docs/CommandGuide/llvm2cpp.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 llvm2xpp - LLVM bitcode to LLVM C++ IR translator
   6
   7 =head1 SYNOPSIS
   8
   9 B<llvm2cpp> [I<options>] [I<filename>]
  10
  11 =head1 DESCRIPTION
  12
  13 B<llvm2cpp> translates from LLVM bitcode (.bc files) to a
  14 corresponding C++ source file that will make calls against the LLVM C++ API to
  15 build the same module as the input. By default, the C++ output is a complete
  16 program that builds the module, verifies it and then emits the module as
  17 LLVM assembly. This technique assists with testing because the input to
  18 B<llvm2cpp> and the output of the generated C++ program should be identical.
  19
  20 If F<filename> is omitted or is C<->, then B<llvm2cpp> reads its input from
  21 standard input.
  22
  23 If an output file is not specified with the B<-o> option, then
  24 B<llvm2cpp> sends its output to a file or standard output by following
  25 these rules:
  26
  27 =over
  28
  29 =item *
  30
  31 If the input is standard input, then the output is standard output.
  32
  33 =item *
  34
  35 If the input is a file that ends with C<.bc>, then the output file is of
  36 the same name, except that the suffix is changed to C<.cpp>.
  37
  38 =item *
  39
  40 If the input is a file that does not end with the C<.bc> suffix, then the
  41 output file has the same name as the input file, except that the C<.cpp>
  42 suffix is appended.
  43
  44 =back
  45
  46 =head1 OPTIONS
  47
  48 =over
  49
  50 =item B<-f>
  51
  52 Force overwrite.  Normally, B<llvm2cpp> will refuse to overwrite an
  53 output file that already exists.  With this option, B<llvm2cpp>
  54 will overwrite the output file and replace it with new C++ source code.
  55
  56 =item B<--help>
  57
  58 Print a summary of command line options.
  59
  60 =item B<-f>
  61
  62 Normally, B<llvm2cpp> will not overwrite an existing output file. With this
  63 option, that default behavior is changed and the program will overwrite existing
  64 output files.
  65
  66 =item B<-o> F<filename>
  67
  68 Specify the output file name.  If F<filename> is C<->, then B<llvm2cpp>
  69 sends its output to standard output.
  70
  71 =item B<-funcname> F<functionName>
  72
  73 Specify the name of the function to be generated. The generated code contains a
  74 single function that produces the input module. By default its name is
  75 I<makeLLVMModule>. The B<-funcname> option overrides this default and allows
  76 you to control the name of the generated function. This is handy in conjunction
  77 with the B<-fragment> option when you only want B<llvm2cpp> to generate a
  78 single function that produces the module. With both options, such generated code
  79 could be I<#included> into another program.
  80
  81 =item B<-for>
  82
  83 Specify the name of the thing for which C++ code should be generated. By default
  84 the entire input module is re-generated. However, use of the various B<-gen-*>
  85 options can restrict what is produced. This option indicates what that
  86 restriction is.
  87
  88 =item B<-gen-program>
  89
  90 Specify that the output should be a complete program. Such program will recreate
  91 B<llvm2cpp>'s input as an LLVM module, verify that module, and then write out
  92 the module in LLVM assembly format. This is useful for doing identity tests
  93 where the output of the generated program is identical to the input to
  94 B<llvm2cpp>. The LLVM DejaGnu test suite can make use of this fact. This is the
  95 default form of generated output.
  96
  97 If the B<-for> option is given with this option, it specifies the module
  98 identifier to use for the module created.
  99
 100 =item B<-gen-module>
 101
 102 Specify that the output should be a function that regenerates the module. It is
 103 assumed that this output will be #included into another program that has already
 104 arranged for the correct header files to be #included. The function generated
 105 takes no arguments and returns a I<Module*>.
 106
 107 If the B<-for> option is given with this option, it specifies the module
 108 identifier to use in creating the module returned by the generated function.
 109
 110 =item B<-gen-contents>
 111
 112 Specify that the output should be a function that adds the contents of the input
 113 module to another module. It is assumed that the output will be #included into
 114 another program that has already arranged for the correct header files to be
 115 #included. The function generated takes a single argument of type I<Module*> and
 116 returns that argument. Note that Module level attributes such as endianess,
 117 pointer size, target triple and inline asm are not passed on from the input
 118 module to the destination module. Only the sub-elements of the module (types,
 119 constants, functions, global variables) will be added to the input module.
 120
 121 If the B<-for> option is given with this option, it specifies the module
 122 identifier to set in the input module by the generated function.
 123
 124 =item B<-gen-function>
 125
 126 Specify that the output should be a function that produces the definitions
 127 necessary for a specific function to be added to a module.  It is assumed that
 128 the output will be #included into another program that has already arranged
 129 for the correct header files to be #included. The function generated takes a
 130 single argument of type I<Module*> and returns the I<Function*> that it added to
 131 the module.  Note that only those things (types, constants, etc.) directly
 132 needed in the definition of the function will be placed in the generated
 133 function.
 134
 135 The B<-for> option must be given with this option or an error will be produced.
 136 The value of the option must be the name of a function in the input module for
 137 which code should be generated. If the named function does not exist an error
 138 will be produced.
 139
 140 =item B<-gen-inline>
 141
 142 This option is very analagous to B<-gen-function> except that the generated
 143 function will not re-produce the target function's definition. Instead, the body
 144 of the target function is inserted into some other function passed as an
 145 argument to the generated function. Similarly any arguments to the function must
 146 be passed to the generated function. The result of the generated function is the
 147 first basic block of the target function.
 148
 149 The B<-for> option works the same way as it does for B<-gen-function>.
 150
 151 =item B<-gen-variable>
 152
 153 Specify that the output should be a function that produces the definitions
 154 necessary for a specific global variable to be added to a module. It is assumed
 155 that the output will be #included into another program that has already arranged
 156 for the correct header files to be #included. The function generated takes a
 157 single argument of type I<Module*> and returns the I<GlobalVariable*> that it
 158 added to the module. Note that only those things (types, constants, etc.)
 159 directly needed in the definition of the global variable will be placed in the
 160 generated function.
 161
 162 The B<-for> option must be given with this option or an error will be produced.
 163 THe value of the option must be the name of a global variable in the input
 164 module for which code should be generated. If the named global variable does not
 165 exist an error will be produced.
 166
 167 =item B<-gen-type>
 168
 169 Specify that the output should be a function that produces the definitions
 170 necessary for specific type to be added to a module. It is assumed that the
 171 otuput will be #included into another program that has already arranged for the
 172 correct header files to be #included. The function generated take a single
 173 argument of type I<Module*> and returns the I<Type*> that it added to the
 174 module. Note that the generated function will only add the necessary type
 175 definitions to (possibly recursively) define the requested type.
 176
 177 The B<-for> option must be given with this option or an error will be produced.
 178 The value of the option must be the name of a global type in the input module
 179 for which code should be generated. If the named type does not exist an error
 180 will be produced.
 181
 182 =item B<-stats>
 183
 184 Show pass statistics (not interesting in this program).
 185
 186 =item B<-time-passes>
 187
 188 Show pass timing statistics (not interesting in this program).
 189
 190 =item B<-version>
 191
 192 Show the version number of this program.
 193
 194 =back
 195
 196
 197 =head1 EXIT STATUS
 198
 199 If B<llvm2cpp> succeeds, it will exit with 0.  Otherwise, if an error
 200 occurs, it will exit with a non-zero value.
 201
 202 =head1 SEE ALSO
 203
 204 L<llvm-as|llvm-as> L<tblgen|tblgen>
 205
 206 =head1 NOTES
 207
 208 This tool may be removed from a future version of LLVM. Instead, its
 209 functionality may be incorporated into the llc tool. It would then act similarly
 210 to other targets except its output would be C++ source that could be compiled to
 211 construct the input program.
 212
 213 =head1 AUTHORS
 214
 215 Written by Reid Spencer (L<http://hlvm.org>).
 216
 217 =cut