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 as the
  21 ``gcc`` program does for GCC - the difference being that LLVMC is designed to be
  22 more adaptable and easier to customize. Most of LLVMC functionality is
  23 implemented via high-level TableGen code, from which a corresponding C++ source
  24 file is automatically generated. This tutorial describes the basic usage and
  25 configuration of LLVMC.
  26
  27
  28 Using the ``llvmc`` program
  29 ===========================
  30
  31 In general, ``llvmc`` tries to be command-line compatible with ``gcc`` as much
  32 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 commands are
  39 executed by using the ``-v`` option). For further help on command-line LLVMC
  40 usage, refer to the ``llvmc --help`` output.
  41
  42
  43 Using LLVMC to generate toolchain drivers
  44 =========================================
  45
  46 LLVMC-based drivers are written mostly using TableGen_, so you need to be
  47 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_OBJ_DIR/tools/examples/Simple
  55     $ make
  56     $ cat > hello.c
  57     #include <stdio.h>
  58     int main() { printf("Hello\n"); }
  59     $ $LLVM_BIN_DIR/Simple -v hello.c
  60     gcc hello.c -o hello.out
  61     $ ./hello.out
  62     Hello
  63
  64 We have thus produced a simple driver called, appropriately, ``Simple``, from
  65 the input TableGen file ``Simple.td``. The ``llvmc`` program itself is generated
  66 using a similar process (see ``llvmc/src``). Contents of the file ``Simple.td``
  67 look like this::
  68
  69     // Include common definitions
  70     include "llvm/CompilerDriver/Common.td"
  71
  72     // Tool descriptions
  73     def gcc : Tool<
  74     [(in_language "c"),
  75      (out_language "executable"),
  76      (output_suffix "out"),
  77      (command "gcc"),
  78      (sink),
  79
  80      // -o is what is used by default, out_file_option here is included for
  81      // instructive purposes.
  82      (out_file_option "-o")
  83     ]>;
  84
  85     // Language map
  86     def LanguageMap : LanguageMap<[(lang_to_suffixes "c", "c")]>;
  87
  88     // Compilation graph
  89     def CompilationGraph : CompilationGraph<[(edge "root", "gcc")]>;
  90
  91 As you can see, this file consists of three parts: tool descriptions, language
  92 map, and the compilation graph definition.
  93
  94 At the heart of LLVMC is the idea of a compilation graph: vertices in this graph
  95 are tools, and edges represent a transformation path between two tools (for
  96 example, assembly source produced by the compiler can be transformed into
  97 executable code by an assembler). The compilation graph is basically a list of
  98 edges; a special node named ``root`` is used to mark graph entry points.
  99
 100 Tool descriptions are represented as property lists: most properties in the
 101 example above should be self-explanatory; the ``sink`` property means that all
 102 options lacking an explicit description should be forwarded to this tool.
 103
 104 The ``LanguageMap`` associates a language name with a list of suffixes and is
 105 used for deciding which toolchain corresponds to a given input file.
 106
 107 To learn more about writing your own drivers with LLVMC, refer to the reference
 108 manual and examples in the ``examples`` directory. Of a particular interest is
 109 the ``Skeleton`` example, which can serve as a template for your LLVMC-based
 110 drivers.
 111
 112 .. raw:: html
 113
 114    <hr />
 115    <address>
 116    <a href="http://jigsaw.w3.org/css-validator/check/referer">
 117    <img src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
 118       alt="Valid CSS" /></a>
 119    <a href="http://validator.w3.org/check?uri=referer">
 120    <img src="http://www.w3.org/Icons/valid-xhtml10-blue"
 121       alt="Valid XHTML 1.0 Transitional"/></a>
 122
 123    <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
 124    <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
 125
 126    Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
 127    </address>