llvm.org GIT mirror llvm / 68319f8
Update the auto-generated llvmc documentation. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@60909 91177308-0d34-0410-b5e6-96231b3b80d8 Mikhail Glushenkov 10 years ago
10 changed file(s) with 1248 addition(s) and 340 deletion(s). Raw diff Collapse all Expand all
22
33
44
5
5
66 Customizing LLVMC: Reference Manual
7 <link rel="stylesheet" href="llvm.css" type="text/css" />
7 <meta name="author" content="Mikhail Glushenkov <foldr@codedegers.com>" />
8
89
910
1011
11
12
Customizing LLVMC: Reference Manual
13
14
15

Note: This document is a work-in-progress. Additions and clarifications

16 are welcome.

17
18
12

Customizing LLVMC: Reference Manual

13
14
15
16
17
Author:
18 Mikhail Glushenkov <foldr@codedegers.com>
19
20
1921

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

2022 extensible. It plays the same role for LLVM as the gcc program
2123 does for GCC - LLVMC's job is essentially to transform a set of input
2426 are completely customizable - in fact, LLVMC knows nothing about the
2527 specifics of transformation (even the command-line options are mostly
2628 not hard-coded) and regards the transformation structure as an
27 abstract graph. This makes it possible to adapt LLVMC for other
28 purposes - for example, as a build tool for game resources.

29

Because LLVMC employs TableGen [1] as its configuration language, you

29 abstract graph. The structure of this graph is completely determined
30 by plugins, which can be either statically or dynamically linked. This
31 makes it possible to easily adapt LLVMC for other purposes - for
32 example, as a build tool for game resources.

33

Because LLVMC employs TableGen [1] as its configuration language, you

3034 need to be familiar with it to customize LLVMC.

3135
36

Contents

3237
33
  • Compiling with LLVMC
  • 34
  • Predefined options
  • 35
  • Customizing LLVMC: the compilation graph
  • 36
  • Writing a tool description
  • 37
  • Option list - specifying all options in a single place
  • 38
  • Using hooks and environment variables in the cmd_line property
  • 39
  • Conditional evaluation: the case expression
  • 40
  • Language map
  • 41
  • References
  • 42
    43
    44
    45
    Written by Mikhail Glushenkov
    46
    47
    48 <div class="doc_section">Compiling with LLVMC>
    38 <li>Compiling with LLVMC>
    39
  • Predefined options
  • 40
  • Compiling LLVMC plugins
  • 41
  • Customizing LLVMC: the compilation graph
  • 42
  • Describing options
  • 43
  • External options
  • 44
    45
    46
  • Conditional evaluation
  • 47
  • Writing a tool description
  • 48
  • Actions
  • 49
    50
    51
  • Language map
  • 52
  • More advanced topics
  • 53
  • Hooks and environment variables
  • 54
  • How plugins are loaded
  • 55
  • Debugging
  • 56
    57
    58
  • References
  • 59
    60
    61
    62

    Compiling with LLVMC

    4963

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

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

    5266
    
                      
                    
    5367 $ # This works as expected:
    54 $ llvmc2 -O3 -Wall hello.cpp
    68 $ llvmc -O3 -Wall hello.cpp
    5569 $ ./a.out
    5670 hello
    5771
    6276 extensions). If you want to force files ending with ".c" to compile as
    6377 C++, use the -x option, just like you would do it with gcc:

    6478
    
                      
                    
    65 $ llvmc2 -x c hello.cpp
    66 $ # hello.cpp is really a C file
    79 $ # hello.c is really a C++ file
    80 $ llvmc -x c++ hello.c
    6781 $ ./a.out
    6882 hello
    6983
    7185 object files you should provide the --linker option since it's
    7286 impossible for LLVMC to choose the right linker in that case:

    7387
    
                      
                    
    74 $ llvmc2 -c hello.cpp
    75 $ llvmc2 hello.o
    88 $ llvmc -c hello.cpp
    89 $ llvmc hello.o
    7690 [A lot of link-time errors skipped]
    77 $ llvmc2 --linker=c++ hello.o
    91 $ llvmc --linker=c++ hello.o
    7892 $ ./a.out
    7993 hello
    8094
    81
    82
    83 <div class="doc_section">Predefined options
    95 <p>By default, LLVMC uses llvm-gcc to compile the source code. It is
    96 also possible to choose the work-in-progress clang compiler with
    97 the -clang option.

    98
    99
    100

    Predefined options

    84101

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

    85 configuration files:

    102 configuration libraries:

    86103
    87104
  • -o FILE - Output file name.
  • 88105
  • -x LANGUAGE - Specify the language of the following input files
  • 89106 until the next -x option.
    107
  • -load PLUGIN_NAME - Load the specified plugin DLL. Example:
  • 108 -load $LLVM_DIR/Release/lib/LLVMCSimple.so.
    90109
  • -v - Enable verbose mode, i.e. print out all executed commands.
  • 91110
  • --view-graph - Show a graphical representation of the compilation
  • 92 graph. Requires that you have dot and gv commands
    111 graph. Requires that you have dot and gv programs
    93112 installed. Hidden option, useful for debugging.
    94113
  • --write-graph - Write a compilation-graph.dot file in the
  • 95114 current directory with the compilation graph description in the
    100119 their standard meaning.
    101120
    102121
    103
    104
    105

    At the time of writing LLVMC does not support on-the-fly reloading of

    106 configuration, so to customize LLVMC you'll have to recompile the
    107 source code (which lives under $LLVM_DIR/tools/llvmc2). The
    108 default configuration files are Common.td (contains common
    109 definitions, don't forget to include it in your configuration
    110 files), Tools.td (tool descriptions) and Graph.td (compilation
    111 graph definition).

    112

    To compile LLVMC with your own configuration file (say,``MyGraph.td``),

    113 run make like this:

    114
    
                      
                    
    115 $ cd $LLVM_DIR/tools/llvmc2
    116 $ make GRAPH=MyGraph.td TOOLNAME=my_llvmc
    117
    118

    This will build an executable named my_llvmc. There are also

    119 several sample configuration files in the llvmc2/examples
    120 subdirectory that should help to get you started.>
    122
    >
    123

    Compiling LLVMC plugins

    124

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

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

    126
    
                      
                    
    127 $ cd $LLVMC_DIR/plugins
    128 $ cp -r Simple MyPlugin
    129 $ cd MyPlugin
    130 $ ls
    131 Makefile PluginMain.cpp Simple.td
    132
    133

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

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

    139

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

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

    142
    
                      
                    
    143 LLVMC_PLUGIN=MyPlugin
    144
    145

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

    146 generic:

    147
    
                      
                    
    148 $ mv Simple.td MyPlugin.td
    149
    150

    Note that the plugin source directory must be placed under

    151 $LLVMC_DIR/plugins to make use of the existing build
    152 infrastructure. To build a version of the LLVMC executable called
    153 mydriver with your plugin compiled in, use the following command:

    154
    
                      
                    
    155 $ cd $LLVMC_DIR
    156 $ make BUILTIN_PLUGINS=MyPlugin DRIVER_NAME=mydriver
    157
    158

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

    159 directory and run make. The resulting file will be called
    160 LLVMC$(LLVMC_PLUGIN).$(DLL_EXTENSION) (in our case,
    161 LLVMCMyPlugin.so). This library can be then loaded in with the
    162 -load option. Example:

    163
    
                      
                    
    164 $ cd $LLVMC_DIR/plugins/Simple
    165 $ make
    166 $ llvmc -load $LLVM_DIR/Release/lib/LLVMCSimple.so
    167
    168

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

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

    170
    
                      
                    
    171 $ cd $LLVMC_DIR
    172 $ make BUILTIN_PLUGINS=""
    173
    174
    175
    176

    Customizing LLVMC: the compilation graph

    177

    Each TableGen configuration file should include the common

    178 definitions:

    179
    
                      
                    
    180 include "llvm/CompilerDriver/Common.td"
    181
    121182

    Internally, LLVMC stores information about possible source

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

    127

    The definition of the compilation graph (see file Graph.td) is

    128 just a list of edges:

    188

    The definition of the compilation graph (see file

    189 plugins/Base/Base.td for an example) is just a list of edges:

    129190
    
                      
                    
    130191 def CompilationGraph : CompilationGraph<[
    131 Edge<root, llvm_gcc_c>,
    132 Edge<root, llvm_gcc_assembler>,
    192 Edge<"root", "llvm_gcc_c">,
    193 Edge<"root", "llvm_gcc_assembler">,
    133194 ...
    134195
    135 Edge<llvm_gcc_c, llc>,
    136 Edge<llvm_gcc_cpp, llc>,
    196 Edge<"llvm_gcc_c", "llc">,
    197 Edge<"llvm_gcc_cpp", "llc">,
    137198 ...
    138199
    139 OptionalEdge<llvm_gcc_c, opt, [(switch_on "opt")]>,
    140 OptionalEdge<llvm_gcc_cpp, opt, [(switch_on "opt")]>,
    200 OptionalEdge<"llvm_gcc_c", "opt", (case (switch_on "opt"),
    201 (inc_weight))>,
    202 OptionalEdge<"llvm_gcc_cpp", "opt", (case (switch_on "opt"),
    203 (inc_weight))>,
    141204 ...
    142205
    143 OptionalEdge<llvm_gcc_assembler, llvm_gcc_cpp_linker,
    206 OptionalEdge<"llvm_gcc_assembler", "llvm_gcc_cpp_linker",
    144207 (case (input_languages_contain "c++"), (inc_weight),
    145208 (or (parameter_equals "linker", "g++"),
    146209 (parameter_equals "linker", "c++")), (inc_weight))>,
    149212 ]>;
    150213
    151214

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

    152 optional edges are differentiated by sporting a case expression
    153 used to calculate the edge's weight.

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

    154220

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

    155221 weight of 0 + 2*N where N is the number of tests that evaluated to
    156222 true in the case expression. It is also possible to provide an
    157223 integer parameter to inc_weight and dec_weight - in this case,
    158224 the weight is increased (or decreased) by the provided value instead
    159 of the default 2.

    225 of the default 2. It is also possible to change the default weight of
    226 an optional edge by using the default clause of the case
    227 construct.

    160228

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

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

    233

    When multiple plugins are loaded, their compilation graphs are merged

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

    165239

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

    166 debugging), run llvmc2 --view-graph. You will need dot and
    240 debugging), run llvmc --view-graph. You will need dot and
    167241 gsview installed for this to work properly.

    168242
    169
    170
    171

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

    172 which are described separately. A tool definition looks like this
    173 (taken from the Tools.td file):

    174
    
                      
                    
    175 def llvm_gcc_cpp : Tool<[
    176 (in_language "c++"),
    177 (out_language "llvm-assembler"),
    178 (output_suffix "bc"),
    179 (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
    180 (sink)
    181 ]>;
    182
    183

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

    184 llvm-g++. As you can see, a tool definition is just a list of
    185 properties; most of them should be self-explanatory. The sink
    186 property means that this tool should be passed all command-line
    187 options that lack explicit descriptions.

    188

    The complete list of the currently implemented tool properties follows:

    189
    190
  • Possible tool properties:
  • 191
  • in_language - input language name.
  • 192
  • out_language - output language name.
  • 193
  • output_suffix - output file suffix.
  • 194
  • cmd_line - the actual command used to run the tool. You can
  • 195 use $INFILE and $OUTFILE variables, output redirection
    196 with >, hook invocations ($CALL), environment variables
    197 (via $ENV) and the case construct (more on this below).
    198
  • join - this tool is a "join node" in the graph, i.e. it gets a
  • 199 list of input files and joins them together. Used for linkers.
    200
  • sink - all command-line options that are not handled by other
  • 201 tools are passed to this tool.
    202
    203
    204
    205

    The next tool definition is slightly more complex:

    206
    
                      
                    
    207 def llvm_gcc_linker : Tool<[
    208 (in_language "object-code"),
    209 (out_language "executable"),
    210 (output_suffix "out"),
    211 (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
    212 (join),
    213 (prefix_list_option "L", (forward),
    214 (help "add a directory to link path")),
    215 (prefix_list_option "l", (forward),
    216 (help "search a library when linking")),
    217 (prefix_list_option "Wl", (unpack_values),
    218 (help "pass options to linker"))
    219 ]>;
    220
    221

    This tool has a "join" property, which means that it behaves like a

    222 linker. This tool also defines several command-line options: -l,
    223 -L and -Wl which have their usual meaning. An option has two
    224 attributes: a name and a (possibly empty) list of properties. All
    225 currently implemented option types and properties are described below:>
    243
    >
    244

    Describing options

    245

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

    246 OptionList:

    247
    
                      
                    
    248 def Options : OptionList<[
    249 (switch_option "E", (help "Help string")),
    250 (alias_option "quiet", "q")
    251 ...
    252 ]>;
    253
    254

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

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

    226259
    227260
  • Possible option types:

  • 228261
    246279
  • Possible option properties:

  • 247280
    248281
    249
  • append_cmd - append a string to the tool invocation command.
  • 250
  • forward - forward this option unchanged.
  • 251
  • output_suffix - modify the output suffix of this
  • 252 tool. Example : (switch "E", (output_suffix "i").
    253
  • stop_compilation - stop compilation after this phase.
  • 254
  • unpack_values - used for for splitting and forwarding
  • 255 comma-separated lists of options, e.g. -Wa,-foo=bar,-baz is
    256 converted to -foo=bar -baz and appended to the tool invocation
    257 command.
    258282
  • help - help string associated with this option. Used for
  • 259283 --help output.
    260284
  • required - this option is obligatory.
  • 285
  • hidden - this option should not appear in the --help
  • 286 output (but should appear in the --help-hidden output).
    287
  • really_hidden - the option should not appear in any help
  • 288 output.
    289
  • extern - this option is defined in some other plugin, see below.
  • 261290
    262291
    263292
    264293
    265
    266
    267
    268

    It can be handy to have all information about options gathered in a

    269 single place to provide an overview. This can be achieved by using a
    270 so-called OptionList:

    271
    
                      
                    
    272 def Options : OptionList<[
    273 (switch_option "E", (help "Help string")),
    274 (alias_option "quiet", "q")
    294
    295

    External options

    296

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

    297 access options defined in some other plugin. Because of the way
    298 options are implemented, such options should be marked as
    299 extern. This is what the extern option property is
    300 for. Example:

    301
    
                      
                    
    275302 ...
    276 ]>;
    277
    278

    OptionList is also a good place to specify option aliases.

    279

    Tool-specific option properties like append_cmd have (obviously)

    280 no meaning in the context of OptionList, so the only properties
    281 allowed there are help and required.

    282

    Option lists are used at the file scope. See file

    283 examples/Clang.td for an example of OptionList usage.

    284
    285
    286
    287

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

    288 this is not sufficient: for example, we may want to specify tool names
    289 in the configuration file. This can be achieved via the mechanism of
    290 hooks - to compile LLVMC with your hooks, just drop a .cpp file into
    291 tools/llvmc2 directory. Hooks should live in the hooks
    292 namespace and have the signature std::string hooks::MyHookName
    293 (void). They can be used from the cmd_line tool property:

    294
    
                      
                    
    295 (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
    296
    297

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

    298
    
                      
                    
    299 (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
    300
    301

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

    302 the case expression (documented below):

    303
    
                      
                    
    304 (cmd_line
    305 (case
    306 (switch_on "E"),
    307 "llvm-g++ -E -x c $INFILE -o $OUTFILE",
    308 (default),
    309 "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm"))
    310
    311
    312
    313
    314

    The 'case' construct can be used to calculate weights of the optional

    315 edges and to choose between several alternative command line strings
    316 in the cmd_line tool property. It is designed after the
    317 similarly-named construct in functional languages and takes the form
    318 (case (test_1), statement_1, (test_2), statement_2, ... (test_N),
    319 statement_N). The statements are evaluated only if the corresponding
    320 tests evaluate to true.

    303 (switch_option "E", (extern))
    304 ...
    305
    306

    See also the section on plugin priorities.

    307
    308
    309
    310

    Conditional evaluation

    311

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

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

    321318

    Examples:

    322319
    
                      
                    
    320 // Edge weight calculation
    321
    323322 // Increases edge weight by 5 if "-A" is provided on the
    324323 // command-line, and by 5 more if "-B" is also provided.
    325324 (case
    326325 (switch_on "A"), (inc_weight 5),
    327326 (switch_on "B"), (inc_weight 5))
    328327
    329 // Evaluates to "cmdline1" if option "-A" is provided on the
    330 // command line, otherwise to "cmdline2"
    328
    329 // Tool command line specification
    330
    331 // Evaluates to "cmdline1" if the option "-A" is provided on the
    332 // command line; to "cmdline2" if "-B" is provided;
    333 // otherwise to "cmdline3".
    334
    331335 (case
    332336 (switch_on "A"), "cmdline1",
    333337 (switch_on "B"), "cmdline2",
    348352 use TableGen inheritance instead.

    349353
    350354
  • Possible tests are:
  • 351
  • switch_on - Returns true if a given command-line option is
  • 352 provided by the user. Example: (switch_on "opt"). Note that
    353 you have to define all possible command-line options separately in
    354 the tool descriptions. See the next doc_text for the discussion of
    355 different kinds of command-line options.
    355
  • switch_on - Returns true if a given command-line switch is
  • 356 provided by the user. Example: (switch_on "opt").
    356357
  • parameter_equals - Returns true if a command-line parameter equals
  • 357 a given value. Example: (parameter_equals "W", "all").
    358
  • element_in_list - Returns true if a command-line parameter list
  • 359 includes a given value. Example: (parameter_in_list "l", "pthread").
    358 a given value.
    359 Example: (parameter_equals "W", "all").
    360
  • element_in_list - Returns true if a command-line parameter
  • 361 list contains a given value.
    362 Example: (parameter_in_list "l", "pthread").
    360363
  • input_languages_contain - Returns true if a given language
  • 361 belongs to the current input language set. Example:
    362 `(input_languages_contain "c++").
    363
  • in_language - Evaluates to true if the language of the input
  • 364 file equals to the argument. Valid only when using case
    365 expression in a cmd_line tool property. Example:
    366 `(in_language "c++").
    364 belongs to the current input language set.
    365 Example: (input_languages_contain "c++").
    366
  • in_language - Evaluates to true if the input file language
  • 367 equals to the argument. At the moment works only with cmd_line
    368 and actions (on non-join nodes).
    369 Example: (in_language "c++").
    367370
  • not_empty - Returns true if a given option (which should be
  • 368371 either a parameter or a parameter list) is set by the
    369 user. Example: `(not_empty "o").
    372 user.
    373 Example: (not_empty "o").
    370374
  • default - Always evaluates to true. Should always be the last
  • 371375 test in the case expression.
    372376
  • and - A standard logical combinator that returns true iff all
  • 380384
    381385
    382386
    383
    384
    385

    One last thing that you will need to modify when adding support for a

    386 new language to LLVMC is the language map, which defines mappings from
    387 file extensions to language names. It is used to choose the proper
    388 toolchain(s) for a given input file set. Language map definition is
    389 located in the file Tools.td and looks like this:>
    387
    >
    388

    Writing a tool description

    389

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

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

    392
    
                      
                    
    393 def llvm_gcc_cpp : Tool<[
    394 (in_language "c++"),
    395 (out_language "llvm-assembler"),
    396 (output_suffix "bc"),
    397 (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
    398 (sink)
    399 ]>;
    400
    401

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

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

    406

    The complete list of all currently implemented tool properties follows.

    407
    408
  • Possible tool properties:
  • 409
  • in_language - input language name. Can be either a string or a
  • 410 list, in case the tool supports multiple input languages.
    411
  • out_language - output language name. Tools are not allowed to
  • 412 have multiple output languages.
    413
  • output_suffix - output file suffix. Can also be changed
  • 414 dynamically, see documentation on actions.
    415
  • cmd_line - the actual command used to run the tool. You can
  • 416 use $INFILE and $OUTFILE variables, output redirection
    417 with >, hook invocations ($CALL), environment variables
    418 (via $ENV) and the case construct.
    419
  • join - this tool is a "join node" in the graph, i.e. it gets a
  • 420 list of input files and joins them together. Used for linkers.
    421
  • sink - all command-line options that are not handled by other
  • 422 tools are passed to this tool.
    423
  • actions - A single big case expression that specifies how
  • 424 this tool reacts on command-line options (described in more detail
    425 below).
    426
    427
    428
    429
    430

    Actions

    431

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

    432 precisely what the actions property is for. The next example
    433 illustrates this feature:

    434
    
                      
                    
    435 def llvm_gcc_linker : Tool<[
    436 (in_language "object-code"),
    437 (out_language "executable"),
    438 (output_suffix "out"),
    439 (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
    440 (join),
    441 (actions (case (not_empty "L"), (forward "L"),
    442 (not_empty "l"), (forward "l"),
    443 (not_empty "dummy"),
    444 [(append_cmd "-dummy1"), (append_cmd "-dummy2")])
    445 ]>;
    446
    447

    The actions tool property is implemented on top of the omnipresent

    448 case expression. It associates one or more different actions
    449 with given conditions - in the example, the actions are forward,
    450 which forwards a given option unchanged, and append_cmd, which
    451 appends a given string to the tool execution command. Multiple actions
    452 can be associated with a single condition by using a list of actions
    453 (used in the example to append some dummy options). The same case
    454 construct can also be used in the cmd_line property to modify the
    455 tool command line.

    456

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

    457 like a linker.

    458

    The list of all possible actions follows.

    459
    460
  • Possible actions:

  • 461
    462
    463
  • append_cmd - append a string to the tool invocation
  • 464 command.
    465 Example: (case (switch_on "pthread"), (append_cmd "-lpthread"))
    466
  • forward - forward an option unchanged.
  • 467 Example: (forward "Wall").
    468
  • forward_as - Change the name of an option, but forward the
  • 469 argument unchanged.
    470 Example: (forward_as "O0" "--disable-optimization").
    471
  • output_suffix - modify the output suffix of this
  • 472 tool.
    473 Example: (output_suffix "i").
    474
  • stop_compilation - stop compilation after this tool processes
  • 475 its input. Used without arguments.
    476
  • unpack_values - used for for splitting and forwarding
  • 477 comma-separated lists of options, e.g. -Wa,-foo=bar,-baz is
    478 converted to -foo=bar -baz and appended to the tool invocation
    479 command.
    480 Example: (unpack_values "Wa,").
    481
    482
    483
    484
    485
    486
    487
    488

    Language map

    489

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

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

    390493
    
                      
                    
    391494 def LanguageMap : LanguageMap<
    392495 [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
    394497 ...
    395498 ]>;
    396499
    397
    398
    399
    400 <table class="docutils footnote" frame="void" id="id2" rules="none">
    500 <p>For example, without those definitions the following command wouldn't work:>
    501
    
                      
                    
    502 $ llvmc hello.cpp
    503 llvmc: Unknown suffix: cpp
    504
    505

    The language map entries should be added only for tools that are

    506 linked with the root node. Since tools are not allowed to have
    507 multiple output languages, for nodes "inside" the graph the input and
    508 output languages should match. This is enforced at compile-time.

    509
    510
    511

    More advanced topics

    512
    513

    Hooks and environment variables

    514

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

    515 this is not sufficient: for example, we may want to specify tool names
    516 in the configuration file. This can be achieved via the mechanism of
    517 hooks - to write your own hooks, just add their definitions to the
    518 PluginMain.cpp or drop a .cpp file into the
    519 $LLVMC_DIR/driver directory. Hooks should live in the hooks
    520 namespace and have the signature std::string hooks::MyHookName
    521 (void). They can be used from the cmd_line tool property:

    522
    
                      
                    
    523 (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
    524
    525

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

    526
    
                      
                    
    527 (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
    528
    529

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

    530 the case expression (documented above):

    531
    
                      
                    
    532 (cmd_line
    533 (case
    534 (switch_on "E"),
    535 "llvm-g++ -E -x c $INFILE -o $OUTFILE",
    536 (default),
    537 "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm"))
    538
    539
    540
    541

    How plugins are loaded

    542

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

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

    548
    
                      
                    
    549 def Priority : PluginPriority<$PRIORITY_VALUE>;
    550 # Where PRIORITY_VALUE is some integer > 0
    551
    552

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

    553 with 0. Therefore, the plugin with the highest priority value will be
    554 loaded last.

    555
    556
    557

    Debugging

    558

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

    559 the resulting compilation graph. This can be achieved via the command
    560 line option --view-graph. This command assumes that Graphviz [2] and
    561 Ghostview [3] are installed. There is also a --dump-graph option that
    562 creates a Graphviz source file(compilation-graph.dot) in the
    563 current directory.

    564
    565
    566
    567

    References

    568
    401569
    402570
    403
    [1]TableGen Fundamentals
    571
    [1]TableGen Fundamentals
    404572 http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
    405573
    406574
    407
    408
    409 <hr />
    575 <table class="docutils footnote" frame="void" id="id8" rules="none">
    576
    577
    578
    [2]Graphviz
    579 http://www.graphviz.org/
    580
    581
    582
    583
    584
    585
    [3]Ghostview
    586 http://pages.cs.wisc.edu/~ghost/
    587
    588
    589
    410590
    411 412 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS" /> 413 414 src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" /> 415 The LLVM Compiler Infrastructure
    416 Last modified: $Date$ 591 Valid CSS 592 Valid HTML 4.01 593 594 Mikhail Glushenkov
    595 LLVM Compiler Infrastructure
    596 597 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $ 417598
    599
    600
    418601 419602
    0
    1
    2
    3
    4
    5
    6 Customizing LLVMC: Reference Manual
    7
    8
    9
    10
    11
    12

    Customizing LLVMC: Reference Manual

    13
    14
    15
    16
    17
    Author:
    18 Mikhail Glushenkov <foldr@codedegers.com>
    19
    20
    21

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

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

    33

    Because LLVMC employs TableGen [1] as its configuration language, you

    34 need to be familiar with it to customize LLVMC.

    35
    36

    Contents

    37
    38
  • Compiling with LLVMC
  • 39
  • Predefined options
  • 40
  • Compiling LLVMC plugins
  • 41
  • Customizing LLVMC: the compilation graph
  • 42
  • Describing options
  • 43
  • External options
  • 44
    45
    46
  • Conditional evaluation
  • 47
  • Writing a tool description
  • 48
  • Actions
  • 49
    50
    51
  • Language map
  • 52
  • More advanced topics
  • 53
  • Hooks and environment variables
  • 54
  • How plugins are loaded
  • 55
  • Debugging
  • 56
    57
    58
  • References
  • 59
    60
    61
    62

    Compiling with LLVMC

    63

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

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

    66
    
                      
                    
    67 $ # This works as expected:
    68 $ llvmc -O3 -Wall hello.cpp
    69 $ ./a.out
    70 hello
    71
    72

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

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

    78
    
                      
                    
    79 $ # hello.c is really a C++ file
    80 $ llvmc -x c++ hello.c
    81 $ ./a.out
    82 hello
    83
    84

    On the other hand, when using LLVMC as a linker to combine several C++

    85 object files you should provide the --linker option since it's
    86 impossible for LLVMC to choose the right linker in that case:

    87
    
                      
                    
    88 $ llvmc -c hello.cpp
    89 $ llvmc hello.o
    90 [A lot of link-time errors skipped]
    91 $ llvmc --linker=c++ hello.o
    92 $ ./a.out
    93 hello
    94
    95

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

    96 also possible to choose the work-in-progress clang compiler with
    97 the -clang option.

    98
    99
    100

    Predefined options

    101

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

    102 configuration libraries:

    103
    104
  • -o FILE - Output file name.
  • 105
  • -x LANGUAGE - Specify the language of the following input files
  • 106 until the next -x option.
    107
  • -load PLUGIN_NAME - Load the specified plugin DLL. Example:
  • 108 -load $LLVM_DIR/Release/lib/LLVMCSimple.so.
    109
  • -v - Enable verbose mode, i.e. print out all executed commands.
  • 110
  • --view-graph - Show a graphical representation of the compilation
  • 111 graph. Requires that you have dot and gv programs
    112 installed. Hidden option, useful for debugging.
    113
  • --write-graph - Write a compilation-graph.dot file in the
  • 114 current directory with the compilation graph description in the
    115 Graphviz format. Hidden option, useful for debugging.
    116
  • --save-temps - Write temporary files to the current directory
  • 117 and do not delete them on exit. Hidden option, useful for debugging.
    118
  • --help, --help-hidden, --version - These options have
  • 119 their standard meaning.
    120
    121
    122
    123

    Compiling LLVMC plugins

    124

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

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

    126
    
                      
                    
    127 $ cd $LLVMC_DIR/plugins
    128 $ cp -r Simple MyPlugin
    129 $ cd MyPlugin
    130 $ ls
    131 Makefile PluginMain.cpp Simple.td
    132
    133

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

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

    139

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

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

    142
    
                      
                    
    143 LLVMC_PLUGIN=MyPlugin
    144
    145

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

    146 generic:

    147
    
                      
                    
    148 $ mv Simple.td MyPlugin.td
    149
    150

    Note that the plugin source directory must be placed under

    151 $LLVMC_DIR/plugins to make use of the existing build
    152 infrastructure. To build a version of the LLVMC executable called
    153 mydriver with your plugin compiled in, use the following command:

    154
    
                      
                    
    155 $ cd $LLVMC_DIR
    156 $ make BUILTIN_PLUGINS=MyPlugin DRIVER_NAME=mydriver
    157
    158

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

    159 directory and run make. The resulting file will be called
    160 LLVMC$(LLVMC_PLUGIN).$(DLL_EXTENSION) (in our case,
    161 LLVMCMyPlugin.so). This library can be then loaded in with the
    162 -load option. Example:

    163
    
                      
                    
    164 $ cd $LLVMC_DIR/plugins/Simple
    165 $ make
    166 $ llvmc -load $LLVM_DIR/Release/lib/LLVMCSimple.so
    167
    168

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

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

    170
    
                      
                    
    171 $ cd $LLVMC_DIR
    172 $ make BUILTIN_PLUGINS=""
    173
    174
    175
    176

    Customizing LLVMC: the compilation graph

    177

    Each TableGen configuration file should include the common

    178 definitions:

    179
    
                      
                    
    180 include "llvm/CompilerDriver/Common.td"
    181
    182

    Internally, LLVMC stores information about possible source

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

    188

    The definition of the compilation graph (see file

    189 plugins/Base/Base.td for an example) is just a list of edges:

    190
    
                      
                    
    191 def CompilationGraph : CompilationGraph<[
    192 Edge<"root", "llvm_gcc_c">,
    193 Edge<"root", "llvm_gcc_assembler">,
    194 ...
    195
    196 Edge<"llvm_gcc_c", "llc">,
    197 Edge<"llvm_gcc_cpp", "llc">,
    198 ...
    199
    200 OptionalEdge<"llvm_gcc_c", "opt", (case (switch_on "opt"),
    201 (inc_weight))>,
    202 OptionalEdge<"llvm_gcc_cpp", "opt", (case (switch_on "opt"),
    203 (inc_weight))>,
    204 ...
    205
    206 OptionalEdge<"llvm_gcc_assembler", "llvm_gcc_cpp_linker",
    207 (case (input_languages_contain "c++"), (inc_weight),
    208 (or (parameter_equals "linker", "g++"),
    209 (parameter_equals "linker", "c++")), (inc_weight))>,
    210 ...
    211
    212 ]>;
    213
    214

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

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

    220

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

    221 weight of 0 + 2*N where N is the number of tests that evaluated to
    222 true in the case expression. It is also possible to provide an
    223 integer parameter to inc_weight and dec_weight - in this case,
    224 the weight is increased (or decreased) by the provided value instead
    225 of the default 2. It is also possible to change the default weight of
    226 an optional edge by using the default clause of the case
    227 construct.

    228

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

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

    233

    When multiple plugins are loaded, their compilation graphs are merged

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

    239

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

    240 debugging), run llvmc --view-graph. You will need dot and
    241 gsview installed for this to work properly.

    242
    243
    244

    Describing options

    245

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

    246 OptionList:

    247
    
                      
                    
    248 def Options : OptionList<[
    249 (switch_option "E", (help "Help string")),
    250 (alias_option "quiet", "q")
    251 ...
    252 ]>;
    253
    254

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

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

    259
    260
  • Possible option types:

  • 261
    262
    263
  • switch_option - a simple boolean switch, for example -time.
  • 264
  • parameter_option - option that takes an argument, for example
  • 265 -std=c99;
    266
  • parameter_list_option - same as the above, but more than one
  • 267 occurence of the option is allowed.
    268
  • prefix_option - same as the parameter_option, but the option name
  • 269 and parameter value are not separated.
    270
  • prefix_list_option - same as the above, but more than one
  • 271 occurence of the option is allowed; example: -lm -lpthread.
    272
  • alias_option - a special option type for creating
  • 273 aliases. Unlike other option types, aliases are not allowed to
    274 have any properties besides the aliased option name. Usage
    275 example: (alias_option "preprocess", "E")
    276
    277
    278
    279
  • Possible option properties:

  • 280
    281
    282
  • help - help string associated with this option. Used for
  • 283 --help output.
    284
  • required - this option is obligatory.
  • 285
  • hidden - this option should not appear in the --help
  • 286 output (but should appear in the --help-hidden output).
    287
  • really_hidden - the option should not appear in any help
  • 288 output.
    289
  • extern - this option is defined in some other plugin, see below.
  • 290
    291
    292
    293
    294
    295

    External options

    296

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

    297 access options defined in some other plugin. Because of the way
    298 options are implemented, such options should be marked as
    299 extern. This is what the extern option property is
    300 for. Example:

    301
    
                      
                    
    302 ...
    303 (switch_option "E", (extern))
    304 ...
    305
    306

    See also the section on plugin priorities.

    307
    308
    309
    310

    Conditional evaluation

    311

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

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

    318

    Examples:

    319
    
                      
                    
    320 // Edge weight calculation
    321
    322 // Increases edge weight by 5 if "-A" is provided on the
    323 // command-line, and by 5 more if "-B" is also provided.
    324 (case
    325 (switch_on "A"), (inc_weight 5),
    326 (switch_on "B"), (inc_weight 5))
    327
    328
    329 // Tool command line specification
    330
    331 // Evaluates to "cmdline1" if the option "-A" is provided on the
    332 // command line; to "cmdline2" if "-B" is provided;
    333 // otherwise to "cmdline3".
    334
    335 (case
    336 (switch_on "A"), "cmdline1",
    337 (switch_on "B"), "cmdline2",
    338 (default), "cmdline3")
    339
    340

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

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

    345

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

    346
    
                      
                    
    347 (case (switch_on "E"), (case (switch_on "o"), ..., (default), ...)
    348 (default), ...)
    349
    350

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

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

    353
    354
  • Possible tests are:
  • 355
  • switch_on - Returns true if a given command-line switch is
  • 356 provided by the user. Example: (switch_on "opt").
    357
  • parameter_equals - Returns true if a command-line parameter equals
  • 358 a given value.
    359 Example: (parameter_equals "W", "all").
    360
  • element_in_list - Returns true if a command-line parameter
  • 361 list contains a given value.
    362 Example: (parameter_in_list "l", "pthread").
    363
  • input_languages_contain - Returns true if a given language
  • 364 belongs to the current input language set.
    365 Example: (input_languages_contain "c++").
    366
  • in_language - Evaluates to true if the input file language
  • 367 equals to the argument. At the moment works only with cmd_line
    368 and actions (on non-join nodes).
    369 Example: (in_language "c++").
    370
  • not_empty - Returns true if a given option (which should be
  • 371 either a parameter or a parameter list) is set by the
    372 user.
    373 Example: (not_empty "o").
    374
  • default - Always evaluates to true. Should always be the last
  • 375 test in the case expression.
    376
  • and - A standard logical combinator that returns true iff all
  • 377 of its arguments return true. Used like this: (and (test1),
    378 (test2), ... (testN)). Nesting of and and or is allowed,
    379 but not encouraged.
    380
  • or - Another logical combinator that returns true only if any
  • 381 one of its arguments returns true. Example: (or (test1),
    382 (test2), ... (testN)).
    383
    384
    385
    386
    387
    388

    Writing a tool description

    389

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

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

    392
    
                      
                    
    393 def llvm_gcc_cpp : Tool<[
    394 (in_language "c++"),
    395 (out_language "llvm-assembler"),
    396 (output_suffix "bc"),
    397 (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
    398 (sink)
    399 ]>;
    400
    401

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

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

    406

    The complete list of all currently implemented tool properties follows.

    407
    408
  • Possible tool properties:
  • 409
  • in_language - input language name. Can be either a string or a
  • 410 list, in case the tool supports multiple input languages.
    411
  • out_language - output language name. Tools are not allowed to
  • 412 have multiple output languages.
    413
  • output_suffix - output file suffix. Can also be changed
  • 414 dynamically, see documentation on actions.
    415
  • cmd_line - the actual command used to run the tool. You can
  • 416 use $INFILE and $OUTFILE variables, output redirection
    417 with >, hook invocations ($CALL), environment variables
    418 (via $ENV) and the case construct.
    419
  • join - this tool is a "join node" in the graph, i.e. it gets a
  • 420 list of input files and joins them together. Used for linkers.
    421
  • sink - all command-line options that are not handled by other
  • 422 tools are passed to this tool.
    423
  • actions - A single big case expression that specifies how
  • 424 this tool reacts on command-line options (described in more detail
    425 below).
    426
    427
    428
    429
    430

    Actions

    431

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

    432 precisely what the actions property is for. The next example
    433 illustrates this feature:

    434
    
                      
                    
    435 def llvm_gcc_linker : Tool<[
    436 (in_language "object-code"),
    437 (out_language "executable"),
    438 (output_suffix "out"),
    439 (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
    440 (join),
    441 (actions (case (not_empty "L"), (forward "L"),
    442 (not_empty "l"), (forward "l"),
    443 (not_empty "dummy"),
    444 [(append_cmd "-dummy1"), (append_cmd "-dummy2")])
    445 ]>;
    446
    447

    The actions tool property is implemented on top of the omnipresent

    448 case expression. It associates one or more different actions
    449 with given conditions - in the example, the actions are forward,
    450 which forwards a given option unchanged, and append_cmd, which
    451 appends a given string to the tool execution command. Multiple actions
    452 can be associated with a single condition by using a list of actions
    453 (used in the example to append some dummy options). The same case
    454 construct can also be used in the cmd_line property to modify the
    455 tool command line.

    456

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

    457 like a linker.

    458

    The list of all possible actions follows.

    459
    460
  • Possible actions:

  • 461
    462
    463
  • append_cmd - append a string to the tool invocation
  • 464 command.
    465 Example: (case (switch_on "pthread"), (append_cmd "-lpthread"))
    466
  • forward - forward an option unchanged.
  • 467 Example: (forward "Wall").
    468
  • forward_as - Change the name of an option, but forward the
  • 469 argument unchanged.
    470 Example: (forward_as "O0" "--disable-optimization").
    471
  • output_suffix - modify the output suffix of this
  • 472 tool.
    473 Example: (output_suffix "i").
    474
  • stop_compilation - stop compilation after this tool processes
  • 475 its input. Used without arguments.
    476
  • unpack_values - used for for splitting and forwarding
  • 477 comma-separated lists of options, e.g. -Wa,-foo=bar,-baz is
    478 converted to -foo=bar -baz and appended to the tool invocation
    479 command.
    480 Example: (unpack_values "Wa,").
    481
    482
    483
    484
    485
    486
    487
    488

    Language map

    489

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

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

    493
    
                      
                    
    494 def LanguageMap : LanguageMap<
    495 [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
    496 LangToSuffixes<"c", ["c"]>,
    497 ...
    498 ]>;
    499
    500

    For example, without those definitions the following command wouldn't work:

    501
    
                      
                    
    502 $ llvmc hello.cpp
    503 llvmc: Unknown suffix: cpp
    504
    505

    The language map entries should be added only for tools that are

    506 linked with the root node. Since tools are not allowed to have
    507 multiple output languages, for nodes "inside" the graph the input and
    508 output languages should match. This is enforced at compile-time.

    509
    510
    511

    More advanced topics

    512
    513

    Hooks and environment variables

    514

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

    515 this is not sufficient: for example, we may want to specify tool names
    516 in the configuration file. This can be achieved via the mechanism of
    517 hooks - to write your own hooks, just add their definitions to the
    518 PluginMain.cpp or drop a .cpp file into the
    519 $LLVMC_DIR/driver directory. Hooks should live in the hooks
    520 namespace and have the signature std::string hooks::MyHookName
    521 (void). They can be used from the cmd_line tool property:

    522
    
                      
                    
    523 (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
    524
    525

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

    526
    
                      
                    
    527 (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
    528
    529

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

    530 the case expression (documented above):

    531
    
                      
                    
    532 (cmd_line
    533 (case
    534 (switch_on "E"),
    535 "llvm-g++ -E -x c $INFILE -o $OUTFILE",
    536 (default),
    537 "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm"))
    538
    539
    540
    541

    How plugins are loaded

    542

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

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

    548
    
                      
                    
    549 def Priority : PluginPriority<$PRIORITY_VALUE>;
    550 # Where PRIORITY_VALUE is some integer > 0
    551
    552

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

    553 with 0. Therefore, the plugin with the highest priority value will be
    554 loaded last.

    555
    556
    557

    Debugging

    558

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

    559 the resulting compilation graph. This can be achieved via the command
    560 line option --view-graph. This command assumes that Graphviz [2] and
    561 Ghostview [3] are installed. There is also a --dump-graph option that
    562 creates a Graphviz source file(compilation-graph.dot) in the
    563 current directory.

    564
    565
    566
    567

    References

    568
    569
    570
    571
    [1]TableGen Fundamentals
    572 http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
    573
    574
    575
    576
    577
    578
    [2]Graphviz
    579 http://www.graphviz.org/
    580
    581
    582
    583
    584
    585
    [3]Ghostview
    586 http://pages.cs.wisc.edu/~ghost/
    587
    588
    589
    590
    591 Valid CSS
    592 Valid HTML 4.01
    593
    594 Mikhail Glushenkov
    595 LLVM Compiler Infrastructure
    596
    597 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    598
    599
    600
    601
    602
    2929
    3030
    3131 32
    32
    3333

    Written by The LLVM Team

    3434
    3535 9999
  • Frequently Asked Questions - A list of common 100100 questions and problems and their solutions.
  • 101101 102
  • Release notes for the current release 102
  • Release notes for the current release 103103 - This describes new features, known bugs, and other limitations.
  • 104104 105105
  • How to Submit A Bug Report - 115115
  • The LLVM Lexicon - Definition of acronyms, terms 116116 and concepts used in LLVM.
  • 117117 118
  • You can probably find help on the unofficial LLVM IRC 119 channel. We often are on irc.oftc.net in the #llvm channel. If you are 120 using the mozilla browser, and have chatzilla installed, you can 118
  • You can probably find help on the unofficial LLVM IRC 119 channel. We often are on irc.oftc.net in the #llvm channel. If you are 120 using the mozilla browser, and have chatzilla installed, you can 121121 href="irc://irc.oftc.net/llvm">join #llvm on irc.oftc.net directly.
  • 122122 123123 151151 Details the LLVM coding standards and provides useful information on writing 152152 efficient C++ code. 153153 154
  • Extending LLVM - Look here to see how 154
  • Extending LLVM - Look here to see how 155155 to add instructions and intrinsics to LLVM.
  • 156156 157157
  • Using LLVM Libraries - Look here to 160160
  • How To Release LLVM To The Public - This 161161 is a guide to preparing LLVM releases. Most developers can ignore it.
  • 162162 163
  • Doxygen generated 163
  • Doxygen generated 164164 documentation ( 165165 href="http://llvm.org/doxygen/inherits.html">classes) 166166 204204 LLVM - This document describes the design and philosophy behind the LLVM 205205 source-level debugger.
  • 206206 207
  • Zero Cost Exception handling in LLVM 207
  • Zero Cost Exception handling in LLVM 208208 - This document describes the design and implementation of exception handling 209209 in LLVM.
  • 210210 211211
  • Bugpoint - automatic bug finder and test-case 212212 reducer description and usage information.
  • 213213 214
  • Compiler Driver (llvmc) - This document 215 describes the design and configuration of the LLVM compiler driver tool, 216 llvmc.
  • 217 218
  • LLVM Bitcode File Format - This describes 214
  • Compiler Driver (llvmc) Tutorial 215 - This document is a tutorial introduction to the usage and 216 configuration of the LLVM compiler driver tool, llvmc.
  • 217 218
  • Compiler Driver (llvmc) 219 Reference - This document describes the design and configuration 220 of llvmc in more detail.
  • 221 222
  • LLVM Bitcode File Format - This describes 219223 the file format and encoding used for LLVM "bc" files.
  • 220224 221225
  • System Library - This document describes 235239 236240
      237241
    • The 238 LLVM Announcements List: This is a low volume list that provides important 242 LLVM Announcements List: This is a low volume list that provides important 239243 announcements regarding LLVM. It gets email about once a month.
    • 240244 241245
    • The Developer's 242 List: This list is for people who want to be included in technical 243 discussions of LLVM. People post to this list when they have questions about 246 List: This list is for people who want to be included in technical 247 discussions of LLVM. People post to this list when they have questions about 244248 writing code for or using the LLVM tools. It is relatively low volume.
    • 245249 246250
    • The Bugs & 247251 Patches Archive: This list gets emailed every time a bug is opened and 248 closed, and when people submit patches to be included in LLVM. It is higher 252 closed, and when people submit patches to be included in LLVM. It is higher 249253 volume than the LLVMdev list.
    • 250254 251255
    • The Commits 252 Archive: This list contains all commit messages that are made when LLVM 253 developers commit code changes to the repository. It is useful for those who 256 Archive: This list contains all commit messages that are made when LLVM 257 developers commit code changes to the repository. It is useful for those who 254258 want to stay on the bleeding edge of LLVM development. This list is very high 255259 volume.
    • 256260
  • 0 /*
    1 * LLVM documentation style sheet
    2 */
    3
    4 /* Common styles */
    5 .body { color: black; background: white; margin: 0 0 0 0 }
    6
    7 /* No borders on image links */
    8 a:link img, a:visited img {border-style: none}
    9
    10 address img { float: right; width: 88px; height: 31px; }
    11 address { clear: right; }
    12
    13 TR, TD { border: 2px solid gray; padding: 4pt 4pt 2pt 2pt; }
    14 TH { border: 2px solid gray; font-weight: bold; font-size: 105%;
    15 background: url("img/lines.gif");
    16 font-family: "Georgia,Palatino,Times,Roman,SanSerif"; text-align:center;
    17 vertical-align: middle; }
    18 TABLE { text-align: center; border: 2px solid black;
    19 border-collapse: collapse; margin-top: 1em; margin-left: 1em;
    20 margin-right: 1em; margin-bottom: 1em; }
    21 /*
    22 * Documentation
    23 */
    24 /* Common for title and header */
    25 h1, h2 {
    26 color: black; background: url("img/lines.gif");
    27 font-family: "Georgia,Palatino,Times,Roman,SanSerif"; font-weight: bold;
    28 border-width: 1px;
    29 border-style: solid none solid none;
    30 text-align: center;
    31 vertical-align: middle;
    32 padding-left: 8pt;
    33 padding-top: 1px;
    34 padding-bottom: 2px;
    35 }
    36
    37 h1 {
    38 text-align: center;
    39 font-size: 22pt;
    40 margin: 20pt 0pt 5pt 0pt;
    41 }
    42
    43 .title { padding-top: 0; margin-top: 0; text-align: left; font-size: 25pt }
    44 h2 { width: 75%;
    45 text-align: left; font-size: 12pt; padding: 4pt 4pt 4pt 4pt;
    46 margin: 1.5em 0.5em 0.5em 0.5em }
    47
    48 h3 { margin: 2.0em 0.5em 0.5em 0.5em;
    49 font-weight: bold; font-style: oblique;
    50 border-bottom: 1px solid #999999; font-size: 12pt;
    51 width: 75%; }
    52 .doc_author { text-align: left; font-weight: bold; padding-left: 20pt }
    53 .doc_text { text-align: left; padding-left: 20pt; padding-right: 10pt }
    54
    55 .doc_footer { text-align: left; padding: 0 0 0 0 }
    56
    57 .doc_hilite { color: blue; font-weight: bold; }
    58
    59 .doc_table { text-align: center; width: 90%;
    60 padding: 1px 1px 1px 1px; border: 1px; }
    61
    62 .doc_table_nw { text-align: center; border: 1px;
    63 padding: 1px 1px 1px 1px; }
    64
    65 .doc_warning { color: red; font-weight: bold }
    66
    67 .literal-block { border: solid 1px gray; background: #eeeeee;
    68 margin: 0 1em 0 1em;
    69 padding: 0 1em 0 1em;
    70 display:table;
    71 }
    72 .doc_notes { background: #fafafa; border: 1px solid #cecece; padding: 0.1em }
    73
    74 TABLE.layout { text-align: left; border: none; border-collapse: collapse;
    75 padding: 4px 4px 4px 4px; }
    76 TR.layout { border: none; padding: 4pt 4pt 2pt 2pt; }
    77 TD.layout { border: none; padding: 4pt 4pt 2pt 2pt;
    78 vertical-align: top;}
    79 TD.left { border: none; padding: 4pt 4pt 2pt 2pt; text-align: left;
    80 vertical-align: top;}
    81 TD.right { border: none; padding: 4pt 4pt 2pt 2pt; text-align: right;
    82 vertical-align: top;}
    83 TH.layout { border: none; font-weight: bold; font-size: 105%;
    84 text-align:center; vertical-align: middle; }
    85
    86 /* Left align table cell */
    87 .td_left { border: 2px solid gray; text-align: left; }
    88
    89 .toc-backref { color: black; text-decoration: none; }
    596596
    597597 .. [3] Ghostview
    598598 http://pages.cs.wisc.edu/~ghost/
    599
    600 .. raw:: html
    601 :file: footer.html
    9797
    9898 .. [1] TableGen Fundamentals
    9999 http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
    100
    101 .. raw:: html
    102 :file: footer.html
    66 #
    77 ##===----------------------------------------------------------------------===##
    88
    9 RST2HTML=rst2html --stylesheet=llvm.css --link-stylesheet
    9 LEVEL=../../..
    10 include $(LEVEL)/Makefile.config
    1011
    11 all : LLVMC-Reference.html LLVMC-Tutorial.html
    12 RST_CSS=llvm-rst.css
    13 DOC_DIR=../../../docs
    14 RST2HTML=rst2html --stylesheet=$(RST_CSS) --link-stylesheet
    1215
    13 LLVMC-Tutorial.html : LLVMC-Tutorial.rst llvm.css
    16 all : LLVMC-Reference.html LLVMC-Tutorial.html $(RST_CSS)
    17 $(CP) $(RST_CSS) $(DOC_DIR)/$(RST_CSS)
    18 $(CP) LLVMC-Reference.html $(DOC_DIR)/CompilerDriver.html
    19 $(CP) LLVMC-Reference.html $(DOC_DIR)/CompilerDriverTutorial.html
    20
    21 LLVMC-Tutorial.html : LLVMC-Tutorial.rst $(RST_CSS)
    1422 $(RST2HTML) $< $@
    1523
    16 LLVMC-Reference.html : LLVMC-Reference.rst llvm.css
    24 LLVMC-Reference.html : LLVMC-Reference.rst $(RST_CSS)
    1725 $(RST2HTML) $< $@
    1826
    1927 clean :
    20 rm *.html
    28 $(RM) LLVMC-Tutorial.html LLVMC-Reference.html
    0
    1
    2 Valid CSS
    3 Valid HTML 4.01
    4
    5 Mikhail Glushenkov
    6 LLVM Compiler Infrastructure
    7
    8 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    9
    0 /*
    1 * LLVM documentation style sheet
    2 */
    3
    4 /* Common styles */
    5 .body { color: black; background: white; margin: 0 0 0 0 }
    6
    7 /* No borders on image links */
    8 a:link img, a:visited img {border-style: none}
    9
    10 address img { float: right; width: 88px; height: 31px; }
    11 address { clear: right; }
    12
    13 TR, TD { border: 2px solid gray; padding: 4pt 4pt 2pt 2pt; }
    14 TH { border: 2px solid gray; font-weight: bold; font-size: 105%;
    15 background: url("img/lines.gif");
    16 font-family: "Georgia,Palatino,Times,Roman,SanSerif"; text-align:center;
    17 vertical-align: middle; }
    18 TABLE { text-align: center; border: 2px solid black;
    19 border-collapse: collapse; margin-top: 1em; margin-left: 1em;
    20 margin-right: 1em; margin-bottom: 1em; }
    21 /*
    22 * Documentation
    23 */
    24 /* Common for title and header */
    25 h1, h2 {
    26 color: black; background: url("img/lines.gif");
    27 font-family: "Georgia,Palatino,Times,Roman,SanSerif"; font-weight: bold;
    28 border-width: 1px;
    29 border-style: solid none solid none;
    30 text-align: center;
    31 vertical-align: middle;
    32 padding-left: 8pt;
    33 padding-top: 1px;
    34 padding-bottom: 2px;
    35 }
    36
    37 h1 {
    38 text-align: center;
    39 font-size: 22pt;
    40 margin: 20pt 0pt 5pt 0pt;
    41 }
    42
    43 .title { padding-top: 0; margin-top: 0; text-align: left; font-size: 25pt }
    44 h2 { width: 75%;
    45 text-align: left; font-size: 12pt; padding: 4pt 4pt 4pt 4pt;
    46 margin: 1.5em 0.5em 0.5em 0.5em }
    47
    48 h3 { margin: 2.0em 0.5em 0.5em 0.5em;
    49 font-weight: bold; font-style: oblique;
    50 border-bottom: 1px solid #999999; font-size: 12pt;
    51 width: 75%; }
    52 .doc_author { text-align: left; font-weight: bold; padding-left: 20pt }
    53 .doc_text { text-align: left; padding-left: 20pt; padding-right: 10pt }
    54
    55 .doc_footer { text-align: left; padding: 0 0 0 0 }
    56
    57 .doc_hilite { color: blue; font-weight: bold; }
    58
    59 .doc_table { text-align: center; width: 90%;
    60 padding: 1px 1px 1px 1px; border: 1px; }
    61
    62 .doc_table_nw { text-align: center; border: 1px;
    63 padding: 1px 1px 1px 1px; }
    64
    65 .doc_warning { color: red; font-weight: bold }
    66
    67 .literal-block { border: solid 1px gray; background: #eeeeee;
    68 margin: 0 1em 0 1em;
    69 padding: 0 1em 0 1em;
    70 display:table;
    71 }
    72 .doc_notes { background: #fafafa; border: 1px solid #cecece; padding: 0.1em }
    73
    74 TABLE.layout { text-align: left; border: none; border-collapse: collapse;
    75 padding: 4px 4px 4px 4px; }
    76 TR.layout { border: none; padding: 4pt 4pt 2pt 2pt; }
    77 TD.layout { border: none; padding: 4pt 4pt 2pt 2pt;
    78 vertical-align: top;}
    79 TD.left { border: none; padding: 4pt 4pt 2pt 2pt; text-align: left;
    80 vertical-align: top;}
    81 TD.right { border: none; padding: 4pt 4pt 2pt 2pt; text-align: right;
    82 vertical-align: top;}
    83 TH.layout { border: none; font-weight: bold; font-size: 105%;
    84 text-align:center; vertical-align: middle; }
    85
    86 /* Left align table cell */
    87 .td_left { border: 2px solid gray; text-align: left; }
    88
    89 .toc-backref { color: black; text-decoration: none; }
    +0
    -86
    tools/llvmc/doc/llvm.css less more
    None /*
    1 * LLVM documentation style sheet
    2 */
    3
    4 /* Common styles */
    5 .body { color: black; background: white; margin: 0 0 0 0 }
    6
    7 /* No borders on image links */
    8 a:link img, a:visited img {border-style: none}
    9
    10 address img { float: right; width: 88px; height: 31px; }
    11 address { clear: right; }
    12
    13 TR, TD { border: 2px solid gray; padding: 4pt 4pt 2pt 2pt; }
    14 TH { border: 2px solid gray; font-weight: bold; font-size: 105%;
    15 background: url("img/lines.gif");
    16 font-family: "Georgia,Palatino,Times,Roman,SanSerif"; text-align:center;
    17 vertical-align: middle; }
    18 TABLE { text-align: center; border: 2px solid black;
    19 border-collapse: collapse; margin-top: 1em; margin-left: 1em;
    20 margin-right: 1em; margin-bottom: 1em; }
    21 /*
    22 * Documentation
    23 */
    24 /* Common for title and header */
    25 h1 {
    26 color: black; background: url("img/lines.gif");
    27 font-family: "Georgia,Palatino,Times,Roman,SanSerif"; font-weight: bold;
    28 border-width: 1px;
    29 border-style: solid none solid none;
    30 text-align: center;
    31 vertical-align: middle;
    32 padding-left: 8pt;
    33 padding-top: 1px;
    34 padding-bottom: 2px
    35 }
    36
    37 .doc_title { text-align: left; font-size: 25pt }
    38 .doc_section { text-align: center; font-size: 22pt;
    39 margin: 20pt 0pt 5pt 0pt; }
    40 .doc_subsection { width: 75%;
    41 text-align: left; font-size: 12pt; padding: 4pt 4pt 4pt 4pt;
    42 margin: 1.5em 0.5em 0.5em 0.5em }
    43
    44 .doc_subsubsection { margin: 2.0em 0.5em 0.5em 0.5em;
    45 font-weight: bold; font-style: oblique;
    46 border-bottom: 1px solid #999999; font-size: 12pt;
    47 width: 75%; }
    48 .doc_author { text-align: left; font-weight: bold; padding-left: 20pt }
    49 .doc_text { text-align: left; padding-left: 20pt; padding-right: 10pt }
    50
    51 .doc_footer { text-align: left; padding: 0 0 0 0 }
    52
    53 .doc_hilite { color: blue; font-weight: bold; }
    54
    55 .doc_table { text-align: center; width: 90%;
    56 padding: 1px 1px 1px 1px; border: 1px; }
    57
    58 .doc_table_nw { text-align: center; border: 1px;
    59 padding: 1px 1px 1px 1px; }
    60
    61 .doc_warning { color: red; font-weight: bold }
    62
    63 .literal-block { border: solid 1px gray; background: #eeeeee;
    64 margin: 0 1em 0 1em;
    65 padding: 0 1em 0 1em;
    66 display:table;
    67 }
    68 .doc_notes { background: #fafafa; border: 1px solid #cecece; padding: 0.1em }
    69
    70 TABLE.layout { text-align: left; border: none; border-collapse: collapse;
    71 padding: 4px 4px 4px 4px; }
    72 TR.layout { border: none; padding: 4pt 4pt 2pt 2pt; }
    73 TD.layout { border: none; padding: 4pt 4pt 2pt 2pt;
    74 vertical-align: top;}
    75 TD.left { border: none; padding: 4pt 4pt 2pt 2pt; text-align: left;
    76 vertical-align: top;}
    77 TD.right { border: none; padding: 4pt 4pt 2pt 2pt; text-align: right;
    78 vertical-align: top;}
    79 TH.layout { border: none; font-weight: bold; font-size: 105%;
    80 text-align:center; vertical-align: middle; }
    81
    82 /* Left align table cell */
    83 .td_left { border: 2px solid gray; text-align: left; }
    84
    85 .toc-backref { color: black; }