tools/llvmc2/doc/LLVMCC-Tutorial.rst

   1 Tutorial - Writing LLVMCC Configuration files
   2 =============================================
   3
   4 LLVMCC is a generic compiler driver (just like ``gcc``), designed to be
   5 customizable and extensible. Its job is essentially to transform a set
   6 of input files into a set of targets, depending on configuration rules
   7 and user options. This tutorial describes how one can write
   8 configuration files for ``llvmcc``.
   9
  10 Because LLVMCC uses TableGen [1]_ as the language of its configuration
  11 files, you need to be familiar with it.
  12
  13 Describing a toolchain
  14 ----------------------
  15
  16 The main concept that ``llvmcc`` operates with is a *toolchain*, which
  17 is just a list of tools that process input files in a pipeline-like
  18 fashion. Toolchain definitions look like this::
  19
  20    def ToolChains : ToolChains<[
  21        ToolChain<[llvm_gcc_c, llc, llvm_gcc_assembler, llvm_gcc_linker]>,
  22        ToolChain<[llvm_gcc_cpp, llc, llvm_gcc_assembler, llvm_gcc_linker]>,
  23        ...
  24        ]>;
  25
  26 Every configuration file should have a single toolchains list called
  27 ``ToolChains``.
  28
  29 At the time of writing, ``llvmcc`` does not support mixing various
  30 toolchains together - in other words, all input files should be in the
  31 same language.
  32
  33 Another temporary limitation is that every toolchain should end with a
  34 "join" node - a linker-like program that combines its inputs into a
  35 single output file.
  36
  37 Describing a tool
  38 -----------------
  39
  40 A single element of a toolchain is a tool. A tool definition looks
  41 like this (taken from the Tools.td file)::
  42
  43   def llvm_gcc_cpp : Tool<[
  44       (in_language "c++"),
  45       (out_language "llvm-assembler"),
  46       (output_suffix "bc"),
  47       (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
  48       (sink)
  49       ]>;
  50
  51 This defines a new tool called ``llvm_gcc_cpp``, which is an alias for
  52 ``llvm-g++``. As you can see, a tool definition is just a list of
  53 properties; most of them should be self-evident. The ``sink`` property
  54 means that this tool should be passed all command-line options that
  55 aren't handled by the other tools.
  56
  57 The complete list of the currently implemented tool properties follows:
  58
  59 * Possible tool properties:
  60   - in_language - input language name.
  61
  62   - out_language - output language name.
  63
  64   - output_suffix - output file suffix.
  65
  66   - cmd_line - the actual command used to run the tool. You can use
  67     ``$INFILE`` and ``$OUTFILE`` variables.
  68
  69   - join - this tool is a "join node" in the graph, i.e. it gets a
  70     list of input files and joins them together. Used for linkers.
  71
  72   - sink - all command-line options that are not handled by other
  73     tools are passed to this tool.
  74
  75 The next tool definition is slightly more complex::
  76
  77   def llvm_gcc_linker : Tool<[
  78       (in_language "object-code"),
  79       (out_language "executable"),
  80       (output_suffix "out"),
  81       (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
  82       (join),
  83       (prefix_list_option "L", (forward), (help "add a directory to link path")),
  84       (prefix_list_option "l", (forward), (help "search a library when linking")),
  85       (prefix_list_option "Wl", (unpack_values), (help "pass options to linker"))
  86       ]>;
  87
  88 This tool has a "join" property, which means that it behaves like a
  89 linker (because of that this tool should be the last in the
  90 toolchain). This tool also defines several command-line options: ``-l``,
  91 ``-L`` and ``-Wl`` which have their usual meaning. An option has two
  92 attributes: a name and a (possibly empty) list of properties. All
  93 currently implemented option types and properties are described below:
  94
  95 * Possible option types:
  96    - switch_option - a simple boolean switch, for example ``-time``.
  97
  98    - parameter_option - option that takes an argument, for example ``-std=c99``;
  99
 100    - parameter_list_option - same as the above, but more than one
 101      occurence of the option is allowed.
 102
 103    - prefix_option - same as the parameter_option, but the option name
 104      and parameter value are not separated.
 105
 106    - prefix_list_option - same as the above, but more than one
 107      occurence of the option is allowed; example: ``-lm -lpthread``.
 108
 109 * Possible option properties:
 110    - append_cmd - append a string to the tool invocation command.
 111
 112    - forward - forward this option unchanged.
 113
 114    - stop_compilation - stop compilation after this phase.
 115
 116    - unpack_values - used for for splitting and forwarding
 117      comma-separated lists of options, e.g. ``-Wa,-foo=bar,-baz`` is
 118      converted to ``-foo=bar -baz`` and appended to the tool invocation
 119      command.
 120
 121    - help - help string associated with this option.
 122
 123    - required - this option is obligatory.
 124
 125 Language map
 126 ------------
 127
 128 One last bit that you probably should change is the language map,
 129 which defines mappings between language names and file extensions. It
 130 is used internally to choose the proper toolchain based on the names
 131 of the input files. Language map definition is located in the file
 132 ``Tools.td`` and looks like this::
 133
 134     def LanguageMap : LanguageMap<
 135         [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
 136          LangToSuffixes<"c", ["c"]>,
 137          ...
 138         ]>;
 139
 140
 141 Putting it all together
 142 -----------------------
 143
 144 Since at the time of writing LLVMCC does not support on-the-fly
 145 reloading of the configuration, the only way to test your changes is
 146 to recompile the program. To do this, ``cd`` to the source code
 147 directory and run ``make``.
 148
 149 References
 150 ==========
 151
 152 .. [1] TableGen Fundamentals
 153        http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html