llvm.org GIT mirror llvm / 502106a
Regenerate. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@73449 91177308-0d34-0410-b5e6-96231b3b80d8 Mikhail Glushenkov 10 years ago
2 changed file(s) with 78 addition(s) and 47 deletion(s). Raw diff Collapse all Expand all
2020
  • Compiling with LLVMC
  • 2121
  • Predefined options
  • 2222
  • Compiling LLVMC plugins
  • 23
  • Customizing LLVMC: the compilation graph
  • 24
  • Describing options
  • 25
  • External options
  • 26
    27
    28
  • Conditional evaluation
  • 29
  • Writing a tool description
  • 30
  • Actions
  • 31
    32
    33
  • Language map
  • 34
  • More advanced topics
  • 35
  • Hooks and environment variables
  • 36
  • How plugins are loaded
  • 37
  • Debugging
  • 23
  • Compiling standalone LLVMC-based drivers
  • 24
  • Customizing LLVMC: the compilation graph
  • 25
  • Describing options
  • 26
  • External options
  • 27
    28
    29
  • Conditional evaluation
  • 30
  • Writing a tool description
  • 31
  • Actions
  • 32
    33
    34
  • Language map
  • 35
  • More advanced topics
  • 36
  • Hooks and environment variables
  • 37
  • How plugins are loaded
  • 38
  • Debugging
  • 3839
    3940
    4041
    109110
  • -v - Enable verbose mode, i.e. print out all executed commands.
  • 110111
  • --check-graph - Check the compilation for common errors like mismatched
  • 111112 output/input language names, multiple default edges and cycles. Because of
    112 plugins, these checks can't be performed at compile-time. Exit with code zero if
    113 no errors were found, and return the number of found errors otherwise. Hidden
    114 option, useful for debugging LLVMC plugins.
    113 plugins, these checks can't be performed at compile-time. Exit with code zero
    114 if no errors were found, and return the number of found errors
    115 otherwise. Hidden option, useful for debugging LLVMC plugins.
    115116
  • --view-graph - Show a graphical representation of the compilation graph
  • 116117 and exit. Requires that you have dot and gv programs installed. Hidden
    117118 option, useful for debugging LLVMC plugins.
    118119
  • --write-graph - Write a compilation-graph.dot file in the current
  • 119120 directory with the compilation graph description in Graphviz format (identical
    120 to the file used by the --view-graph option). The -o option can be used
    121 to set the output file name. Hidden option, useful for debugging LLVMC plugins.
    121 to the file used by the --view-graph option). The -o option can be
    122 used to set the output file name. Hidden option, useful for debugging LLVMC
    123 plugins.
    122124
  • --save-temps - Write temporary files to the current directory
  • 123125 and do not delete them on exit. Hidden option, useful for debugging.
    124126
  • --help, --help-hidden, --version - These options have
  • 153155
    
                      
                    
    154156 $ mv Simple.td MyPlugin.td
    155157
    156

    Note that the plugin source directory must be placed under

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

    160
    
                      
                    
    161 $ cd $LLVMC_DIR
    162 $ make BUILTIN_PLUGINS=MyPlugin DRIVER_NAME=mydriver
    163
    164158

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

    165159 directory and run make. The resulting file will be called
    166160 LLVMC$(LLVMC_PLUGIN).$(DLL_EXTENSION) (in our case,
    171165 $ make
    172166 $ llvmc -load $LLVM_DIR/Release/lib/LLVMCSimple.so
    173167
    168
    169
    170

    Compiling standalone LLVMC-based drivers

    171

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

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

    176
    
                      
                    
    177 $ cd $LLVMC_DIR/example/
    178 $ cp -r Skeleton mydriver
    179 $ cd mydriver
    180 $ vim Makefile
    181 [...]
    182 $ make
    183
    184

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

    185 must perform the following additional steps before running make:

    186
    
                      
                    
    187 # LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/
    188 # LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/
    189 $ cp $LLVMC_SRC_DIR/example/mydriver/Makefile \
    190 $LLVMC_OBJ_DIR/example/mydriver/
    191 $ cd $LLVMC_OBJ_DIR/example/mydriver
    192 $ make
    193
    194

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

    195
    
                      
                    
    196 $ cd $LLVMC_DIR
    197 $ make LLVMC_BUILTIN_PLUGINS=MyPlugin LLVMC_BASED_DRIVER_NAME=mydriver
    198
    199

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

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

    174201

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

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

    176203
    
                      
                    
    177204 $ cd $LLVMC_DIR
    178 $ make BUILTIN_PLUGINS=""
    205 $ make LLVMC_BUILTIN_PLUGINS=""
    179206
    180207
    181208
    182

    Customizing LLVMC: the compilation graph

    209

    Customizing LLVMC: the compilation graph

    183210

    Each TableGen configuration file should include the common

    184211 definitions:

    185212
    
                      
                    
    247274 gsview installed for this to work properly.

    248275
    249276
    250

    Describing options

    277

    Describing options

    251278

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

    252279 OptionList:

    253280
    
                      
                    
    316343
    317344
    318345
    319

    External options

    346

    External options

    320347

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

    321348 access options defined in some other plugin. Because of the way
    322349 options are implemented, such options must be marked as
    331358
    332359
    333360
    334

    Conditional evaluation

    361

    Conditional evaluation

    335362

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

    336363 achieved in LLVMC. It can be used to calculate edge weights, program
    337364 actions and modify the shell commands to be executed. The 'case'
    411438
    412439
    413440
    414

    Writing a tool description

    441

    Writing a tool description

    415442

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

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

    453480
    454481
    455482
    456

    Actions

    483

    Actions

    457484

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

    458485 precisely what the actions property is for. The next example
    459486 illustrates this feature:

    514541
    515542
    516543
    517

    Language map

    544

    Language map

    518545

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

    519546 modify the language map, which defines mappings from file extensions
    520547 to language names. It is used to choose the proper toolchain(s) for a
    537564 output languages should match. This is enforced at compile-time.

    538565
    539566
    540

    More advanced topics

    567

    More advanced topics

    541568
    542

    Hooks and environment variables

    569

    Hooks and environment variables

    543570

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

    544571 this is not sufficient: for example, we may want to specify tool paths
    545572 or names in the configuration file. This can be easily achieved via
    572599
    573600
    574601
    575

    How plugins are loaded

    602

    How plugins are loaded

    576603

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

    577604 one can create edges between nodes defined in some other plugin. To
    578605 make this work, however, that plugin should be loaded first. To
    588615 loaded last.

    589616
    590617
    591

    Debugging

    618

    Debugging

    592619

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

    593620 the resulting compilation graph. This can be achieved via the command
    594621 line option --view-graph. This command assumes that Graphviz and
    4949

    Using LLVMC to generate toolchain drivers

    5050

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

    5151 be familiar with it to get anything done.

    52

    Start by compiling plugins/Simple/Simple.td, which is a primitive

    53 wrapper for gcc:

    52

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

    53 gcc:

    5454
    
                      
                    
    5555 $ cd $LLVM_DIR/tools/llvmc
    56 $ make DRIVER_NAME=mygcc BUILTIN_PLUGINS=Simple
    56
    57 # NB: A less verbose way to compile standalone LLVMC-based drivers is
    58 # described in the reference manual.
    59
    60 $ make LLVMC_BASED_DRIVER_NAME=mygcc LLVMC_BUILTIN_PLUGINS=Simple
    5761 $ cat > hello.c
    5862 [...]
    5963 $ mygcc hello.c
    6064 $ ./hello.out
    6165 Hello
    6266
    63

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

    64 executable file called mygcc. It is also possible to build our
    65 plugin as a standalone dynamic library; this is described in the
    66 reference manual.

    67

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

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

    6771

    Contents of the file Simple.td look like this:

    6872
    
                      
                    
    6973 // Include common definitions