llvm.org GIT mirror llvm / d6d2efc
Regenerate documentation. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@71055 91177308-0d34-0410-b5e6-96231b3b80d8 Mikhail Glushenkov 10 years ago
3 changed file(s) with 78 addition(s) and 76 deletion(s). Raw diff Collapse all Expand all
22
33
44
5
5
66 Customizing LLVMC: Reference Manual
77
88
99
1010
1111

Customizing LLVMC: Reference Manual

12
1213
15
16 <p class="topic-title first">Contents>
16 <div class="contents topic" id="contents">
17

Contents

1718
18
  • Introduction
  • 19
  • Compiling with LLVMC
  • 20
  • Predefined options
  • 21
  • Compiling LLVMC plugins
  • 22
  • Customizing LLVMC: the compilation graph
  • 23
  • Describing options
  • 24
  • External options
  • 25
    26
    27
  • Conditional evaluation
  • 28
  • Writing a tool description
  • 29
  • Actions
  • 30
    31
    32
  • Language map
  • 33
  • More advanced topics
  • 34
  • Hooks and environment variables
  • 35
  • How plugins are loaded
  • 36
  • Debugging
  • 19
  • Introduction
  • 20
  • Compiling with LLVMC
  • 21
  • Predefined options
  • 22
  • 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
  • 3738
    3839
    3940
    4041
    4142
    4243

    Written by Mikhail Glushenkov

    43
    44 <h1>Introduction>
    44 </div>
    >
    45

    Introduction

    4546

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

    4647 extensible. It plays the same role for LLVM as the gcc program
    4748 does for GCC - LLVMC's job is essentially to transform a set of input
    5455 by plugins, which can be either statically or dynamically linked. This
    5556 makes it possible to easily adapt LLVMC for other purposes - for
    5657 example, as a build tool for game resources.

    57

    Because LLVMC employs TableGen as its configuration language, you

    58

    Because LLVMC employs TableGen as its configuration language, you

    5859 need to be familiar with it to customize LLVMC.

    5960
    60
    61 <h1>Compiling with LLVMC>
    61 <div class="section" id="compiling-with-llvmc">
    62

    Compiling with LLVMC

    6263

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

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

    9596 also possible to choose the work-in-progress clang compiler with
    9697 the -clang option.

    9798
    98
    99 <h1>Predefined options>
    99 <div class="section" id="predefined-options">
    100

    Predefined options

    100101

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

    101102 configuration libraries:

    102103
    124125 their standard meaning.
    125126
    126127
    127
    128 <h1>Compiling LLVMC plugins>
    128 <div class="section" id="compiling-llvmc-plugins">
    129

    Compiling LLVMC plugins

    129130

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

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

    131132
    
                      
                    
    140141 description of the compilation graph; its format is documented in the
    141142 following sections. PluginMain.cpp is just a helper file used to
    142143 compile the auto-generated C++ code produced from TableGen source. It
    143 can also contain hook definitions (see below).

    144 can also contain hook definitions (see below).

    144145

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

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

    177178 $ make BUILTIN_PLUGINS=""
    178179
    179180
    180
    181 <h1>Customizing LLVMC: the compilation graph>
    181 <div class="section" id="customizing-llvmc-the-compilation-graph">
    182

    Customizing LLVMC: the compilation graph

    182183

    Each TableGen configuration file should include the common

    183184 definitions:

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

    247248
    248
    249 <h1>Describing options>
    249 <div class="section" id="describing-options">
    250

    Describing options

    250251

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

    251252 OptionList:

    252253
    
                      
                    
    314315
    315316
    316317
    317
    318 <h2>External options>
    318 <div class="section" id="external-options">
    319

    External options

    319320

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

    320321 access options defined in some other plugin. Because of the way
    321322 options are implemented, such options must be marked as
    326327 (switch_option "E", (extern))
    327328 ...
    328329
    329

    See also the section on plugin priorities.

    330
    331
    332
    333 <h1>Conditional evaluation>
    330 <p>See also the section on plugin priorities.>
    331
    332
    333
    334

    Conditional evaluation

    334335

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

    335336 achieved in LLVMC. It can be used to calculate edge weights, program
    336337 actions and modify the shell commands to be executed. The 'case'
    409410
    410411
    411412
    412
    413 <h1>Writing a tool description>
    413 <div class="section" id="writing-a-tool-description">
    414

    Writing a tool description

    414415

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

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

    451452
    452453
    453454
    454
    455 <h2>Actions>
    455 <div class="section" id="actions">
    456

    Actions

    456457

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

    457458 precisely what the actions property is for. The next example
    458459 illustrates this feature:

    495496 Example: (forward "Wall").
    496497
  • forward_as - Change the name of an option, but forward the
  • 497498 argument unchanged.
    498 Example: (forward_as "O0" "--disable-optimization").
    499 Example: (forward_as "O0", "--disable-optimization").
    499500
  • output_suffix - modify the output suffix of this
  • 500501 tool.
    501502 Example: (output_suffix "i").
    512513
    513514
    514515
    515
    516 <h1>Language map>
    516 <div class="section" id="language-map">
    517

    Language map

    517518

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

    518519 modify the language map, which defines mappings from file extensions
    519520 to language names. It is used to choose the proper toolchain(s) for a
    535536 multiple output languages, for nodes "inside" the graph the input and
    536537 output languages should match. This is enforced at compile-time.

    537538
    538
    539

    More advanced topics

    540
    541 <h2>Hooks and environment variables>
    539 <div class="section" id="more-advanced-topics">
    540

    More advanced topics

    541
    542

    Hooks and environment variables

    542543

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

    543544 this is not sufficient: for example, we may want to specify tool paths
    544545 or names in the configuration file. This can be easily achieved via
    560561 (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
    561562
    562563

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

    563 the case expression (documented above):

    564 the case expression (documented above):

    564565
    
                      
                    
    565566 (cmd_line
    566567 (case
    570571 "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm"))
    571572
    572573
    573
    574 <h2>How plugins are loaded>
    574 <div class="section" id="how-plugins-are-loaded">
    575

    How plugins are loaded

    575576

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

    576577 one can create edges between nodes defined in some other plugin. To
    577578 make this work, however, that plugin should be loaded first. To
    586587 with 0. Therefore, the plugin with the highest priority value will be
    587588 loaded last.

    588589
    589
    590 <h2>Debugging>
    590 <div class="section" id="debugging">
    591

    Debugging

    591592

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

    592593 the resulting compilation graph. This can be achieved via the command
    593 line option --view-graph. This command assumes that Graphviz and
    594 Ghostview are installed. There is also a --write-graph option that
    594 line option --view-graph. This command assumes that Graphviz and
    595 Ghostview are installed. There is also a --write-graph option that
    595596 creates a Graphviz source file (compilation-graph.dot) in the
    596597 current directory.

    597598

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

    22
    33
    44
    5
    5
    66 Tutorial - Using LLVMC
    77
    88
    99
    1010
    1111

    Tutorial - Using LLVMC

    12
    1213
    15
    16 <p class="topic-title first">Contents>
    16 <div class="contents topic" id="contents">
    17

    Contents

    1718
    18
  • Introduction
  • 19
  • Compiling with LLVMC
  • 20
  • Using LLVMC to generate toolchain drivers
  • 19
  • Introduction
  • 20
  • Compiling with LLVMC
  • 21
  • Using LLVMC to generate toolchain drivers
  • 2122
    2223
    2324
    2425

    Written by Mikhail Glushenkov

    25
    26 <h1>Introduction>
    26 </div>
    >
    27

    Introduction

    2728

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

    2829 as the gcc program does for GCC - the difference being that LLVMC
    2930 is designed to be more adaptable and easier to customize. Most of
    3132 dynamically or compiled in. This tutorial describes the basic usage
    3233 and configuration of LLVMC.

    3334
    34
    35 <h1>Compiling with LLVMC>
    35 <div class="section" id="compiling-with-llvmc">
    36

    Compiling with LLVMC

    3637

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

    3738 much as possible, so most of the familiar options work:

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

    4647
    47
    48

    Using LLVMC to generate toolchain drivers

    49 <p>LLVMC plugins are written mostly using TableGen, so you need to
    48 <div class="section" id="using-llvmc-to-generate-toolchain-drivers">
    49

    Using LLVMC to generate toolchain drivers

    50

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

    5051 be familiar with it to get anything done.

    5152

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

    5253 wrapper for gcc:

    7171
    7272 /* It is preferrable to use
     everywhere instead of the
    
                      
                    
    7373 *
    ...
    construct.
    74 *
    74 *
    7575 * Once all docs use
     for code regions, this style can  be merged with the
    
                      
                    
    7676 * one above, and we can drop the [pre] qualifier.
    7777 */
    9494
    9595 /* ReST-specific */
    9696 .title { margin-top: 0 }
    97 #contents { display: none }
    97 .topic-title{ display: none }
    9898 div.contents ul { list-style-type: decimal }
    9999 .toc-backref { color: black; text-decoration: none; }