llvm.org GIT mirror llvm / d565203
More cosmetic tweaks for llvmc docs. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@60969 91177308-0d34-0410-b5e6-96231b3b80d8 Mikhail Glushenkov 10 years ago
7 changed file(s) with 159 addition(s) and 175 deletion(s). Raw diff Collapse all Expand all
44
55
66 Customizing LLVMC: Reference Manual
7
87
98
109
1110
1211

Customizing LLVMC: Reference Manual

13
14
15
16
17
Author:
18 Mikhail Glushenkov <foldr@codedegers.com>
19
20 </table>
12 <div class="contents topic">
13

Contents

14
15
  • Introduction
  • 16
  • Compiling with LLVMC
  • 17
  • Predefined options
  • 18
  • Compiling LLVMC plugins
  • 19
  • Customizing LLVMC: the compilation graph
  • 20
  • Describing options
  • 21
  • External options
  • 22
    23
    24
  • Conditional evaluation
  • 25
  • Writing a tool description
  • 26
  • Actions
  • 27
    28
    29
  • Language map
  • 30
  • More advanced topics
  • 31
  • Hooks and environment variables
  • 32
  • How plugins are loaded
  • 33
  • Debugging
  • 34
    35
    36
    37
    38
    39

    Written by Mikhail Glushenkov

    40
    41

    Introduction

    2142

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

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

    33

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

    54

    Because LLVMC employs TableGen as its configuration language, you

    3455 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 <h1>Compiling with LLVMC>
    56 </div>
    57
    58

    Compiling with LLVMC

    6359

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

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

    9793 the -clang option.

    9894
    9995
    100

    Predefined options

    96

    Predefined options

    10197

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

    10298 configuration libraries:

    10399
    120116
    121117
    122118
    123

    Compiling LLVMC plugins

    119

    Compiling LLVMC plugins

    124120

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

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

    126122
    
                      
                    
    173169
    174170
    175171
    176

    Customizing LLVMC: the compilation graph

    172

    Customizing LLVMC: the compilation graph

    177173

    Each TableGen configuration file should include the common

    178174 definitions:

    179175
    
                      
                    
    241237 gsview installed for this to work properly.

    242238
    243239
    244

    Describing options

    240

    Describing options

    245241

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

    246242 OptionList:

    247243
    
                      
                    
    292288
    293289
    294290
    295

    External options

    291

    External options

    296292

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

    297293 access options defined in some other plugin. Because of the way
    298294 options are implemented, such options should be marked as
    307303
    308304
    309305
    310

    Conditional evaluation

    306

    Conditional evaluation

    311307

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

    312308 achieved in LLVMC. It can be used to calculate edge weights, program
    313309 actions and modify the shell commands to be executed. The 'case'
    385381
    386382
    387383
    388

    Writing a tool description

    384

    Writing a tool description

    389385

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

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

    427423
    428424
    429425
    430

    Actions

    426

    Actions

    431427

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

    432428 precisely what the actions property is for. The next example
    433429 illustrates this feature:

    485481
    486482
    487483
    488

    Language map

    484

    Language map

    489485

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

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

    509505
    510506
    511

    More advanced topics

    512
    513 2>Hooks and environment variables>
    507 1>More advanced topics>
    508
    509

    Hooks and environment variables

    514510

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

    515511 this is not sufficient: for example, we may want to specify tool names
    516512 in the configuration file. This can be achieved via the mechanism of
    538534
    539535
    540536
    541

    How plugins are loaded

    537

    How plugins are loaded

    542538

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

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

    555551
    556552
    557

    Debugging

    553

    Debugging

    558554

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

    559555 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
    556 line option --view-graph. This command assumes that Graphviz and
    557 Ghostview are installed. There is also a --dump-graph option that
    558 creates a Graphviz source file (compilation-graph.dot) in the
    563559 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
    589560
    590561
    591
    592 alt="Valid CSS" />
    593
    594 alt="Valid XHTML 1.0 Transitional"/>
    595
    596 Mikhail Glushenkov
    597 LLVM Compiler Infrastructure
    598
    599 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    600 </address>
    562 <a href="http://jigsaw.w3.org/css-validator/check/referer">
    563
    564 alt="Valid CSS" />
    565
    566
    567 alt="Valid XHTML 1.0 Transitional"/>
    568
    569 Mikhail Glushenkov
    570 LLVM Compiler Infrastructure
    571
    572 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    573
    601574
    602575
    603576
    44
    55
    66 Tutorial - Using LLVMC
    7
    87
    98
    109
    1110
    1211

    Tutorial - Using LLVMC

    13
    14
    15
    16
    17
    Author:
    18 Mikhail Glushenkov <foldr@codedegers.com>
    19
    20 </table>
    12 <div class="contents topic">
    13

    Contents

    14
    15
  • Introduction
  • 16
  • Compiling with LLVMC
  • 17
  • Using LLVMC to generate toolchain drivers
  • 18
    19
    20
    21

    Written by Mikhail Glushenkov

    22
    23

    Introduction

    2124

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

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

    27
    28

    Contents

    29
    30
  • Compiling with LLVMC
  • 31
  • Using LLVMC to generate toolchain drivers
  • 32
  • References
  • 33
    3430
    3531
    36

    Compiling with LLVMC

    32

    Compiling with LLVMC

    3733

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

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

    3935
    
                      
                    
    4642 command-line LLVMC usage, refer to the llvmc --help output.

    4743
    4844
    49

    Using LLVMC to generate toolchain drivers

    50 <p>LLVMC plugins are written mostly using TableGen [1], so you need to
    45 <h1>Using LLVMC to generate toolchain drivers
    46

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

    5147 be familiar with it to get anything done.

    5248

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

    5349 wrapper for gcc:

    10197 file.

    10298

    To learn more about LLVMC customization, refer to the reference

    10399 manual and plugin source code in the plugins directory.

    104
    105
    106

    References

    107
    108
    109
    110
    [1]TableGen Fundamentals
    111 http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
    112
    113
    114100
    115101
    116
    117 alt="Valid CSS" />
    118
    119 alt="Valid XHTML 1.0 Transitional"/>>
    102 >
    103
    104 alt="Valid CSS" />
    105
    106
    107 alt="Valid XHTML 1.0 Transitional"/>
    120108
    121 Mikhail Glushenkov
    122 LLVM Compiler Infrastructure
    109 Mikhail Glushenkov
    110 LLVM Compiler Infrastructure
    123111
    124 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    125
    126
    112 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    113
    127114
    128115
    129116
    4040 margin: 20pt 0pt 5pt 0pt;
    4141 }
    4242
    43 .title { padding-top: 0; margin-top: 0; text-align: left; font-size: 25pt }
    43 .title { padding-top: 0; margin-top: 0; text-align: left;
    44 font-size: 25pt }
    45
    46 #contents { font-weight: bold; }
    4447 h2 { width: 75%;
    4548 text-align: left; font-size: 12pt; padding: 4pt 4pt 4pt 4pt;
    4649 margin: 1.5em 0.5em 0.5em 0.5em }
    6669
    6770 .literal-block { border: solid 1px gray; background: #eeeeee;
    6871 margin: 0 1em 0 1em;
    69 padding: 0 1em 0 1em;
    72 padding: 1em 2em 1em 1em;
    7073 display:table;
    7174 }
    7275 .doc_notes { background: #fafafa; border: 1px solid #cecece; padding: 0.1em }
    0 ===================================
    11 Customizing LLVMC: Reference Manual
    22 ===================================
    3 :Author: Mikhail Glushenkov
    3
    4 .. contents::
    5
    6 .. raw:: html
    7
    8
    9

    Written by Mikhail Glushenkov

    10
    11
    12 Introduction
    13 ============
    414
    515 LLVMC is a generic compiler driver, designed to be customizable and
    616 extensible. It plays the same role for LLVM as the ``gcc`` program
    1525 makes it possible to easily adapt LLVMC for other purposes - for
    1626 example, as a build tool for game resources.
    1727
    18 Because LLVMC employs TableGen [1]_ as its configuration language, you
    28 Because LLVMC employs TableGen_ as its configuration language, you
    1929 need to be familiar with it to customize LLVMC.
    2030
    21
    22 .. contents::
    31 .. _TableGen: http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
    2332
    2433
    2534 Compiling with LLVMC
    579588
    580589 When writing LLVMC plugins, it can be useful to get a visual view of
    581590 the resulting compilation graph. This can be achieved via the command
    582 line option ``--view-graph``. This command assumes that Graphviz [2]_ and
    583 Ghostview [3]_ are installed. There is also a ``--dump-graph`` option that
    584 creates a Graphviz source file(``compilation-graph.dot``) in the
    591 line option ``--view-graph``. This command assumes that Graphviz_ and
    592 Ghostview_ are installed. There is also a ``--dump-graph`` option that
    593 creates a Graphviz source file (``compilation-graph.dot``) in the
    585594 current directory.
    586595
    587
    588 References
    589 ==========
    590
    591 .. [1] TableGen Fundamentals
    592 http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
    593
    594 .. [2] Graphviz
    595 http://www.graphviz.org/
    596
    597 .. [3] Ghostview
    598 http://pages.cs.wisc.edu/~ghost/
    596 .. _Graphviz: http://www.graphviz.org/
    597 .. _Ghostview: http://pages.cs.wisc.edu/~ghost/
    599598
    600599 .. raw:: html
    601 :file: footer.html
    600
    601
    602
    603
    604
    605 alt="Valid CSS" />
    606
    607
    608 alt="Valid XHTML 1.0 Transitional"/>
    609
    610 Mikhail Glushenkov
    611 LLVM Compiler Infrastructure
    612
    613 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    614
    0 ======================
    11 Tutorial - Using LLVMC
    22 ======================
    3 :Author: Mikhail Glushenkov
    3
    4 .. contents::
    5
    6 .. raw:: html
    7
    8
    9

    Written by Mikhail Glushenkov

    10
    11
    12 Introduction
    13 ============
    414
    515 LLVMC is a generic compiler driver, which plays the same role for LLVM
    616 as the ``gcc`` program does for GCC - the difference being that LLVMC
    818 LLVMC functionality is implemented via plugins, which can be loaded
    919 dynamically or compiled in. This tutorial describes the basic usage
    1020 and configuration of LLVMC.
    11
    12
    13 .. contents::
    1421
    1522
    1623 Compiling with LLVMC
    3138 Using LLVMC to generate toolchain drivers
    3239 =========================================
    3340
    34 LLVMC plugins are written mostly using TableGen [1]_, so you need to
    41 LLVMC plugins are written mostly using TableGen_, so you need to
    3542 be familiar with it to get anything done.
    43
    44 .. _TableGen: http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
    3645
    3746 Start by compiling ``plugins/Simple/Simple.td``, which is a primitive
    3847 wrapper for ``gcc``::
    92101 To learn more about LLVMC customization, refer to the reference
    93102 manual and plugin source code in the ``plugins`` directory.
    94103
    95 References
    96 ==========
    104 .. raw:: html
    97105
    98 .. [1] TableGen Fundamentals
    99 http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
    106
    107
    108
    109
    110 alt="Valid CSS" />
    111
    112
    113 alt="Valid XHTML 1.0 Transitional"/>
    100114
    101 .. raw:: html
    102 :file: footer.html
    115 Mikhail Glushenkov
    116 LLVM Compiler Infrastructure
    117
    118 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    119
    +0
    -12
    tools/llvmc/doc/footer.html less more
    None
    1
    2
    3 alt="Valid CSS" />
    4
    5 alt="Valid XHTML 1.0 Transitional"/>
    6
    7 Mikhail Glushenkov
    8 LLVM Compiler Infrastructure
    9
    10 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    11
    4040 margin: 20pt 0pt 5pt 0pt;
    4141 }
    4242
    43 .title { padding-top: 0; margin-top: 0; text-align: left; font-size: 25pt }
    43 .title { padding-top: 0; margin-top: 0; text-align: left;
    44 font-size: 25pt }
    45
    46 #contents { font-weight: bold; }
    4447 h2 { width: 75%;
    4548 text-align: left; font-size: 12pt; padding: 4pt 4pt 4pt 4pt;
    4649 margin: 1.5em 0.5em 0.5em 0.5em }
    6669
    6770 .literal-block { border: solid 1px gray; background: #eeeeee;
    6871 margin: 0 1em 0 1em;
    69 padding: 0 1em 0 1em;
    72 padding: 1em 2em 1em 1em;
    7073 display:table;
    7174 }
    7275 .doc_notes { background: #fafafa; border: 1px solid #cecece; padding: 0.1em }