tools/llvmc/doc/LLVMC-Tutorial.rst

   1 ======================
   2 Tutorial - Using LLVMC
   3 ======================
   4 ..
   5    This file was automatically generated by rst2html.
   6    Please do not edit directly!
   7    The ReST source lives in the directory 'tools/llvmc/doc'.
   8
   9 .. contents::
  10
  11 .. raw:: html
  12
  13    <div class="doc_author">
  14    <p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p>
  15    </div>
  16
  17 Introduction
  18 ============
  19
  20 LLVMC is a generic compiler driver, which plays the same role for LLVM
  21 as the ``gcc`` program does for GCC - the difference being that LLVMC
  22 is designed to be more adaptable and easier to customize. Most of
  23 LLVMC functionality is implemented via plugins, which can be loaded
  24 dynamically or compiled in. This tutorial describes the basic usage
  25 and configuration of LLVMC.
  26
  27
  28 Compiling with LLVMC
  29 ====================
  30
  31 In general, LLVMC tries to be command-line compatible with ``gcc`` as
  32 much as possible, so most of the familiar options work::
  33
  34      $ llvmc -O3 -Wall hello.cpp
  35      $ ./a.out
  36      hello
  37
  38 This will invoke ``llvm-g++`` under the hood (you can see which
  39 commands are executed by using the ``-v`` option). For further help on
  40 command-line LLVMC usage, refer to the ``llvmc --help`` output.
  41
  42
  43 Using LLVMC to generate toolchain drivers
  44 =========================================
  45
  46 LLVMC plugins are written mostly using TableGen_, so you need to
  47 be familiar with it to get anything done.
  48
  49 .. _TableGen: http://llvm.org/docs/TableGenFundamentals.html
  50
  51 Start by compiling ``example/Simple``, which is a primitive wrapper for
  52 ``gcc``::
  53
  54     $ cd $LLVM_DIR/tools/llvmc
  55     $ cp -r example/Simple 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
  61     $ cat > hello.c
  62     [...]
  63     $ mygcc hello.c
  64     $ ./hello.out
  65     Hello
  66
  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.
  71
  72 Contents of the file ``Simple.td`` look like this::
  73
  74     // Include common definitions
  75     include "llvm/CompilerDriver/Common.td"
  76
  77     // Tool descriptions
  78     def gcc : Tool<
  79     [(in_language "c"),
  80      (out_language "executable"),
  81      (output_suffix "out"),
  82      (cmd_line "gcc $INFILE -o $OUTFILE"),
  83      (sink)
  84     ]>;
  85
  86     // Language map
  87     def LanguageMap : LanguageMap<[LangToSuffixes<"c", ["c"]>]>;
  88
  89     // Compilation graph
  90     def CompilationGraph : CompilationGraph<[Edge<"root", "gcc">]>;
  91
  92 As you can see, this file consists of three parts: tool descriptions,
  93 language map, and the compilation graph definition.
  94
  95 At the heart of LLVMC is the idea of a compilation graph: vertices in
  96 this graph are tools, and edges represent a transformation path
  97 between two tools (for example, assembly source produced by the
  98 compiler can be transformed into executable code by an assembler). The
  99 compilation graph is basically a list of edges; a special node named
 100 ``root`` is used to mark graph entry points.
 101
 102 Tool descriptions are represented as property lists: most properties
 103 in the example above should be self-explanatory; the ``sink`` property
 104 means that all options lacking an explicit description should be
 105 forwarded to this tool.
 106
 107 The ``LanguageMap`` associates a language name with a list of suffixes
 108 and is used for deciding which toolchain corresponds to a given input
 109 file.
 110
 111 To learn more about LLVMC customization, refer to the reference
 112 manual and plugin source code in the ``plugins`` directory.
 113
 114 .. raw:: html
 115
 116    <hr />
 117    <address>
 118    <a href="http://jigsaw.w3.org/css-validator/check/referer">
 119    <img src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
 120       alt="Valid CSS" /></a>
 121    <a href="http://validator.w3.org/check?uri=referer">
 122    <img src="http://www.w3.org/Icons/valid-xhtml10-blue"
 123       alt="Valid XHTML 1.0 Transitional"/></a>
 124
 125    <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
 126    <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
 127
 128    Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
 129    </address>