docs/CommandGuide/llvm2cpp.pod - platform/external/llvm - Git at Google

 =pod

 =head1 NAME

 llvm2xpp - LLVM bytecode to LLVM C++ IR translator

 =head1 SYNOPSIS

 B<llvm2cpp> [I<options>] [I<filename>]

 =head1 DESCRIPTION

 B<llvm2cpp> translates from LLVM bytecode (.bc files) to a
 corresponding C++ source file that will make calls against the LLVM C++ API to
 build the same module as the input. By default, the C++ output is a complete
 program that builds the module, verifies it and then emits the module as
 LLVM assembly. This technique assists with testing because the input to
 B<llvm2cpp> and the output of the generated C++ program should be identical.

 If F<filename> is omitted or is C<->, then B<llvm2cpp> reads its input from
 standard input.

 If an output file is not specified with the B<-o> option, then
 B<llvm2cpp> sends its output to a file or standard output by following
 these rules:

 =over

 =item *

 If the input is standard input, then the output is standard output.

 =item *

 If the input is a file that ends with C<.bc>, then the output file is of
 the same name, except that the suffix is changed to C<.cpp>.

 =item *

 If the input is a file that does not end with the C<.bc> suffix, then the
 output file has the same name as the input file, except that the C<.cpp>
 suffix is appended.

 =back

 =head1 OPTIONS

 =over

 =item B<-f>

 Force overwrite.  Normally, B<llvm2cpp> will refuse to overwrite an
 output file that already exists.  With this option, B<llvm2cpp>
 will overwrite the output file and replace it with new C++ source code.

 =item B<--help>

 Print a summary of command line options.

 =item B<-f>

 Normally, B<llvm2cpp> will not overwrite an existing output file. With this
 option, that default behavior is changed and the program will overwrite existing
 output files.

 =item B<-o> F<filename>

 Specify the output file name.  If F<filename> is C<->, then B<llvm2cpp>
 sends its output to standard output.

 =item B<-funcname> F<functionName>

 Specify the name of the function to be generated. The generated code contains a
 single function that produces the input module. By default its name is
 I<makeLLVMModule>. The B<-funcname> option overrides this default and allows
 you to control the name of the generated function. This is handy in conjunction
 with the B<-fragment> option when you only want B<llvm2cpp> to generate a
 single function that produces the module. With both options, such generated code
 could be I<#included> into another program.

 =item B<-for>

 Specify the name of the thing for which C++ code should be generated. By default
 the entire input module is re-generated. However, use of the various B<-gen-*>
 options can restrict what is produced. This option indicates what that
 restriction is.

 =item B<-gen-program>

 Specify that the output should be a complete program. Such program will recreate
 B<llvm2cpp>'s input as an LLVM module, verify that module, and then write out
 the module in LLVM assembly format. This is useful for doing identity tests
 where the output of the generated program is identical to the input to
 B<llvm2cpp>. The LLVM DejaGnu test suite can make use of this fact. This is the
 default form of generated output.

 If the B<-for> option is given with this option, it specifies the module
 identifier to use for the module created.

 =item B<-gen-module>

 Specify that the output should be a function that regenerates the module. It is
 assumed that this output will be #included into another program that has already
 arranged for the correct header files to be #included. The function generated
 takes no arguments and returns a I<Module*>.

 If the B<-for> option is given with this option, it specifies the module
 identifier to use in creating the module returned by the generated function.

 =item B<-gen-contents>

 Specify that the output should be a function that adds the contents of the input
 module to another module. It is assumed that the output will be #included into
 another program that has already arranged for the correct header files to be
 #included. The function generated takes a single argument of type I<Module*> and
 returns that argument. Note that Module level attributes such as endianess,
 pointer size, target triple and inline asm are not passed on from the input
 module to the destination module. Only the sub-elements of the module (types,
 constants, functions, global variables) will be added to the input module.

 If the B<-for> option is given with this option, it specifies the module
 identifier to set in the input module by the generated function.

 =item B<-gen-function>

 Specify that the output should be a function that produces the definitions
 necessary for a specific function to be added to a module.  It is assumed that
 the output will be #included into another program that has already arranged
 for the correct header files to be #included. The function generated takes a
 single argument of type I<Module*> and returns the I<Function*> that it added to
 the module.  Note that only those things (types, constants, etc.) directly
 needed in the definition of the function will be placed in the generated
 function.

 The B<-for> option must be given with this option or an error will be produced.
 The value of the option must be the name of a function in the input module for
 which code should be generated. If the named function does not exist an error
 will be produced.

 =item B<-gen-inline>

 This option is very analagous to B<-gen-function> except that the generated
 function will not re-produce the target function's definition. Instead, the body
 of the target function is inserted into some other function passed as an
 argument to the generated function. Similarly any arguments to the function must
 be passed to the generated function. The result of the generated function is the
 first basic block of the target function.

 The B<-for> option works the same way as it does for B<-gen-function>.

 =item B<-gen-variable>

 Specify that the output should be a function that produces the definitions
 necessary for a specific global variable to be added to a module. It is assumed
 that the output will be #included into another program that has already arranged
 for the correct header files to be #included. The function generated takes a
 single argument of type I<Module*> and returns the I<GlobalVariable*> that it
 added to the module. Note that only those things (types, constants, etc.)
 directly needed in the definition of the global variable will be placed in the
 generated function.

 The B<-for> option must be given with this option or an error will be produced.
 THe value of the option must be the name of a global variable in the input
 module for which code should be generated. If the named global variable does not
 exist an error will be produced.

 =item B<-gen-type>

 Specify that the output should be a function that produces the definitions
 necessary for specific type to be added to a module. It is assumed that the
 otuput will be #included into another program that has already arranged for the
 correct header files to be #included. The function generated take a single
 argument of type I<Module*> and returns the I<Type*> that it added to the
 module. Note that the generated function will only add the necessary type
 definitions to (possibly recursively) define the requested type.

 The B<-for> option must be given with this option or an error will be produced.
 The value of the option must be the name of a global type in the input module
 for which code should be generated. If the named type does not exist an error
 will be produced.

 =item B<-stats>

 Show pass statistics (not interesting in this program).

 =item B<-time-passes>

 Show pass timing statistics (not interesting in this program).

 =item B<-version>

 Show the version number of this program.

 =back


 =head1 EXIT STATUS

 If B<llvm2cpp> succeeds, it will exit with 0.  Otherwise, if an error
 occurs, it will exit with a non-zero value.

 =head1 SEE ALSO

 L<llvm-as|llvm-as> L<tblgen|tblgen>

 =head1 NOTES

 This tool may be removed from a future version of LLVM. Instead, its
 functionality may be incorporated into the llc tool. It would then act similarly
 to other targets except its output would be C++ source that could be compiled to
 construct the input program.

 =head1 AUTHORS

 Written by Reid Spencer (L<http://hlvm.org>).

 =cut
	=pod

	=head1 NAME

	llvm2xpp - LLVM bytecode to LLVM C++ IR translator

	=head1 SYNOPSIS

	B<llvm2cpp> [I<options>] [I<filename>]

	=head1 DESCRIPTION

	B<llvm2cpp> translates from LLVM bytecode (.bc files) to a
	corresponding C++ source file that will make calls against the LLVM C++ API to
	build the same module as the input. By default, the C++ output is a complete
	program that builds the module, verifies it and then emits the module as
	LLVM assembly. This technique assists with testing because the input to
	B<llvm2cpp> and the output of the generated C++ program should be identical.

	If F<filename> is omitted or is C<->, then B<llvm2cpp> reads its input from
	standard input.

	If an output file is not specified with the B<-o> option, then
	B<llvm2cpp> sends its output to a file or standard output by following
	these rules:

	=over

	=item *

	If the input is standard input, then the output is standard output.

	=item *

	If the input is a file that ends with C<.bc>, then the output file is of
	the same name, except that the suffix is changed to C<.cpp>.

	=item *

	If the input is a file that does not end with the C<.bc> suffix, then the
	output file has the same name as the input file, except that the C<.cpp>
	suffix is appended.

	=back

	=head1 OPTIONS

	=over

	=item B<-f>

	Force overwrite. Normally, B<llvm2cpp> will refuse to overwrite an
	output file that already exists. With this option, B<llvm2cpp>
	will overwrite the output file and replace it with new C++ source code.

	=item B<--help>

	Print a summary of command line options.

	=item B<-f>

	Normally, B<llvm2cpp> will not overwrite an existing output file. With this
	option, that default behavior is changed and the program will overwrite existing
	output files.

	=item B<-o> F<filename>

	Specify the output file name. If F<filename> is C<->, then B<llvm2cpp>
	sends its output to standard output.

	=item B<-funcname> F<functionName>

	Specify the name of the function to be generated. The generated code contains a
	single function that produces the input module. By default its name is
	I<makeLLVMModule>. The B<-funcname> option overrides this default and allows
	you to control the name of the generated function. This is handy in conjunction
	with the B<-fragment> option when you only want B<llvm2cpp> to generate a
	single function that produces the module. With both options, such generated code
	could be I<#included> into another program.

	=item B<-for>

	Specify the name of the thing for which C++ code should be generated. By default
	the entire input module is re-generated. However, use of the various B<-gen-*>
	options can restrict what is produced. This option indicates what that
	restriction is.

	=item B<-gen-program>

	Specify that the output should be a complete program. Such program will recreate
	B<llvm2cpp>'s input as an LLVM module, verify that module, and then write out
	the module in LLVM assembly format. This is useful for doing identity tests
	where the output of the generated program is identical to the input to
	B<llvm2cpp>. The LLVM DejaGnu test suite can make use of this fact. This is the
	default form of generated output.

	If the B<-for> option is given with this option, it specifies the module
	identifier to use for the module created.

	=item B<-gen-module>

	Specify that the output should be a function that regenerates the module. It is
	assumed that this output will be #included into another program that has already
	arranged for the correct header files to be #included. The function generated
	takes no arguments and returns a I<Module*>.

	If the B<-for> option is given with this option, it specifies the module
	identifier to use in creating the module returned by the generated function.

	=item B<-gen-contents>

	Specify that the output should be a function that adds the contents of the input
	module to another module. It is assumed that the output will be #included into
	another program that has already arranged for the correct header files to be
	#included. The function generated takes a single argument of type I<Module*> and
	returns that argument. Note that Module level attributes such as endianess,
	pointer size, target triple and inline asm are not passed on from the input
	module to the destination module. Only the sub-elements of the module (types,
	constants, functions, global variables) will be added to the input module.

	If the B<-for> option is given with this option, it specifies the module
	identifier to set in the input module by the generated function.

	=item B<-gen-function>

	Specify that the output should be a function that produces the definitions
	necessary for a specific function to be added to a module. It is assumed that
	the output will be #included into another program that has already arranged
	for the correct header files to be #included. The function generated takes a
	single argument of type I<Module> and returns the I<Function> that it added to
	the module. Note that only those things (types, constants, etc.) directly
	needed in the definition of the function will be placed in the generated
	function.

	The B<-for> option must be given with this option or an error will be produced.
	The value of the option must be the name of a function in the input module for
	which code should be generated. If the named function does not exist an error
	will be produced.

	=item B<-gen-inline>

	This option is very analagous to B<-gen-function> except that the generated
	function will not re-produce the target function's definition. Instead, the body
	of the target function is inserted into some other function passed as an
	argument to the generated function. Similarly any arguments to the function must
	be passed to the generated function. The result of the generated function is the
	first basic block of the target function.

	The B<-for> option works the same way as it does for B<-gen-function>.

	=item B<-gen-variable>

	Specify that the output should be a function that produces the definitions
	necessary for a specific global variable to be added to a module. It is assumed
	that the output will be #included into another program that has already arranged
	for the correct header files to be #included. The function generated takes a
	single argument of type I<Module> and returns the I<GlobalVariable> that it
	added to the module. Note that only those things (types, constants, etc.)
	directly needed in the definition of the global variable will be placed in the
	generated function.

	The B<-for> option must be given with this option or an error will be produced.
	THe value of the option must be the name of a global variable in the input
	module for which code should be generated. If the named global variable does not
	exist an error will be produced.

	=item B<-gen-type>

	Specify that the output should be a function that produces the definitions
	necessary for specific type to be added to a module. It is assumed that the
	otuput will be #included into another program that has already arranged for the
	correct header files to be #included. The function generated take a single
	argument of type I<Module> and returns the I<Type> that it added to the
	module. Note that the generated function will only add the necessary type
	definitions to (possibly recursively) define the requested type.

	The B<-for> option must be given with this option or an error will be produced.
	The value of the option must be the name of a global type in the input module
	for which code should be generated. If the named type does not exist an error
	will be produced.

	=item B<-stats>

	Show pass statistics (not interesting in this program).

	=item B<-time-passes>

	Show pass timing statistics (not interesting in this program).

	=item B<-version>

	Show the version number of this program.

	=back


	=head1 EXIT STATUS

	If B<llvm2cpp> succeeds, it will exit with 0. Otherwise, if an error
	occurs, it will exit with a non-zero value.

	=head1 SEE ALSO

	L<llvm-as\|llvm-as> L<tblgen\|tblgen>

	=head1 NOTES

	This tool may be removed from a future version of LLVM. Instead, its
	functionality may be incorporated into the llc tool. It would then act similarly
	to other targets except its output would be C++ source that could be compiled to
	construct the input program.

	=head1 AUTHORS

	Written by Reid Spencer (L<http://hlvm.org>).

	=cut