1 files changed, 217 insertions, 0 deletions
diff --git a/docs/CommandGuide/llvm2cpp.pod b/docs/CommandGuide/llvm2cpp.pod
new file mode 100644
index 0000000..4b86ae0
--- /dev/null
+++ b/docs/CommandGuide/llvm2cpp.pod
@@ -0,0 +1,217 @@
+=pod
+
+=head1 NAME
+
+llvm2xpp - LLVM bitcode to LLVM C++ IR translator
+
+=head1 SYNOPSIS
+
+B<llvm2cpp> [I<options>] [I<filename>]
+
+=head1 DESCRIPTION
+
+B<llvm2cpp> translates from LLVM bitcode (.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