llvm.org GIT mirror llvm / fb88665
Regenerate. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@130091 91177308-0d34-0410-b5e6-96231b3b80d8 Mikhail Glushenkov 9 years ago
2 changed file(s) with 415 addition(s) and 485 deletion(s). Raw diff Collapse all Expand all
22
33
44
5
5
66 Customizing LLVMC: Reference Manual
77
88
1616
1717

Contents

1818
19
  • Introduction
  • 20
  • Compiling with LLVMC
  • 21
  • Predefined options
  • 22
  • Compiling LLVMC plugins
  • 23
  • Compiling standalone LLVMC-based drivers
  • 24
  • Customizing LLVMC: the compilation graph
  • 25
  • Describing options
  • 26
  • External options
  • 19
  • Introduction
  • 20
  • Compiling with llvmc
  • 21
  • Predefined options
  • 22
  • Compiling LLVMC-based drivers
  • 23
  • Customizing LLVMC: the compilation graph
  • 24
  • Describing options
  • 25
  • Conditional evaluation
  • 26
  • Writing a tool description
  • 27
  • Actions
  • 2728
    2829
    29
  • Conditional evaluation
  • 30
  • Writing a tool description
  • 31
  • Actions
  • 32
    33
    34
  • Language map
  • 35
  • Option preprocessor
  • 36
  • More advanced topics
  • 37
  • Hooks and environment variables
  • 38
  • How plugins are loaded
  • 39
  • Debugging
  • 40
  • Conditioning on the executable name
  • 30
  • Language map
  • 31
  • Option preprocessor
  • 32
  • More advanced topics
  • 33
  • Hooks and environment variables
  • 34
  • Debugging
  • 35
  • Conditioning on the executable name
  • 4136
    4237
    4338
    4540
    4641

    Written by Mikhail Glushenkov

    4742
    48

    Introduction

    43

    Introduction

    4944

    LLVMC is a generic compiler driver, designed to be customizable and

    50 extensible. It plays the same role for LLVM as the gcc program
    51 does for GCC - LLVMC's job is essentially to transform a set of input
    52 files into a set of targets depending on configuration rules and user
    53 options. What makes LLVMC different is that these transformation rules
    54 are completely customizable - in fact, LLVMC knows nothing about the
    55 specifics of transformation (even the command-line options are mostly
    56 not hard-coded) and regards the transformation structure as an
    57 abstract graph. The structure of this graph is completely determined
    58 by plugins, which can be either statically or dynamically linked. This
    59 makes it possible to easily adapt LLVMC for other purposes - for
    60 example, as a build tool for game resources.

    45 extensible. It plays the same role for LLVM as the gcc program does for
    46 GCC - LLVMC's job is essentially to transform a set of input files into a set of
    47 targets depending on configuration rules and user options. What makes LLVMC
    48 different is that these transformation rules are completely customizable - in
    49 fact, LLVMC knows nothing about the specifics of transformation (even the
    50 command-line options are mostly not hard-coded) and regards the transformation
    51 structure as an abstract graph. The structure of this graph is described in
    52 high-level TableGen code, from which an efficient C++ representation is
    53 automatically derived. This makes it possible to adapt LLVMC for other
    54 purposes - for example, as a build tool for game resources.

    6155

    Because LLVMC employs TableGen as its configuration language, you

    6256 need to be familiar with it to customize LLVMC.

    6357
    6458
    65

    Compiling with LLVMC

    66 <p>LLVMC tries hard to be as compatible with gcc as possible,
    59 <h1>Compiling with llvmc
    60

    LLVMC tries hard to be as compatible with gcc as possible,

    6761 although there are some small differences. Most of the time, however,
    6862 you shouldn't be able to notice them:

    6963
    
                      
                    
    7367 hello
    7468
    7569

    One nice feature of LLVMC is that one doesn't have to distinguish between

    76 different compilers for different languages (think g++ vs. gcc) - the
    70 different compilers for different languages (think g++ vs. gcc) - the
    7771 right toolchain is chosen automatically based on input language names (which
    7872 are, in turn, determined from file extensions). If you want to force files
    7973 ending with ".c" to compile as C++, use the -x option, just like you would
    80 do it with gcc:

    74 do it with gcc:

    8175
    
                      
                    
    8276 $ # hello.c is really a C++ file
    8377 $ llvmc -x c++ hello.c
    9690 hello
    9791
    9892

    By default, LLVMC uses llvm-gcc to compile the source code. It is also

    99 possible to choose the clang compiler with the -clang option.

    93 possible to choose the clang compiler with the -clang option.

    10094
    10195
    102

    Predefined options

    103

    LLVMC has some built-in options that can't be overridden in the

    104 configuration libraries:

    105
    106
  • -o FILE - Output file name.
  • 107 <li>-x LANGUAGE - Specify the language of the following input files
    96 <h1>Predefined options
    97

    LLVMC has some built-in options that can't be overridden in the TableGen code:

    98
    99
  • -o FILE - Output file name.
  • 100
  • -x LANGUAGE - Specify the language of the following input files
  • 108101 until the next -x option.
    109
  • -load PLUGIN_NAME - Load the specified plugin DLL. Example:
  • 110 -load $LLVM_DIR/Release/lib/LLVMCSimple.so.
    111102
  • -v - Enable verbose mode, i.e. print out all executed commands.
  • 112103
  • --save-temps - Write temporary files to the current directory and do not
  • 113104 delete them on exit. This option can also take an argument: the
    114105 --save-temps=obj switch will write files into the directory specified with
    115106 the -o option. The --save-temps=cwd and --save-temps switches are
    116107 both synonyms for the default behaviour.
    117
  • --temp-dir DIRECTORY - Store temporary files in the given directory. This
  • 108
  • --temp-dir DIRECTORY - Store temporary files in the given directory. This
  • 118109 directory is deleted on exit unless --save-temps is specified. If
    119110 --save-temps=obj is also specified, --temp-dir is given the
    120111 precedence.
    121112
  • --check-graph - Check the compilation for common errors like mismatched
  • 122 output/input language names, multiple default edges and cycles. Because of
    123 plugins, these checks can't be performed at compile-time. Exit with code zero
    124 if no errors were found, and return the number of found errors
    125 otherwise. Hidden option, useful for debugging LLVMC plugins.
    113 output/input language names, multiple default edges and cycles. Exit with code
    114 zero if no errors were found, and return the number of found errors
    115 otherwise. Hidden option, useful for debugging.
    126116
  • --view-graph - Show a graphical representation of the compilation graph
  • 127 and exit. Requires that you have dot and gv programs installed. Hidden
    128 option, useful for debugging LLVMC plugins.
    117 and exit. Requires that you have dot and gv programs installed. Hidden
    118 option, useful for debugging.
    129119
  • --write-graph - Write a compilation-graph.dot file in the current
  • 130120 directory with the compilation graph description in Graphviz format (identical
    131121 to the file used by the --view-graph option). The -o option can be
    132 used to set the output file name. Hidden option, useful for debugging LLVMC
    133 plugins.
    134
  • -help, -help-hidden, --version - These options have
  • 122 used to set the output file name. Hidden option, useful for debugging.
    123
  • --help, --help-hidden, --version - These options have
  • 135124 their standard meaning.
    136125
    137126
    138
    139

    Compiling LLVMC plugins

    140

    It's easiest to start working on your own LLVMC plugin by copying the

    141 skeleton project which lives under $LLVMC_DIR/plugins/Simple:

    142
    
                      
                    
    143 $ cd $LLVMC_DIR/plugins
    144 $ cp -r Simple MyPlugin
    145 $ cd MyPlugin
    127
    128

    Compiling LLVMC-based drivers

    129

    It's easiest to start working on your own LLVMC driver by copying the skeleton

    130 project which lives under $LLVMC_DIR/examples/Skeleton:

    131
    
                      
                    
    132 $ cd $LLVMC_DIR/examples
    133 $ cp -r Skeleton MyDriver
    134 $ cd MyDriver
    146135 $ ls
    147 Makefile PluginMain.cpp Simple.td
    148
    149

    As you can see, our basic plugin consists of only two files (not

    150 counting the build script). Simple.td contains TableGen
    151 description of the compilation graph; its format is documented in the
    152 following sections. PluginMain.cpp is just a helper file used to
    153 compile the auto-generated C++ code produced from TableGen source. It
    154 can also contain hook definitions (see below).

    155

    The first thing that you should do is to change the LLVMC_PLUGIN

    156 variable in the Makefile to avoid conflicts (since this variable
    157 is used to name the resulting library):

    158
    
                      
                    
    159 LLVMC_PLUGIN=MyPlugin
    160
    161

    It is also a good idea to rename Simple.td to something less

    162 generic:

    163
    
                      
                    
    164 $ mv Simple.td MyPlugin.td
    165
    166

    To build your plugin as a dynamic library, just cd to its source

    167 directory and run make. The resulting file will be called
    168 plugin_llvmc_$(LLVMC_PLUGIN).$(DLL_EXTENSION) (in our case,
    169 plugin_llvmc_MyPlugin.so). This library can be then loaded in with the
    170 -load option. Example:

    171
    
                      
                    
    172 $ cd $LLVMC_DIR/plugins/Simple
    173 $ make
    174 $ llvmc -load $LLVM_DIR/Release/lib/plugin_llvmc_Simple.so
    175
    176
    177
    178

    Compiling standalone LLVMC-based drivers

    179

    By default, the llvmc executable consists of a driver core plus several

    180 statically linked plugins (Base and Clang at the moment). You can
    181 produce a standalone LLVMC-based driver executable by linking the core with your
    182 own plugins. The recommended way to do this is by starting with the provided
    183 Skeleton example ($LLVMC_DIR/example/Skeleton):

    184
    
                      
                    
    185 $ cd $LLVMC_DIR/example/
    186 $ cp -r Skeleton mydriver
    187 $ cd mydriver
    188 $ vim Makefile
    136 AutoGenerated.td Hooks.cpp Main.cpp Makefile
    137
    138

    As you can see, our basic driver consists of only three files (not counting the

    139 build script). AutoGenerated.td contains TableGen description of the
    140 compilation graph; its format is documented in the following
    141 sections. Hooks.cpp is an empty file that should be used for hook
    142 definitions (see below). Main.cpp is just a helper used to compile the
    143 auto-generated C++ code produced from TableGen source.

    144

    The first thing that you should do is to change the LLVMC_BASED_DRIVER

    145 variable in the Makefile:

    146
    
                      
                    
    147 LLVMC_BASED_DRIVER=MyDriver
    148
    149

    It can also be a good idea to put your TableGen code into a file with a less

    150 generic name:

    151
    
                      
                    
    152 $ touch MyDriver.td
    153 $ vim AutoGenerated.td
    189154 [...]
    190 $ make
    191
    155 include "MyDriver.td"
    156
    157

    If you have more than one TableGen source file, they all should be included from

    158 AutoGenerated.td, since this file is used by the build system to generate
    159 C++ code.

    160

    To build your driver, just cd to its source directory and run make. The

    161 resulting executable will be put into $LLVM_OBJ_DIR/$(BuildMode)/bin.

    192162

    If you're compiling LLVM with different source and object directories, then you

    193 must perform the following additional steps before running make:

    163 must perform the following additional steps before running make:

    194164
    
                      
                    
    195165 # LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/
    196166 # LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/
    197 $ cp $LLVMC_SRC_DIR/example/mydriver/Makefile \
    198 $LLVMC_OBJ_DIR/example/mydriver/
    199 $ cd $LLVMC_OBJ_DIR/example/mydriver
    167 $ mkdir $LLVMC_OBJ_DIR/examples/MyDriver/
    168 $ cp $LLVMC_SRC_DIR/examples/MyDriver/Makefile \
    169 $LLVMC_OBJ_DIR/examples/MyDriver/
    170 $ cd $LLVMC_OBJ_DIR/examples/MyDriver
    200171 $ make
    201172
    202

    Another way to do the same thing is by using the following command:

    203
    
                      
                    
    204 $ cd $LLVMC_DIR
    205 $ make LLVMC_BUILTIN_PLUGINS=MyPlugin LLVMC_BASED_DRIVER_NAME=mydriver
    206
    207

    This works with both srcdir == objdir and srcdir != objdir, but assumes that the

    208 plugin source directory was placed under $LLVMC_DIR/plugins.

    209

    Sometimes, you will want a 'bare-bones' version of LLVMC that has no

    210 built-in plugins. It can be compiled with the following command:

    211
    
                      
                    
    212 $ cd $LLVMC_DIR
    213 $ make LLVMC_BUILTIN_PLUGINS=""
    214
    215173
    216174
    217

    Customizing LLVMC: the compilation graph

    218

    Each TableGen configuration file should include the common

    219 definitions:>
    175

    Customizing LLVMC: the compilation graph>

    176

    Each TableGen configuration file should include the common definitions:

    220177
    
                      
                    
    221178 include "llvm/CompilerDriver/Common.td"
    222179
    223

    Internally, LLVMC stores information about possible source

    224 transformations in form of a graph. Nodes in this graph represent
    225 tools, and edges between two nodes represent a transformation path. A
    226 special "root" node is used to mark entry points for the
    227 transformations. LLVMC also assigns a weight to each edge (more on
    228 this later) to choose between several alternative edges.

    229

    The definition of the compilation graph (see file

    230 <tt class="docutils literal">plugins/Base/Base.td for an example) is just a list of edges:

    180 <p>Internally, LLVMC stores information about possible source transformations in
    181 form of a graph. Nodes in this graph represent tools, and edges between two
    182 nodes represent a transformation path. A special "root" node is used to mark
    183 entry points for the transformations. LLVMC also assigns a weight to each edge
    184 (more on this later) to choose between several alternative edges.

    185

    The definition of the compilation graph (see file llvmc/src/Base.td for an

    186 example) is just a list of edges:

    231187
    
                      
                    
    232188 def CompilationGraph : CompilationGraph<[
    233189 Edge<"root", "llvm_gcc_c">,
    252208
    253209 ]>;
    254210
    255

    As you can see, the edges can be either default or optional, where

    256 optional edges are differentiated by an additional case expression
    257 used to calculate the weight of this edge. Notice also that we refer
    258 to tools via their names (as strings). This makes it possible to add
    259 edges to an existing compilation graph in plugins without having to
    260 know about all tool definitions used in the graph.

    261

    The default edges are assigned a weight of 1, and optional edges get a

    262 weight of 0 + 2*N where N is the number of tests that evaluated to
    263 true in the case expression. It is also possible to provide an
    264 integer parameter to inc_weight and dec_weight - in this case,
    265 the weight is increased (or decreased) by the provided value instead
    266 of the default 2. It is also possible to change the default weight of
    267 an optional edge by using the default clause of the case
    211

    As you can see, the edges can be either default or optional, where optional

    212 edges are differentiated by an additional case expression used to calculate
    213 the weight of this edge. Notice also that we refer to tools via their names (as
    214 strings). This makes it possible to add edges to an existing compilation graph
    215 without having to know about all tool definitions used in the graph.

    216

    The default edges are assigned a weight of 1, and optional edges get a weight of

    217 0 + 2*N where N is the number of tests that evaluated to true in the case
    218 expression. It is also possible to provide an integer parameter to
    219 inc_weight and dec_weight - in this case, the weight is increased (or
    220 decreased) by the provided value instead of the default 2. Default weight of an
    221 optional edge can be changed by using the default clause of the case
    268222 construct.

    269

    When passing an input file through the graph, LLVMC picks the edge

    270 with the maximum weight. To avoid ambiguity, there should be only one
    271 default edge between two nodes (with the exception of the root node,
    272 which gets a special treatment - there you are allowed to specify one
    273 default edge per language).

    274

    When multiple plugins are loaded, their compilation graphs are merged

    275 together. Since multiple edges that have the same end nodes are not
    276 allowed (i.e. the graph is not a multigraph), an edge defined in
    277 several plugins will be replaced by the definition from the plugin
    278 that was loaded last. Plugin load order can be controlled by using the
    279 plugin priority feature described above.

    280

    To get a visual representation of the compilation graph (useful for

    281 debugging), run llvmc --view-graph. You will need dot and
    282 <tt class="docutils literal">gsview installed for this to work properly.

    223 <p>When passing an input file through the graph, LLVMC picks the edge with the
    224 maximum weight. To avoid ambiguity, there should be only one default edge
    225 between two nodes (with the exception of the root node, which gets a special
    226 treatment - there you are allowed to specify one default edge per language).

    227

    When multiple compilation graphs are defined, they are merged together. Multiple

    228 edges with the same end nodes are not allowed (i.e. the graph is not a
    229 multigraph), and will lead to a compile-time error.

    230

    To get a visual representation of the compilation graph (useful for debugging),

    231 run llvmc --view-graph. You will need dot and gsview installed for
    232 this to work properly.

    283233
    284234
    285

    Describing options

    286

    Command-line options that the plugin supports are defined by using an

    287 <tt class="docutils literal">OptionList:>
    235 <h1>Describing options>
    236

    Command-line options supported by the driver are defined by using an

    237 OptionList:

    288238
    
                      
                    
    289239 def Options : OptionList<[
    290240 (switch_option "E", (help "Help string")),
    292242 ...
    293243 ]>;
    294244
    295

    As you can see, the option list is just a list of DAGs, where each DAG

    296 is an option description consisting of the option name and some
    297 properties. A plugin can define more than one option list (they are
    298 all merged together in the end), which can be handy if one wants to
    299 separate option groups syntactically.

    245

    As you can see, the option list is just a list of DAGs, where each DAG is an

    246 option description consisting of the option name and some properties. More than
    247 one option list can be defined (they are all merged together in the end), which
    248 can be handy if one wants to separate option groups syntactically.

    300249
    301250
  • Possible option types:

  • 302251
    303252
    304
  • switch_option - a simple boolean switch without arguments, for example
  • 305 -O2 or -time. At most one occurrence is allowed.
    306
  • parameter_option - option that takes one argument, for example
  • 253
  • switch_option - a simple boolean switch without arguments, for example
  • 254 -O2 or -time. At most one occurrence is allowed by default.
    255
  • parameter_option - option that takes one argument, for example
  • 307256 -std=c99. It is also allowed to use spaces instead of the equality
    308 sign: -std c99. At most one occurrence is allowed.
    309
  • parameter_list_option - same as the above, but more than one option
  • 257 sign: -std c99. At most one occurrence is allowed.
    258
  • parameter_list_option - same as the above, but more than one option
  • 310259 occurrence is allowed.
    311
  • prefix_option - same as the parameter_option, but the option name and
  • 260
  • prefix_option - same as the parameter_option, but the option name and
  • 312261 argument do not have to be separated. Example: -ofile. This can be also
    313 specified as -o file; however, -o=file will be parsed incorrectly
    314 (=file will be interpreted as option value). At most one occurrence is
    262 specified as -o file; however, -o=file will be parsed incorrectly
    263 (=file will be interpreted as option value). At most one occurrence is
    315264 allowed.
    316
  • prefix_list_option - same as the above, but more than one occurrence of
  • 265
  • prefix_list_option - same as the above, but more than one occurrence of
  • 317266 the option is allowed; example: -lm -lpthread.
    318
  • alias_option - a special option type for creating aliases. Unlike other
  • 267
  • alias_option - a special option type for creating aliases. Unlike other
  • 319268 option types, aliases are not allowed to have any properties besides the
    320 aliased option name. Usage example: (alias_option "preprocess", "E")
    269 aliased option name.
    270 Usage example: (alias_option "preprocess", "E")
    271
  • switch_list_option - like switch_option with the zero_or_more
  • 272 property, but remembers how many times the switch was turned on. Useful
    273 mostly for forwarding. Example: when -foo is a switch option (with the
    274 zero_or_more property), the command driver -foo -foo is forwarded
    275 as some-tool -foo, but when -foo is a switch list, the same command
    276 is forwarded as some-tool -foo -foo.
    321277
    322278
    323279
    324280
  • Possible option properties:

  • 325281
    326282
    327
  • help - help string associated with this option. Used for -help
  • 283
  • help - help string associated with this option. Used for --help
  • 328284 output.
    329
  • required - this option must be specified exactly once (or, in case of
  • 330 the list options without the multi_val property, at least
    331 once). Incompatible with zero_or_one and one_or_more.
    332
  • one_or_more - the option must be specified at least one time. Useful
  • 333 only for list options in conjunction with multi_val; for ordinary lists
    334 it is synonymous with required. Incompatible with required and
    335 zero_or_one.
    336
  • optional - the option can be specified zero or one times. Useful only
  • 337 for list options in conjunction with multi_val. Incompatible with
    338 required and one_or_more.
    339
  • hidden - the description of this option will not appear in
  • 340 the -help output (but will appear in the -help-hidden
    285
  • required - this option must be specified exactly once (or, in case of
  • 286 the list options without the multi_val property, at least
    287 once). Incompatible with optional and one_or_more.
    288
  • optional - the option can be specified either zero times or exactly
  • 289 once. The default for switch options. Useful only for list options in
    290 conjunction with multi_val. Incompatible with required,
    291 zero_or_more and one_or_more.
    292
  • one_or_more - the option must be specified at least once. Can be useful
  • 293 to allow switch options be both obligatory and be specified multiple
    294 times. For list options is useful only in conjunction with multi_val;
    295 for ordinary it is synonymous with required. Incompatible with
    296 required, optional and zero_or_more.
    297
  • zero_or_more - the option can be specified zero or more times. Useful
  • 298 to allow a single switch option to be specified more than
    299 once. Incompatible with required, optional and one_or_more.
    300
  • hidden - the description of this option will not appear in
  • 301 the --help output (but will appear in the --help-hidden
    341302 output).
    342
  • really_hidden - the option will not be mentioned in any help
  • 303
  • really_hidden - the option will not be mentioned in any help
  • 343304 output.
    344
  • comma_separated - Indicates that any commas specified for an option's
  • 305
  • comma_separated - Indicates that any commas specified for an option's
  • 345306 value should be used to split the value up into multiple values for the
    346307 option. This property is valid only for list options. In conjunction with
    347 forward_value can be used to implement option forwarding in style of
    308 forward_value can be used to implement option forwarding in style of
    348309 gcc's -Wa,.
    349
  • multi_val n - this option takes n arguments (can be useful in some
  • 350 special cases). Usage example: (parameter_list_option "foo", (multi_val
    351 3)); the command-line syntax is '-foo a b c'. Only list options can have
    352 this attribute; you can, however, use the one_or_more, optional
    353 and required properties.
    354
  • init - this option has a default value, either a string (if it is a
  • 310
  • multi_val n - this option takes n arguments (can be useful in some
  • 311 special cases). Usage example: (parameter_list_option "foo", (multi_val
    312 3)); the command-line syntax is '-foo a b c'. Only list options can have
    313 this attribute; you can, however, use the one_or_more, optional
    314 and required properties.
    315
  • init - this option has a default value, either a string (if it is a
  • 355316 parameter), or a boolean (if it is a switch; as in C++, boolean constants
    356 are called true and false). List options can't have init
    317 are called true and false). List options can't have init
    357318 attribute.
    358 Usage examples: (switch_option "foo", (init true)); (prefix_option
    359 "bar", (init "baz")).
    360
  • extern - this option is defined in some other plugin, see below.
  • 319 Usage examples: (switch_option "foo", (init true)); (prefix_option
    320 "bar", (init "baz")).
    361321
    362322
    363323
    364324
    365
    366

    External options

    367

    Sometimes, when linking several plugins together, one plugin needs to

    368 access options defined in some other plugin. Because of the way
    369 options are implemented, such options must be marked as
    370 extern. This is what the extern option property is
    371 for. Example:

    372
    
                      
                    
    373 ...
    374 (switch_option "E", (extern))
    375 ...
    376
    377

    If an external option has additional attributes besides 'extern', they are

    378 ignored. See also the section on plugin priorities.

    379
    380325
    381326
    382

    Conditional evaluation

    383

    The 'case' construct is the main means by which programmability is

    384 achieved in LLVMC. It can be used to calculate edge weights, program
    385 actions and modify the shell commands to be executed. The 'case'
    386 expression is designed after the similarly-named construct in
    387 functional languages and takes the form (case (test_1), statement_1,
    388 (test_2), statement_2, ... (test_N), statement_N). The statements
    389 are evaluated only if the corresponding tests evaluate to true.>
    327

    Conditional evaluation>

    328

    The 'case' construct is the main means by which programmability is achieved in

    329 LLVMC. It can be used to calculate edge weights, program actions and modify the
    330 shell commands to be executed. The 'case' expression is designed after the
    331 similarly-named construct in functional languages and takes the form (case
    332 (test_1), statement_1, (test_2), statement_2, ... (test_N), statement_N). The
    333 statements are evaluated only if the corresponding tests evaluate to true.

    390334

    Examples:

    391335
    
                      
                    
    392336 // Edge weight calculation
    409353 (switch_on "B"), "cmdline2",
    410354 (default), "cmdline3")
    411355
    412

    Note the slight difference in 'case' expression handling in contexts

    413 of edge weights and command line specification - in the second example
    414 the value of the "B" switch is never checked when switch "A" is
    415 enabled, and the whole expression always evaluates to "cmdline1" in
    416 that case.

    356

    Note the slight difference in 'case' expression handling in contexts of edge

    357 weights and command line specification - in the second example the value of the
    358 "B" switch is never checked when switch "A" is enabled, and the whole
    359 expression always evaluates to "cmdline1" in that case.

    417360

    Case expressions can also be nested, i.e. the following is legal:

    418361
    
                      
                    
    419362 (case (switch_on "E"), (case (switch_on "o"), ..., (default), ...)
    420363 (default), ...)
    421364
    422

    You should, however, try to avoid doing that because it hurts

    423 readability. It is usually better to split tool descriptions and/or
    424 use TableGen inheritance instead.

    365

    You should, however, try to avoid doing that because it hurts readability. It is

    366 usually better to split tool descriptions and/or use TableGen inheritance
    367 instead.

    425368
    426369
  • Possible tests are:
  • 427
  • switch_on - Returns true if a given command-line switch is provided by
  • 428 the user. Can be given a list as argument, in that case (switch_on ["foo",
    429 "bar", "baz"]) is equivalent to (and (switch_on "foo"), (switch_on
    430 "bar"), (switch_on "baz")).
    431 Example: (switch_on "opt").
    432
  • any_switch_on - Given a list of switch options, returns true if any of
  • 370
  • switch_on - Returns true if a given command-line switch is provided by
  • 371 the user. Can be given multiple arguments, in that case (switch_on "foo",
    372 "bar", "baz") is equivalent to (and (switch_on "foo"), (switch_on
    373 "bar"), (switch_on "baz")).
    374 Example: (switch_on "opt").
    375
  • any_switch_on - Given a number of switch options, returns true if any of
  • 433376 the switches is turned on.
    434 Example: (any_switch_on ["foo", "bar", "baz"]) is equivalent to (or
    435 (switch_on "foo"), (switch_on "bar"), (switch_on "baz")).
    436
  • parameter_equals - Returns true if a command-line parameter equals
  • 437 a given value.
    438 Example: (parameter_equals "W", "all").
    439
  • element_in_list - Returns true if a command-line parameter
  • 440 list contains a given value.
    441 Example: (element_in_list "l", "pthread").
    442
  • input_languages_contain - Returns true if a given language
  • 377 Example: (any_switch_on "foo", "bar", "baz") is equivalent to (or
    378 (switch_on "foo"), (switch_on "bar"), (switch_on "baz")).
    379
  • parameter_equals - Returns true if a command-line parameter (first
  • 380 argument) equals a given value (second argument).
    381 Example: (parameter_equals "W", "all").
    382
  • element_in_list - Returns true if a command-line parameter list (first
  • 383 argument) contains a given value (second argument).
    384 Example: (element_in_list "l", "pthread").
    385
  • input_languages_contain - Returns true if a given language
  • 443386 belongs to the current input language set.
    444 Example: (input_languages_contain "c++").
    445
  • in_language - Evaluates to true if the input file language is equal to
  • 446 the argument. At the moment works only with cmd_line and actions (on
    387 Example: (input_languages_contain "c++").
    388
  • in_language - Evaluates to true if the input file language is equal to
  • 389 the argument. At the moment works only with command and actions (on
    447390 non-join nodes).
    448 Example: (in_language "c++").
    449
  • not_empty - Returns true if a given option (which should be either a
  • 450 parameter or a parameter list) is set by the user. Like switch_on, can
    451 be also given a list as argument.
    452 Example: (not_empty "o").
    453
  • any_not_empty - Returns true if not_empty returns true for any of
  • 454 the options in the list.
    455 Example: (any_not_empty ["foo", "bar", "baz"]) is equivalent to (or
    456 (not_empty "foo"), (not_empty "bar"), (not_empty "baz")).
    457
  • empty - The opposite of not_empty. Equivalent to (not (not_empty
  • 458 X)). Provided for convenience. Can be given a list as argument.
    459
  • any_not_empty - Returns true if not_empty returns true for any of
  • 460 the options in the list.
    461 Example: (any_empty ["foo", "bar", "baz"]) is equivalent to (not (and
    462 (not_empty "foo"), (not_empty "bar"), (not_empty "baz"))).
    463
  • single_input_file - Returns true if there was only one input file
  • 391 Example: (in_language "c++").
    392
  • not_empty - Returns true if a given option (which should be either a
  • 393 parameter or a parameter list) is set by the user. Like switch_on, can
    394 be also given multiple arguments.
    395 Examples: (not_empty "o"), (not_empty "o", "l").
    396
  • any_not_empty - Returns true if not_empty returns true for any of
  • 397 the provided options.
    398 Example: (any_not_empty "foo", "bar", "baz") is equivalent to (or
    399 (not_empty "foo"), (not_empty "bar"), (not_empty "baz")).
    400
  • empty - The opposite of not_empty. Equivalent to (not (not_empty
  • 401 X)). Can be given multiple arguments.
    402
  • any_not_empty - Returns true if not_empty returns true for any of
  • 403 the provided options.
    404 Example: (any_empty "foo", "bar", "baz") is equivalent to (or
    405 (not_empty "foo"), (not_empty "bar"), (not_empty "baz")).
    406
  • single_input_file - Returns true if there was only one input file
  • 464407 provided on the command-line. Used without arguments:
    465 (single_input_file).
    466 <li>multiple_input_files - Equivalent to (not (single_input_file)) (the
    408 <tt class="docutils literal">(single_input_file).
    409
  • multiple_input_files - Equivalent to (not (single_input_file)) (the
  • 467410 case of zero input files is considered an error).
    468
  • default - Always evaluates to true. Should always be the last
  • 469 test in the case expression.
    470
  • and - A standard binary logical combinator that returns true iff all of
  • 471 its arguments return true. Used like this: (and (test1), (test2),
    472 <span class="pre">... (testN)). Nesting of and and or is allowed, but not
    411 <li>default - Always evaluates to true. Should always be the last
    412 test in the case expression.
    413
  • and - A standard logical combinator that returns true iff all of
  • 414 its arguments return true. Used like this: (and (test1), (test2),
    415 ... (testN)). Nesting of and and or is allowed, but not
    473416 encouraged.
    474
  • or - A binary logical combinator that returns true iff any of its
  • 475 arguments returns true. Example: (or (test1), (test2), ... (testN)).
    476
  • not - Standard unary logical combinator that negates its
  • 477 argument. Example: (not (or (test1), (test2), ... (testN))).
    417
  • or - A logical combinator that returns true iff any of its arguments
  • 418 return true.
    419 Example: (or (test1), (test2), ... (testN)).
    420
  • not - Standard unary logical combinator that negates its
  • 421 argument.
    422 Example: (not (or (test1), (test2), ... (testN))).
    478423
    479424
    480425
    481426
    482427
    483

    Writing a tool description

    484

    As was said earlier, nodes in the compilation graph represent tools,

    485 which are described separately. A tool definition looks like this
    486 (taken from the include/llvm/CompilerDriver/Tools.td file):>
    428

    Writing a tool description>

    429

    As was said earlier, nodes in the compilation graph represent tools, which are

    430 described separately. A tool definition looks like this (taken from the
    431 llvmc/src/Base.td file):

    487432
    
                      
                    
    488433 def llvm_gcc_cpp : Tool<[
    489434 (in_language "c++"),
    490435 (out_language "llvm-assembler"),
    491436 (output_suffix "bc"),
    492 (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
    437 (command "llvm-g++ -c -emit-llvm"),
    493438 (sink)
    494439 ]>;
    495440
    496

    This defines a new tool called llvm_gcc_cpp, which is an alias for

    497 llvm-g++. As you can see, a tool definition is just a list of
    498 properties; most of them should be self-explanatory. The sink
    499 property means that this tool should be passed all command-line
    500 options that aren't mentioned in the option list.

    441

    This defines a new tool called llvm_gcc_cpp, which is an alias for

    442 llvm-g++. As you can see, a tool definition is just a list of properties;
    443 most of them should be self-explanatory. The sink property means that this
    444 tool should be passed all command-line options that aren't mentioned in the
    445 option list.

    501446

    The complete list of all currently implemented tool properties follows.

    502447
    503448
  • Possible tool properties:
  • 504
  • in_language - input language name. Can be either a string or a
  • 505 list, in case the tool supports multiple input languages.
    506
  • out_language - output language name. Multiple output languages are not
  • 507 allowed.
    508
  • output_suffix - output file suffix. Can also be changed
  • 509 dynamically, see documentation on actions.
    510
  • cmd_line - the actual command used to run the tool. You can
  • 511 use $INFILE and $OUTFILE variables, output redirection
    512 with >, hook invocations ($CALL), environment variables
    513 (via $ENV) and the case construct.
    514
  • join - this tool is a "join node" in the graph, i.e. it gets a
  • 515 list of input files and joins them together. Used for linkers.
    516
  • sink - all command-line options that are not handled by other
  • 517 tools are passed to this tool.
    518
  • actions - A single big case expression that specifies how
  • 519 this tool reacts on command-line options (described in more detail
    520 <a class="reference internal" href="#actions">below).
    449 <li>in_language - input language name. Can be given multiple arguments, in
    450 case the tool supports multiple input languages. Used for typechecking and
    451 mapping file extensions to tools.
    452
  • out_language - output language name. Multiple output languages are
  • 453 allowed. Used for typechecking the compilation graph.
    454
  • output_suffix - output file suffix. Can also be changed dynamically, see
  • 455 documentation on actions.
    521456
    522457
    523458
    524
    525

    Actions

    526

    A tool often needs to react to command-line options, and this is

    527 precisely what the actions property is for. The next example
    528 illustrates this feature:>
    459 >
    460
    461
  • command - the actual command used to run the tool. You can use output
  • 462 redirection with >, hook invocations ($CALL), environment variables
    463 (via $ENV) and the case construct.
    464
  • join - this tool is a "join node" in the graph, i.e. it gets a list of
  • 465 input files and joins them together. Used for linkers.
    466
  • sink - all command-line options that are not handled by other tools are
  • 467 passed to this tool.
    468
  • actions - A single big case expression that specifies how this tool
  • 469 reacts on command-line options (described in more detail below).
    470
    471
    472
    473
    474
  • out_file_option, in_file_option - Options appended to the
  • 475 command string to designate output and input files. Default values are
    476 "-o" and "", respectively.
    477
    478
    479
    480

    Actions

    481

    A tool often needs to react to command-line options, and this is precisely what

    482 the actions property is for. The next example illustrates this feature:

    529483
    
                      
                    
    530484 def llvm_gcc_linker : Tool<[
    531485 (in_language "object-code"),
    532486 (out_language "executable"),
    533487 (output_suffix "out"),
    534 (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
    488 (command "llvm-gcc"),
    535489 (join),
    536490 (actions (case (not_empty "L"), (forward "L"),
    537491 (not_empty "l"), (forward "l"),
    539493 [(append_cmd "-dummy1"), (append_cmd "-dummy2")])
    540494 ]>;
    541495
    542

    The actions tool property is implemented on top of the omnipresent

    543 case expression. It associates one or more different actions
    544 with given conditions - in the example, the actions are forward,
    545 which forwards a given option unchanged, and append_cmd, which
    546 appends a given string to the tool execution command. Multiple actions
    547 can be associated with a single condition by using a list of actions
    548 (used in the example to append some dummy options). The same case
    549 construct can also be used in the cmd_line property to modify the
    550 tool command line.

    551

    The "join" property used in the example means that this tool behaves

    552 like a linker.>
    496

    The actions tool property is implemented on top of the omnipresent case>

    497 expression. It associates one or more different actions with given
    498 conditions - in the example, the actions are forward, which forwards a given
    499 option unchanged, and append_cmd, which appends a given string to the tool
    500 execution command. Multiple actions can be associated with a single condition by
    501 using a list of actions (used in the example to append some dummy options). The
    502 same case construct can also be used in the cmd_line property to modify
    503 the tool command line.

    504

    The "join" property used in the example means that this tool behaves like a

    505 linker.

    553506

    The list of all possible actions follows.

    554507
    555508
  • Possible actions:

  • 556509
    557510
    558
  • append_cmd - Append a string to the tool invocation command.
  • 559 Example: (case (switch_on "pthread"), (append_cmd "-lpthread")).
    560
  • error - Exit with error.
  • 561 Example: (error "Mixing -c and -S is not allowed!").
    562
  • warning - Print a warning.
  • 563 Example: (warning "Specifying both -O1 and -O2 is meaningless!").
    564
  • forward - Forward the option unchanged.
  • 565 Example: (forward "Wall").
    566
  • forward_as - Change the option's name, but forward the argument
  • 511
  • append_cmd - Append a string to the tool invocation command.
  • 512 Example: (case (switch_on "pthread"), (append_cmd "-lpthread")).
    513
  • error - Exit with error.
  • 514 Example: (error "Mixing -c and -S is not allowed!").
    515
  • warning - Print a warning.
  • 516 Example: (warning "Specifying both -O1 and -O2 is meaningless!").
    517
  • forward - Forward the option unchanged.
  • 518 Example: (forward "Wall").
    519
  • forward_as - Change the option's name, but forward the argument
  • 567520 unchanged.
    568 Example: (forward_as "O0", "--disable-optimization").
    569
  • forward_value - Forward only option's value. Cannot be used with switch
  • 521 Example: (forward_as "O0", "--disable-optimization").
    522
  • forward_value - Forward only option's value. Cannot be used with switch
  • 570523 options (since they don't have values), but works fine with lists.
    571 Example: (forward_value "Wa,").
    572
  • forward_transformed_value - As above, but applies a hook to the
  • 524 Example: (forward_value "Wa,").
    525
  • forward_transformed_value - As above, but applies a hook to the
  • 573526 option's value before forwarding (see below). When
    574 forward_transformed_value is applied to a list
    527 forward_transformed_value is applied to a list
    575528 option, the hook must have signature
    576 std::string hooks::HookName (const std::vector<std::string>&).
    577 Example: (forward_transformed_value "m", "ConvertToMAttr").
    578
  • output_suffix - Modify the output suffix of this tool.
  • 579 Example: (output_suffix "i").
    580 <li>stop_compilation - Stop compilation after this tool processes its
    529 <tt class="docutils literal">std::string hooks::HookName (const std::vector<std::string>&).
    530 Example: (forward_transformed_value "m", "ConvertToMAttr").
    531
  • output_suffix - Modify the output suffix of this tool.
  • 532 Example: (output_suffix "i").
    533
  • stop_compilation - Stop compilation after this tool processes its
  • 581534 input. Used without arguments.
    582 Example: (stop_compilation).
    535 Example: (stop_compilation).
    583536
    584537
    585538
    587540
    588541
    589542
    590

    Language map

    591

    If you are adding support for a new language to LLVMC, you'll need to

    592 modify the language map, which defines mappings from file extensions
    593 to language names. It is used to choose the proper toolchain(s) for a
    594 given input file set. Language map definition looks like this:>
    543

    Language map>

    544

    If you are adding support for a new language to LLVMC, you'll need to modify the

    545 language map, which defines mappings from file extensions to language names. It
    546 is used to choose the proper toolchain(s) for a given input file set. Language
    547 map definition looks like this:

    595548
    
                      
                    
    596549 def LanguageMap : LanguageMap<
    597550 [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
    605558 llvmc: Unknown suffix: cpp
    606559
    607560

    The language map entries are needed only for the tools that are linked from the

    608 root node. Since a tool can't have multiple output languages, for inner nodes of
    609 the graph the input and output languages should match. This is enforced at
    610 compile-time.

    561 root node. A tool can have multiple output languages.

    611562
    612563
    613

    Option preprocessor

    564

    Option preprocessor

    614565

    It is sometimes useful to run error-checking code before processing the

    615566 compilation graph. For example, if optimization options "-O1" and "-O2" are
    616567 implemented as switches, we might want to output a warning if the user invokes
    617568 the driver with both of these options enabled.

    618

    The OptionPreprocessor feature is reserved specially for these

    619 occasions. Example (adapted from the built-in Base plugin):

    569

    The OptionPreprocessor feature is reserved specially for these

    570 occasions. Example (adapted from llvm/src/Base.td.in):

    620571
    
                      
                    
    621572 def Preprocess : OptionPreprocessor<
    622 (case (not (any_switch_on ["O0", "O1", "O2", "O3"])),
    573 (case (not (any_switch_on "O0", "O1", "O2", "O3")),
    623574 (set_option "O2"),
    624 (and (switch_on "O3"), (any_switch_on ["O0", "O1", "O2"])),
    625 (unset_option ["O0", "O1", "O2"]),
    626 (and (switch_on "O2"), (any_switch_on ["O0", "O1"])),
    627 (unset_option ["O0", "O1"]),
    575 (and (switch_on "O3"), (any_switch_on "O0", "O1", "O2")),
    576 (unset_option "O0", "O1", "O2"),
    577 (and (switch_on "O2"), (any_switch_on "O0", "O1")),
    578 (unset_option "O0", "O1"),
    628579 (and (switch_on "O1"), (switch_on "O0")),
    629580 (unset_option "O0"))
    630581 >;
    631582
    632

    Here, OptionPreprocessor is used to unset all spurious -O options so

    583

    Here, OptionPreprocessor is used to unset all spurious -O options so

    633584 that they are not forwarded to the compiler. If no optimization options are
    634585 specified, -O2 is enabled.

    635

    OptionPreprocessor is basically a single big case expression, which is

    636 evaluated only once right after the plugin is loaded. The only allowed actions
    637 in OptionPreprocessor are error, warning, and two special actions:
    638 unset_option and set_option. As their names suggest, they can be used to
    639 set or unset a given option. To set an option with set_option, use the
    640 two-argument form: (set_option "parameter", VALUE). Here, VALUE can be
    586

    OptionPreprocessor is basically a single big case expression, which is

    587 evaluated only once right after the driver is started. The only allowed actions
    588 in OptionPreprocessor are error, warning, and two special actions:
    589 unset_option and set_option. As their names suggest, they can be used to
    590 set or unset a given option. To set an option with set_option, use the
    591 two-argument form: (set_option "parameter", VALUE). Here, VALUE can be
    641592 either a string, a string list, or a boolean constant.

    642

    For convenience, set_option and unset_option also work on lists. That

    643 is, instead of [(unset_option "A"), (unset_option "B")] you can use
    644 (unset_option ["A", "B"]). Obviously, (set_option ["A", "B"]) is valid
    645 only if both A and B are switches.

    593

    For convenience, set_option and unset_option also work with multiple

    594 arguments. That is, instead of [(unset_option "A"), (unset_option "B")] you
    595 can use (unset_option "A", "B"). Obviously, (set_option "A", "B") is
    596 only valid if both A and B are switches.

    646597
    647598
    648

    More advanced topics

    599

    More advanced topics

    649600
    650

    Hooks and environment variables

    651

    Normally, LLVMC executes programs from the system PATH. Sometimes,

    652 this is not sufficient: for example, we may want to specify tool paths
    653 or names in the configuration file. This can be easily achieved via
    654 the hooks mechanism. To write your own hooks, just add their
    655 definitions to the PluginMain.cpp or drop a .cpp file into the
    656 your plugin directory. Hooks should live in the hooks namespace
    657 and have the signature std::string hooks::MyHookName ([const char*
    658 Arg0 [ const char* Arg2 [, ...]]]). They can be used from the
    659 cmd_line tool property:

    660
    
                      
                    
    661 (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
    601

    Hooks and environment variables

    602

    Normally, LLVMC searches for programs in the system PATH. Sometimes, this is

    603 not sufficient: for example, we may want to specify tool paths or names in the
    604 configuration file. This can be achieved via the hooks mechanism. To write your
    605 own hooks, add their definitions to the Hooks.cpp or drop a .cpp file
    606 into your driver directory. Hooks should live in the hooks namespace and
    607 have the signature std::string hooks::MyHookName ([const char* Arg0 [ const
    608 char* Arg2 [, ...]]]). They can be used from the command tool property:

    609
    
                      
                    
    610 (command "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
    662611
    663612

    To pass arguments to hooks, use the following syntax:

    664613
    
                      
                    
    665 (cmd_line "$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2")
    614 (command "$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2")
    666615
    667616

    It is also possible to use environment variables in the same manner:

    668617
    
                      
                    
    669 (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
    618 (command "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
    670619
    671620

    To change the command line string based on user-provided options use

    672 the case expression (documented above):

    673
    
                      
                    
    674 (cmd_line
    621 the case expression (documented above):

    622
    
                      
                    
    623 (command
    675624 (case
    676625 (switch_on "E"),
    677626 "llvm-g++ -E -x c $INFILE -o $OUTFILE",
    679628 "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm"))
    680629
    681630
    682
    683

    How plugins are loaded

    684

    It is possible for LLVMC plugins to depend on each other. For example,

    685 one can create edges between nodes defined in some other plugin. To
    686 make this work, however, that plugin should be loaded first. To
    687 achieve this, the concept of plugin priority was introduced. By
    688 default, every plugin has priority zero; to specify the priority
    689 explicitly, put the following line in your plugin's TableGen file:

    690
    
                      
                    
    691 def Priority : PluginPriority<$PRIORITY_VALUE>;
    692 # Where PRIORITY_VALUE is some integer > 0
    693
    694

    Plugins are loaded in order of their (increasing) priority, starting

    695 with 0. Therefore, the plugin with the highest priority value will be
    696 loaded last.

    697
    698631
    699

    Debugging

    700

    When writing LLVMC plugins, it can be useful to get a visual view of

    701 the resulting compilation graph. This can be achieved via the command
    702 line option --view-graph. This command assumes that Graphviz and
    703 Ghostview are installed. There is also a --write-graph option that
    704 creates a Graphviz source file (compilation-graph.dot) in the
    705 current directory.

    706

    Another useful llvmc option is --check-graph. It checks the

    707 compilation graph for common errors like mismatched output/input
    708 language names, multiple default edges and cycles. These checks can't
    709 be performed at compile-time because the plugins can load code
    710 dynamically. When invoked with --check-graph, llvmc doesn't
    711 perform any compilation tasks and returns the number of encountered
    712 errors as its status code.>
    632

    Debugging>

    633

    When writing LLVMC-based drivers, it can be useful to get a visual view of the

    634 resulting compilation graph. This can be achieved via the command line option
    635 --view-graph (which assumes that Graphviz and Ghostview are
    636 installed). There is also a --write-graph option that creates a Graphviz
    637 source file (compilation-graph.dot) in the current directory.

    638

    Another useful llvmc option is --check-graph. It checks the compilation

    639 graph for common errors like mismatched output/input language names, multiple
    640 default edges and cycles. When invoked with --check-graph, llvmc doesn't
    641 perform any compilation tasks and returns the number of encountered errors as
    642 its status code. In the future, these checks will be performed at compile-time
    643 and this option will disappear.

    713644
    714645
    715

    Conditioning on the executable name

    716 <p>For now, the executable name (the value passed to the driver in argv[0]) is
    646 <h2>Conditioning on the executable name
    647

    For now, the executable name (the value passed to the driver in argv[0]) is

    717648 accessible only in the C++ code (i.e. hooks). Use the following code:

    718649
    
                      
                    
    719650 namespace llvmc {
    733664
    734665

    In general, you're encouraged not to make the behaviour dependent on the

    735666 executable file name, and use command-line switches instead. See for example how
    736 the Base plugin behaves when it needs to choose the correct linker options
    737 (think g++ vs. gcc).

    667 the llvmc program behaves when it needs to choose the correct linker options
    668 (think g++ vs. gcc).

    738669
    739670
    740671
    745676 alt="Valid XHTML 1.0 Transitional"/>
    746677
    747678 Mikhail Glushenkov
    748 LLVM Compiler Infrastructure
    749
    750 Last modified: $Date$
    679 LLVM Compiler Infrastructure
    680
    681 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    751682
    752683
    753684
    22
    33
    44
    5
    5
    66 Tutorial - Using LLVMC
    77
    88
    1717

    Contents

    1818
    1919
  • Introduction
  • 20
  • Compiling with LLVMC
  • 20
  • Using the llvmc program
  • 2121
  • Using LLVMC to generate toolchain drivers
  • 2222
    2323
    2525

    Written by Mikhail Glushenkov

    2626
    2727

    Introduction

    28

    LLVMC is a generic compiler driver, which plays the same role for LLVM

    29 as the gcc program does for GCC - the difference being that LLVMC
    30 is designed to be more adaptable and easier to customize. Most of
    31 LLVMC functionality is implemented via plugins, which can be loaded
    32 dynamically or compiled in. This tutorial describes the basic usage
    33 and configuration of LLVMC.

    28

    LLVMC is a generic compiler driver, which plays the same role for LLVM as the

    29 gcc program does for GCC - the difference being that LLVMC is designed to be
    30 more adaptable and easier to customize. Most of LLVMC functionality is
    31 implemented via high-level TableGen code, from which a corresponding C++ source
    32 file is automatically generated. This tutorial describes the basic usage and
    33 configuration of LLVMC.

    3434
    35
    36

    Compiling with LLVMC

    37

    In general, LLVMC tries to be command-line compatible with gcc as

    38 much as possible, so most of the familiar options work:>
    35
    >
    36

    Using the llvmc program

    37

    In general, llvmc tries to be command-line compatible with gcc as much

    38 as possible, so most of the familiar options work:

    3939
    
                      
                    
    4040 $ llvmc -O3 -Wall hello.cpp
    4141 $ ./a.out
    4242 hello
    4343
    44

    This will invoke llvm-g++ under the hood (you can see which

    45 commands are executed by using the -v option). For further help on
    46 command-line LLVMC usage, refer to the llvmc --help output.

    44

    This will invoke llvm-g++ under the hood (you can see which commands are

    45 executed by using the -v option). For further help on command-line LLVMC
    46 usage, refer to the llvmc --help output.

    4747
    4848
    4949

    Using LLVMC to generate toolchain drivers

    50

    LLVMC plugins are written mostly using TableGen, so you need to

    51 be familiar with it to get anything done.

    52

    Start by compiling example/Simple, which is a primitive wrapper for

    53 <tt class="docutils literal">gcc:

    50 <p>LLVMC-based drivers are written mostly using TableGen, so you need to be
    51 familiar with it to get anything done.

    52

    Start by compiling example/Simple, which is a primitive wrapper for

    53 gcc:

    5454
    
                      
                    
    55 $ cd $LLVM_DIR/tools/llvmc
    56 $ cp -r example/Simple plugins/Simple
    57
    58 # NB: A less verbose way to compile standalone LLVMC-based drivers is
    59 # described in the reference manual.
    60
    61 $ make LLVMC_BASED_DRIVER_NAME=mygcc LLVMC_BUILTIN_PLUGINS=Simple
    55 $ cd $LLVM_OBJ_DIR/tools/examples/Simple
    56 $ make
    6257 $ cat > hello.c
    63 [...]
    64 $ mygcc hello.c
    58 #include <stdio.h>
    59 int main() { printf("Hello\n"); }
    60 $ $LLVM_BIN_DIR/Simple -v hello.c
    61 gcc hello.c -o hello.out
    6562 $ ./hello.out
    6663 Hello
    6764
    68

    Here we link our plugin with the LLVMC core statically to form an executable

    69 file called mygcc. It is also possible to build our plugin as a dynamic
    70 library to be loaded by the llvmc executable (or any other LLVMC-based
    71 standalone driver); this is described in the reference manual.

    72

    Contents of the file Simple.td look like this:

    65

    We have thus produced a simple driver called, appropriately, Simple, from

    66 the input TableGen file Simple.td. The llvmc program itself is generated
    67 using a similar process (see llvmc/src). Contents of the file Simple.td
    68 look like this:

    7369
    
                      
                    
    7470 // Include common definitions
    7571 include "llvm/CompilerDriver/Common.td"
    7975 [(in_language "c"),
    8076 (out_language "executable"),
    8177 (output_suffix "out"),
    82 (cmd_line "gcc $INFILE -o $OUTFILE"),
    83 (sink)
    78 (command "gcc"),
    79 (sink),
    80
    81 // -o is what is used by default, out_file_option here is included for
    82 // instructive purposes.
    83 (out_file_option "-o")
    8484 ]>;
    8585
    8686 // Language map
    87 def LanguageMap : LanguageMap<[LangToSuffixes<"c", ["c"]>]>;
    87 def LanguageMap : LanguageMap<[(lang_to_suffixes "c", "c")]>;
    8888
    8989 // Compilation graph
    90 def CompilationGraph : CompilationGraph<[Edge<"root", "gcc">]>;
    90 def CompilationGraph : CompilationGraph<[(edge "root", "gcc")]>;
    9191
    92

    As you can see, this file consists of three parts: tool descriptions,

    93 language map, and the compilation graph definition.

    94

    At the heart of LLVMC is the idea of a compilation graph: vertices in

    95 this graph are tools, and edges represent a transformation path
    96 between two tools (for example, assembly source produced by the
    97 compiler can be transformed into executable code by an assembler). The
    98 compilation graph is basically a list of edges; a special node named
    99 root is used to mark graph entry points.

    100

    Tool descriptions are represented as property lists: most properties

    101 in the example above should be self-explanatory; the sink property
    102 means that all options lacking an explicit description should be
    103 forwarded to this tool.

    104

    The LanguageMap associates a language name with a list of suffixes

    105 and is used for deciding which toolchain corresponds to a given input
    106 file.

    107

    To learn more about LLVMC customization, refer to the reference

    108 manual and plugin source code in the plugins directory.

    92

    As you can see, this file consists of three parts: tool descriptions, language

    93 map, and the compilation graph definition.

    94

    At the heart of LLVMC is the idea of a compilation graph: vertices in this graph

    95 are tools, and edges represent a transformation path between two tools (for
    96 example, assembly source produced by the compiler can be transformed into
    97 executable code by an assembler). The compilation graph is basically a list of
    98 edges; a special node named root is used to mark graph entry points.

    99

    Tool descriptions are represented as property lists: most properties in the

    100 example above should be self-explanatory; the sink property means that all
    101 options lacking an explicit description should be forwarded to this tool.

    102

    The LanguageMap associates a language name with a list of suffixes and is

    103 used for deciding which toolchain corresponds to a given input file.

    104

    To learn more about writing your own drivers with LLVMC, refer to the reference

    105 manual and examples in the examples directory. Of a particular interest is
    106 the Skeleton example, which can serve as a template for your LLVMC-based
    107 drivers.

    109108
    110109
    111110
    116115 alt="Valid XHTML 1.0 Transitional"/>
    117116
    118117 Mikhail Glushenkov
    119 LLVM Compiler Infrastructure
    118 LLVM Compiler Infrastructure
    120119
    121120 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    122121