tools/llvmc2/doc/LLVMC-Tutorial.rst

   1 ======================
   2 Tutorial - Using LLVMC
   3 ======================
   4
   5 LLVMC is a generic compiler driver, which plays the same role for LLVM
   6 as the ``gcc`` program does for GCC - the difference being that LLVMC
   7 is designed to be more adaptable and easier to customize. This
   8 tutorial describes the basic usage and configuration of LLVMC.
   9
  10
  11 .. contents::
  12
  13
  14 Compiling with LLVMC
  15 ====================
  16
  17 In general, LLVMC tries to be command-line compatible with ``gcc`` as
  18 much as possible, so most of the familiar options work::
  19
  20      $ llvmc2 -O3 -Wall hello.cpp
  21      $ ./a.out
  22      hello
  23
  24 For further help on command-line LLVMC usage, refer to the ``llvmc
  25 --help`` output.
  26
  27 Using LLVMC to generate toolchain drivers
  28 =========================================
  29
  30 At the time of writing LLVMC does not support on-the-fly reloading of
  31 configuration, so it will be necessary to recompile its source
  32 code. LLVMC uses TableGen [1]_ as its configuration language, so
  33 you'll need to familiar with it.
  34
  35 Start by compiling ``examples/Simple.td``, which is a simple wrapper
  36 for ``gcc``::
  37
  38     $ cd $LLVM_DIR/tools/llvmc2
  39     $ make TOOLNAME=mygcc GRAPH=examples/Simple.td
  40     $ edit hello.c
  41     $ mygcc hello.c
  42     $ ./hello.out
  43     Hello
  44
  45 Contents of the file ``Simple.td`` look like this::
  46
  47     // Include common definitions
  48     include "Common.td"
  49
  50     // Tool descriptions
  51     def gcc : Tool<
  52     [(in_language "c"),
  53      (out_language "executable"),
  54      (output_suffix "out"),
  55      (cmd_line "gcc $INFILE -o $OUTFILE"),
  56      (sink)
  57     ]>;
  58
  59     // Language map
  60     def LanguageMap : LanguageMap<[LangToSuffixes<"c", ["c"]>]>;
  61
  62     // Compilation graph
  63     def CompilationGraph : CompilationGraph<[Edge<root, gcc>]>;
  64
  65 As you can see, this file consists of three parts: tool descriptions,
  66 language map, and the compilation graph definition.
  67
  68 At the heart of LLVMC is the idea of a transformation graph: vertices
  69 in this graph are tools, and edges signify that there is a
  70 transformation path between two tools (for example, assembly source
  71 produced by the compiler can be transformed into executable code by an
  72 assembler). A special node named ``root`` is used to mark the graph
  73 entry points.
  74
  75 Tool descriptions are basically lists of properties: most properties
  76 in the example above should be self-explanatory; the ``sink`` property
  77 means that all options lacking an explicit description should be
  78 forwarded to this tool.
  79
  80 ``LanguageMap`` associates a language name with a list of suffixes and
  81 is used for deciding which toolchain corresponds to a given input
  82 file.
  83
  84 To learn more about LLVMC customization, refer to the reference
  85 manual and sample configuration files in the ``examples`` directory.
  86
  87 References
  88 ==========
  89
  90 .. [1] TableGen Fundamentals
  91        http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
  92