llvm.org GIT mirror llvm / 77ddce9
Update documentation to reflect the current state of affairs. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@50763 91177308-0d34-0410-b5e6-96231b3b80d8 Mikhail Glushenkov 12 years ago
1 changed file(s) with 176 addition(s) and 80 deletion(s). Raw diff Collapse all Expand all
None Tutorial - Writing LLVMCC Configuration files
0 Tutorial - Writing LLVMC Configuration files
11 =============================================
22
3 LLVMCC is a generic compiler driver (just like ``gcc``), designed to be
4 customizable and extensible. Its job is essentially to transform a set
5 of input files into a set of targets, depending on configuration rules
6 and user options. This tutorial describes how one can write
7 configuration files for ``llvmcc``.
8
9 Because LLVMCC uses TableGen [1]_ as the language of its configuration
10 files, you need to be familiar with it.
11
12 Describing a toolchain
13 ----------------------
14
15 The main concept that ``llvmcc`` operates with is a *toolchain*, which
16 is just a list of tools that process input files in a pipeline-like
17 fashion. Toolchain definitions look like this::
18
19 def ToolChains : ToolChains<[
20 ToolChain<[llvm_gcc_c, llc, llvm_gcc_assembler, llvm_gcc_linker]>,
21 ToolChain<[llvm_gcc_cpp, llc, llvm_gcc_assembler, llvm_gcc_linker]>,
22 ...
23 ]>;
24
25 Every configuration file should have a single toolchains list called
26 ``ToolChains``.
27
28 At the time of writing, ``llvmcc`` does not support mixing various
29 toolchains together - in other words, all input files should be in the
30 same language.
31
32 Another temporary limitation is that every toolchain should end with a
33 "join" node - a linker-like program that combines its inputs into a
34 single output file.
35
36 Describing a tool
37 -----------------
38
39 A single element of a toolchain is a tool. A tool definition looks
40 like this (taken from the Tools.td file)::
3 LLVMC is a generic compiler driver, designed to be customizable and
4 extensible. It plays the same role for LLVM as the ``gcc`` program
5 does for GCC - LLVMC's job is essentially to transform a set of input
6 files into a set of targets depending on configuration rules and user
7 options. What makes LLVMC different is that these transformation rules
8 are completely customizable - in fact, LLVMC knows nothing about the
9 specifics of transformation (even the command-line options are mostly
10 not hard-coded) and regards the transformation structure as an
11 abstract graph. This makes it possible to adapt LLVMC for other
12 purposes - for example, as a build tool for game resources. This
13 tutorial describes the basic usage and configuration of LLVMC.
14
15 Because LLVMC employs TableGen [1]_ as its configuration language, you
16 need to be familiar with it to customize LLVMC.
17
18 Compiling with LLVMC
19 --------------------
20
21 In general, LLVMC tries to be command-line compatible with ``gcc`` as
22 much as possible, so most of the familiar options work::
23
24 $ llvmc2 -O3 -Wall hello.cpp
25 $ ./a.out
26 hello
27
28 One nice feature of LLVMC is that you don't have to distinguish
29 between different compilers for different languages (think ``g++`` and
30 ``gcc``) - the right toolchain is chosen automatically based on input
31 language names (which are, in turn, determined from file extension). If
32 you want to force files ending with ".c" compile as C++, use the
33 ``-x`` option, just like you would do it with ``gcc``::
34
35 $ llvmc2 -x c hello.cpp
36 $ # hello.cpp is really a C file
37 $ ./a.out
38 hello
39
40 On the other hand, when using LLVMC as a linker to combine several C++
41 object files you should provide the ``--linker`` option since it's
42 impossible for LLVMC to choose the right linker in that case::
43
44 $ llvmc2 -c hello.cpp
45 $ llvmc2 hello.o
46 [A lot of link-time errors skipped]
47 $ llvmc2 --linker=c++ hello.o
48 $ ./a.out
49 hello
50
51 For further help on command-line LLVMC usage, refer to the ``llvmc
52 --help`` output.
53
54 Customizing LLVMC: the compilation graph
55 ----------------------------------------
56
57 At the time of writing LLVMC does not support on-the-fly reloading of
58 configuration, so to customize LLVMC you'll have to edit and recompile
59 the source code (which lives under ``$LLVM_DIR/tools/llvmc2``). The
60 relevant files are ``Common.td``, ``Tools.td`` and ``Example.td``.
61
62 Internally, LLVMC stores information about possible transformations in
63 form of a graph. Nodes in this graph represent tools, and edges
64 between two nodes represent a transformation path. A special "root"
65 node represents entry points for the transformations. LLVMC also
66 assigns a weight to each edge (more on that below) to choose between
67 several alternative edges.
68
69 The definition of the compilation graph (see file ``Example.td``) is
70 just a list of edges::
71
72 def CompilationGraph : CompilationGraph<[
73 Edge,
74 Edge,
75 ...
76
77 Edge,
78 Edge,
79 ...
80
81 OptionalEdge,
82 OptionalEdge,
83 ...
84
85 OptionalEdge
86 [(if_input_languages_contain "c++"),
87 (or (parameter_equals "linker", "g++"),
88 (parameter_equals "linker", "c++"))]>,
89 ...
90
91 ]>;
92
93 As you can see, the edges can be either default or optional, where
94 optional edges are differentiated by sporting a list of patterns (or
95 edge properties) which are used to calculate the edge's weight. The
96 default edges are assigned a weight of 1, and optional edges get a
97 weight of 0 + 2*N where N is the number of succesful edge property
98 matches. When passing an input file through the graph, LLVMC picks the
99 edge with the maximum weight. To avoid ambiguity, there should be only
100 one default edge between two nodes (with the exception of the root
101 node, which gets a special treatment - there you are allowed to
102 specify one default edge *per language*).
103
104 * Possible edge properties are:
105
106 - ``switch_on`` - Returns true if a given command-line option is
107 provided by the user. Example: ``(switch_on "opt")``. Note that
108 you have to define all possible command-line options separately in
109 the tool descriptions. See the next section for the discussion of
110 different kinds of command-line options.
111
112 - ``parameter_equals`` - Returns true if a command-line parameter equals
113 a given value. Example: ``(parameter_equals "W", "all")``.
114
115 - ``element_in_list`` - Returns true if a command-line parameter list
116 includes a given value. Example: ``(parameter_in_list "l", "pthread")``.
117
118 - ``if_input_languages_contain`` - Returns true if a given input
119 language belongs to the current input language set.
120
121 - ``and`` - Edge property combinator. Returns true if all of its
122 arguments return true. Used like this: (and
123 (prop1), (prop2), ... (propN)). Nesting not allowed.
124
125 - ``or`` - Edge property combinator that returns true if any one of its
126 arguments returns true. Example: (or (prop1), (prop2), ... (propN))
127
128 To get a visual representation of the compilation graph (useful for
129 debugging), run ``llvmc2 --view-graph``. You will need ``dot`` and
130 ``gsview`` installed for this to work properly.
131
132
133 Writing a tool description
134 --------------------------
135
136 As was said earlier, nodes in the compilation graph represent tools. A
137 tool definition looks like this (taken from the ``Tools.td`` file)::
41138
42139 def llvm_gcc_cpp : Tool<[
43140 (in_language "c++"),
56153 The complete list of the currently implemented tool properties follows:
57154
58155 * Possible tool properties:
59 - in_language - input language name.
60
61 - out_language - output language name.
62
63 - output_suffix - output file suffix.
64
65 - cmd_line - the actual command used to run the tool. You can use
66 ``$INFILE`` and ``$OUTFILE`` variables.
67
68 - join - this tool is a "join node" in the graph, i.e. it gets a
156
157 - ``in_language`` - input language name.
158
159 - ``out_language`` - output language name.
160
161 - ``output_suffix`` - output file suffix.
162
163 - ``cmd_line`` - the actual command used to run the tool. You can use
164 ``$INFILE`` and ``$OUTFILE`` variables, as well as output
165 redirection with ``>``.
166
167 - ``join`` - this tool is a "join node" in the graph, i.e. it gets a
69168 list of input files and joins them together. Used for linkers.
70169
71 - sink - all command-line options that are not handled by other
170 - ``sink`` - all command-line options that are not handled by other
72171 tools are passed to this tool.
73172
74173 The next tool definition is slightly more complex::
92191 currently implemented option types and properties are described below:
93192
94193 * Possible option types:
95 - switch_option - a simple boolean switch, for example ``-time``.
96
97 - parameter_option - option that takes an argument, for example ``-std=c99``;
98
99 - parameter_list_option - same as the above, but more than one
194
195 - ``switch_option`` - a simple boolean switch, for example ``-time``.
196
197 - ``parameter_option`` - option that takes an argument, for example
198 ``-std=c99``;
199
200 - ``parameter_list_option`` - same as the above, but more than one
100201 occurence of the option is allowed.
101202
102 - prefix_option - same as the parameter_option, but the option name
203 - ``prefix_option`` - same as the parameter_option, but the option name
103204 and parameter value are not separated.
104205
105 - prefix_list_option - same as the above, but more than one
206 - ``prefix_list_option`` - same as the above, but more than one
106207 occurence of the option is allowed; example: ``-lm -lpthread``.
107208
209
108210 * Possible option properties:
109 - append_cmd - append a string to the tool invocation command.
110
111 - forward - forward this option unchanged.
112
113 - stop_compilation - stop compilation after this phase.
114
115 - unpack_values - used for for splitting and forwarding
211
212 - ``append_cmd`` - append a string to the tool invocation command.
213
214 - ``forward`` - forward this option unchanged.
215
216 - ``stop_compilation`` - stop compilation after this phase.
217
218 - ``unpack_values`` - used for for splitting and forwarding
116219 comma-separated lists of options, e.g. ``-Wa,-foo=bar,-baz`` is
117220 converted to ``-foo=bar -baz`` and appended to the tool invocation
118221 command.
119222
120 - help - help string associated with this option.
121
122 - required - this option is obligatory.
223 - ``help`` - help string associated with this option.
224
225 - ``required`` - this option is obligatory.
226
123227
124228 Language map
125229 ------------
126230
127 One last bit that you probably should change is the language map,
128 which defines mappings between language names and file extensions. It
129 is used internally to choose the proper toolchain based on the names
130 of the input files. Language map definition is located in the file
131 ``Tools.td`` and looks like this::
231 One last thing that you need to modify when adding support for a new
232 language to LLVMC is the language map, which defines mappings from
233 file extensions to language names. It is used to choose the proper
234 toolchain based on the input. Language map definition is located in
235 the file ``Tools.td`` and looks like this::
132236
133237 def LanguageMap : LanguageMap<
134238 [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
137241 ]>;
138242
139243
140 Putting it all together
141 -----------------------
142
143 Since at the time of writing LLVMCC does not support on-the-fly
144 reloading of the configuration, the only way to test your changes is
145 to recompile the program. To do this, ``cd`` to the source code
146 directory and run ``make``.
147
148244 References
149245 ==========
150246