1 Tutorial - Writing LLVMCC Configuration files
2 =============================================
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``.
10 Since LLVMCC uses TableGen [1]_ as the language of its configuration
11 files, you need to be familiar with it.
13 Describing a toolchain
14 ----------------------
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::
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]>,
26 Every configuration file should have a single toolchains list called
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
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
40 A single element of a toolchain is a tool. A tool definition looks
41 like this (taken from the Tools.td file)::
43 def llvm_gcc_cpp : Tool<[
45 (out_language "llvm-assembler"),
47 (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
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.
57 The complete list of the currently implemented tool properties follows:
59 * Possible tool properties:
60 - in_language - input language name.
62 - out_language - output language name.
64 - output_suffix - output file suffix.
66 - cmd_line - the actual command used to run the tool. You can use
67 ``$INFILE`` and ``$OUTFILE`` variables.
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.
72 - sink - all command-line options that are not handled by other
73 tools are passed to this tool.
75 The next tool definition is slightly more complex::
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"),
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"))
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:
95 * Possible option types:
96 - switch_option - a simple boolean switch, for example ``-time``.
98 - parameter_option - option that takes an argument, for example ``-std=c99``;
100 - parameter_list_option - same as the above, but more than one
101 occurence of the option is allowed.
103 - prefix_option - same as the parameter_option, but the option name
104 and parameter value are not separated.
106 - prefix_list_option - same as the above, but more than one
107 occurence of the option is allowed; example: ``-lm -lpthread``.
109 * Possible option properties:
110 - append_cmd - append a string to the tool invocation command.
112 - forward - forward this option unchanged.
114 - stop_compilation - stop compilation after this phase.
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
121 - help - help string associated with this option.
123 - required - this option is obligatory.
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::
134 def LanguageMap : LanguageMap<
135 [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
136 LangToSuffixes<"c", ["c"]>,
141 Putting it all together
142 -----------------------
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``.
152 .. [1] TableGen Fundamentals
153 http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html