tools/llvmc/doc/LLVMC-Tutorial.rst

   1 ======================
   2 Tutorial - Using LLVMC
   3 ======================
   4 :Author: Mikhail Glushenkov <foldr@codedegers.com>
   5
   6 LLVMC is a generic compiler driver, which plays the same role for LLVM
   7 as the ``gcc`` program does for GCC - the difference being that LLVMC
   8 is designed to be more adaptable and easier to customize. Most of
   9 LLVMC functionality is implemented via plugins, which can be loaded
  10 dynamically or compiled in. This tutorial describes the basic usage
  11 and configuration of LLVMC.
  12
  13
  14 .. contents::
  15
  16
  17 Compiling with LLVMC
  18 ====================
  19
  20 In general, LLVMC tries to be command-line compatible with ``gcc`` as
  21 much as possible, so most of the familiar options work::
  22
  23      $ llvmc -O3 -Wall hello.cpp
  24      $ ./a.out
  25      hello
  26
  27 This will invoke ``llvm-g++`` under the hood (you can see which
  28 commands are executed by using the ``-v`` option). For further help on
  29 command-line LLVMC usage, refer to the ``llvmc --help`` output.
  30
  31
  32 Using LLVMC to generate toolchain drivers
  33 =========================================
  34
  35 LLVMC plugins are written mostly using TableGen [1]_, so you need to
  36 be familiar with it to get anything done.
  37
  38 Start by compiling ``plugins/Simple/Simple.td``, which is a primitive
  39 wrapper for ``gcc``::
  40
  41     $ cd $LLVM_DIR/tools/llvmc
  42     $ make DRIVER_NAME=mygcc BUILTIN_PLUGINS=Simple
  43     $ cat > hello.c
  44     [...]
  45     $ mygcc hello.c
  46     $ ./hello.out
  47     Hello
  48
  49 Here we link our plugin with the LLVMC core statically to form an
  50 executable file called ``mygcc``. It is also possible to build our
  51 plugin as a standalone dynamic library; this is described in the
  52 reference manual.
  53
  54 Contents of the file ``Simple.td`` look like this::
  55
  56     // Include common definitions
  57     include "llvm/CompilerDriver/Common.td"
  58
  59     // Tool descriptions
  60     def gcc : Tool<
  61     [(in_language "c"),
  62      (out_language "executable"),
  63      (output_suffix "out"),
  64      (cmd_line "gcc $INFILE -o $OUTFILE"),
  65      (sink)
  66     ]>;
  67
  68     // Language map
  69     def LanguageMap : LanguageMap<[LangToSuffixes<"c", ["c"]>]>;
  70
  71     // Compilation graph
  72     def CompilationGraph : CompilationGraph<[Edge<"root", "gcc">]>;
  73
  74 As you can see, this file consists of three parts: tool descriptions,
  75 language map, and the compilation graph definition.
  76
  77 At the heart of LLVMC is the idea of a compilation graph: vertices in
  78 this graph are tools, and edges represent a transformation path
  79 between two tools (for example, assembly source produced by the
  80 compiler can be transformed into executable code by an assembler). The
  81 compilation graph is basically a list of edges; a special node named
  82 ``root`` is used to mark graph entry points.
  83
  84 Tool descriptions are represented as property lists: most properties
  85 in the example above should be self-explanatory; the ``sink`` property
  86 means that all options lacking an explicit description should be
  87 forwarded to this tool.
  88
  89 The ``LanguageMap`` associates a language name with a list of suffixes
  90 and is used for deciding which toolchain corresponds to a given input
  91 file.
  92
  93 To learn more about LLVMC customization, refer to the reference
  94 manual and plugin source code in the ``plugins`` directory.
  95
  96 References
  97 ==========
  98
  99 .. [1] TableGen Fundamentals
 100        http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html