blob: 7e609a7bc341d25e01fcb09a22d3ab990c4fd04f [file] [log] [blame]
Mikhail Glushenkov270cae32008-05-30 06:25:24 +00001===================================
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +00002Customizing LLVMC: Reference Manual
3===================================
Mikhail Glushenkov23f522a2008-12-13 17:51:47 +00004..
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'.
Mikhail Glushenkovd5652032008-12-13 02:28:58 +00008
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
17Introduction
18============
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000019
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +000020LLVMC is a generic compiler driver, designed to be customizable and
21extensible. It plays the same role for LLVM as the ``gcc`` program
22does for GCC - LLVMC's job is essentially to transform a set of input
23files into a set of targets depending on configuration rules and user
24options. What makes LLVMC different is that these transformation rules
25are completely customizable - in fact, LLVMC knows nothing about the
26specifics of transformation (even the command-line options are mostly
27not hard-coded) and regards the transformation structure as an
Mikhail Glushenkov83237482008-10-15 09:29:13 +000028abstract graph. The structure of this graph is completely determined
29by plugins, which can be either statically or dynamically linked. This
30makes it possible to easily adapt LLVMC for other purposes - for
31example, as a build tool for game resources.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000032
Mikhail Glushenkovd5652032008-12-13 02:28:58 +000033Because LLVMC employs TableGen_ as its configuration language, you
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +000034need to be familiar with it to customize LLVMC.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000035
Mikhail Glushenkov4aecec12009-06-17 02:56:08 +000036.. _TableGen: http://llvm.org/docs/TableGenFundamentals.html
Mikhail Glushenkov270cae32008-05-30 06:25:24 +000037
38
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +000039Compiling with LLVMC
Mikhail Glushenkov270cae32008-05-30 06:25:24 +000040====================
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000041
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +000042LLVMC tries hard to be as compatible with ``gcc`` as possible,
43although there are some small differences. Most of the time, however,
44you shouldn't be able to notice them::
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000045
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +000046 $ # This works as expected:
Mikhail Glushenkov113ec352008-11-25 21:38:12 +000047 $ llvmc -O3 -Wall hello.cpp
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +000048 $ ./a.out
49 hello
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000050
Mikhail Glushenkov4aecec12009-06-17 02:56:08 +000051One nice feature of LLVMC is that one doesn't have to distinguish between
52different compilers for different languages (think ``g++`` vs. ``gcc``) - the
53right toolchain is chosen automatically based on input language names (which
54are, in turn, determined from file extensions). If you want to force files
55ending with ".c" to compile as C++, use the ``-x`` option, just like you would
56do it with ``gcc``::
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000057
Mikhail Glushenkovebdeca72008-11-25 21:34:29 +000058 $ # hello.c is really a C++ file
Mikhail Glushenkov113ec352008-11-25 21:38:12 +000059 $ llvmc -x c++ hello.c
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +000060 $ ./a.out
61 hello
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000062
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +000063On the other hand, when using LLVMC as a linker to combine several C++
64object files you should provide the ``--linker`` option since it's
65impossible for LLVMC to choose the right linker in that case::
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000066
Mikhail Glushenkov113ec352008-11-25 21:38:12 +000067 $ llvmc -c hello.cpp
68 $ llvmc hello.o
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +000069 [A lot of link-time errors skipped]
Mikhail Glushenkov113ec352008-11-25 21:38:12 +000070 $ llvmc --linker=c++ hello.o
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +000071 $ ./a.out
72 hello
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +000073
Mikhail Glushenkove8e4d582009-06-30 00:16:22 +000074By default, LLVMC uses ``llvm-gcc`` to compile the source code. It is also
75possible to choose the ``clang`` compiler with the ``-clang`` option.
Mikhail Glushenkov4410e322008-12-07 16:47:42 +000076
Mikhail Glushenkov83237482008-10-15 09:29:13 +000077
Mikhail Glushenkov270cae32008-05-30 06:25:24 +000078Predefined options
79==================
80
81LLVMC has some built-in options that can't be overridden in the
Mikhail Glushenkov7e6d70a2008-11-26 22:59:45 +000082configuration libraries:
Mikhail Glushenkov270cae32008-05-30 06:25:24 +000083
84* ``-o FILE`` - Output file name.
85
86* ``-x LANGUAGE`` - Specify the language of the following input files
87 until the next -x option.
88
Mikhail Glushenkov83237482008-10-15 09:29:13 +000089* ``-load PLUGIN_NAME`` - Load the specified plugin DLL. Example:
90 ``-load $LLVM_DIR/Release/lib/LLVMCSimple.so``.
91
Mikhail Glushenkov270cae32008-05-30 06:25:24 +000092* ``-v`` - Enable verbose mode, i.e. print out all executed commands.
93
Mikhail Glushenkov294f5072009-06-25 18:20:44 +000094* ``--save-temps`` - Write temporary files to the current directory and do not
95 delete them on exit. This option can also take an argument: the
96 ``--save-temps=obj`` switch will write files into the directory specified with
97 the ``-o`` option. The ``--save-temps=cwd`` and ``--save-temps`` switches are
98 both synonyms for the default behaviour.
99
Mikhail Glushenkov09826e32009-07-11 19:27:40 +0000100* ``--temp-dir DIRECTORY`` - Store temporary files in the given directory. This
101 directory is deleted on exit unless ``--save-temps`` is specified. If
102 ``--save-temps=obj`` is also specified, ``--temp-dir`` is given the
103 precedence.
Mikhail Glushenkov792f1822009-07-09 19:39:16 +0000104
Mikhail Glushenkov4ad0d572009-03-27 12:58:29 +0000105* ``--check-graph`` - Check the compilation for common errors like mismatched
106 output/input language names, multiple default edges and cycles. Because of
Mikhail Glushenkov530f3992009-06-16 00:13:52 +0000107 plugins, these checks can't be performed at compile-time. Exit with code zero
108 if no errors were found, and return the number of found errors
109 otherwise. Hidden option, useful for debugging LLVMC plugins.
Mikhail Glushenkovf8c430b2009-01-09 16:16:27 +0000110
Mikhail Glushenkov4ad0d572009-03-27 12:58:29 +0000111* ``--view-graph`` - Show a graphical representation of the compilation graph
112 and exit. Requires that you have ``dot`` and ``gv`` programs installed. Hidden
113 option, useful for debugging LLVMC plugins.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000114
Mikhail Glushenkov4ad0d572009-03-27 12:58:29 +0000115* ``--write-graph`` - Write a ``compilation-graph.dot`` file in the current
116 directory with the compilation graph description in Graphviz format (identical
Mikhail Glushenkov530f3992009-06-16 00:13:52 +0000117 to the file used by the ``--view-graph`` option). The ``-o`` option can be
118 used to set the output file name. Hidden option, useful for debugging LLVMC
119 plugins.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000120
Mikhail Glushenkov73296102008-05-30 06:29:17 +0000121* ``--help``, ``--help-hidden``, ``--version`` - These options have
122 their standard meaning.
123
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000124Compiling LLVMC plugins
125=======================
126
127It's easiest to start working on your own LLVMC plugin by copying the
128skeleton project which lives under ``$LLVMC_DIR/plugins/Simple``::
129
130 $ cd $LLVMC_DIR/plugins
131 $ cp -r Simple MyPlugin
132 $ cd MyPlugin
133 $ ls
134 Makefile PluginMain.cpp Simple.td
135
136As you can see, our basic plugin consists of only two files (not
137counting the build script). ``Simple.td`` contains TableGen
138description of the compilation graph; its format is documented in the
139following sections. ``PluginMain.cpp`` is just a helper file used to
140compile the auto-generated C++ code produced from TableGen source. It
141can also contain hook definitions (see `below`__).
142
143__ hooks_
144
145The first thing that you should do is to change the ``LLVMC_PLUGIN``
146variable in the ``Makefile`` to avoid conflicts (since this variable
147is used to name the resulting library)::
148
149 LLVMC_PLUGIN=MyPlugin
150
151It is also a good idea to rename ``Simple.td`` to something less
152generic::
153
154 $ mv Simple.td MyPlugin.td
155
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000156To build your plugin as a dynamic library, just ``cd`` to its source
157directory and run ``make``. The resulting file will be called
Mikhail Glushenkov4aecec12009-06-17 02:56:08 +0000158``plugin_llvmc_$(LLVMC_PLUGIN).$(DLL_EXTENSION)`` (in our case,
159``plugin_llvmc_MyPlugin.so``). This library can be then loaded in with the
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000160``-load`` option. Example::
161
162 $ cd $LLVMC_DIR/plugins/Simple
163 $ make
Mikhail Glushenkov4aecec12009-06-17 02:56:08 +0000164 $ llvmc -load $LLVM_DIR/Release/lib/plugin_llvmc_Simple.so
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000165
Mikhail Glushenkov530f3992009-06-16 00:13:52 +0000166Compiling standalone LLVMC-based drivers
167========================================
168
169By default, the ``llvmc`` executable consists of a driver core plus several
170statically linked plugins (``Base`` and ``Clang`` at the moment). You can
171produce a standalone LLVMC-based driver executable by linking the core with your
172own plugins. The recommended way to do this is by starting with the provided
173``Skeleton`` example (``$LLVMC_DIR/example/Skeleton``)::
174
175 $ cd $LLVMC_DIR/example/
176 $ cp -r Skeleton mydriver
177 $ cd mydriver
178 $ vim Makefile
179 [...]
180 $ make
181
182If you're compiling LLVM with different source and object directories, then you
183must perform the following additional steps before running ``make``::
184
185 # LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/
186 # LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/
187 $ cp $LLVMC_SRC_DIR/example/mydriver/Makefile \
188 $LLVMC_OBJ_DIR/example/mydriver/
189 $ cd $LLVMC_OBJ_DIR/example/mydriver
190 $ make
191
192Another way to do the same thing is by using the following command::
193
194 $ cd $LLVMC_DIR
195 $ make LLVMC_BUILTIN_PLUGINS=MyPlugin LLVMC_BASED_DRIVER_NAME=mydriver
196
Mikhail Glushenkov4aecec12009-06-17 02:56:08 +0000197This works with both srcdir == objdir and srcdir != objdir, but assumes that the
Mikhail Glushenkov530f3992009-06-16 00:13:52 +0000198plugin source directory was placed under ``$LLVMC_DIR/plugins``.
199
Mikhail Glushenkovf80f0aa2008-11-25 21:34:01 +0000200Sometimes, you will want a 'bare-bones' version of LLVMC that has no
201built-in plugins. It can be compiled with the following command::
202
203 $ cd $LLVMC_DIR
Mikhail Glushenkov530f3992009-06-16 00:13:52 +0000204 $ make LLVMC_BUILTIN_PLUGINS=""
Mikhail Glushenkovf80f0aa2008-11-25 21:34:01 +0000205
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000206
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000207Customizing LLVMC: the compilation graph
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000208========================================
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000209
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000210Each TableGen configuration file should include the common
211definitions::
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000212
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000213 include "llvm/CompilerDriver/Common.td"
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +0000214
215Internally, LLVMC stores information about possible source
216transformations in form of a graph. Nodes in this graph represent
217tools, and edges between two nodes represent a transformation path. A
218special "root" node is used to mark entry points for the
219transformations. LLVMC also assigns a weight to each edge (more on
220this later) to choose between several alternative edges.
221
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000222The definition of the compilation graph (see file
223``plugins/Base/Base.td`` for an example) is just a list of edges::
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000224
225 def CompilationGraph : CompilationGraph<[
Mikhail Glushenkov01088772008-11-17 17:29:18 +0000226 Edge<"root", "llvm_gcc_c">,
227 Edge<"root", "llvm_gcc_assembler">,
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000228 ...
229
Mikhail Glushenkov01088772008-11-17 17:29:18 +0000230 Edge<"llvm_gcc_c", "llc">,
231 Edge<"llvm_gcc_cpp", "llc">,
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000232 ...
233
Mikhail Glushenkov536637f2008-11-25 21:34:53 +0000234 OptionalEdge<"llvm_gcc_c", "opt", (case (switch_on "opt"),
235 (inc_weight))>,
236 OptionalEdge<"llvm_gcc_cpp", "opt", (case (switch_on "opt"),
237 (inc_weight))>,
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000238 ...
239
Mikhail Glushenkov01088772008-11-17 17:29:18 +0000240 OptionalEdge<"llvm_gcc_assembler", "llvm_gcc_cpp_linker",
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +0000241 (case (input_languages_contain "c++"), (inc_weight),
242 (or (parameter_equals "linker", "g++"),
243 (parameter_equals "linker", "c++")), (inc_weight))>,
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000244 ...
245
246 ]>;
247
248As you can see, the edges can be either default or optional, where
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000249optional edges are differentiated by an additional ``case`` expression
Mikhail Glushenkov01088772008-11-17 17:29:18 +0000250used to calculate the weight of this edge. Notice also that we refer
Mikhail Glushenkovf80f0aa2008-11-25 21:34:01 +0000251to tools via their names (as strings). This makes it possible to add
252edges to an existing compilation graph in plugins without having to
253know about all tool definitions used in the graph.
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000254
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +0000255The default edges are assigned a weight of 1, and optional edges get a
256weight of 0 + 2*N where N is the number of tests that evaluated to
257true in the ``case`` expression. It is also possible to provide an
258integer parameter to ``inc_weight`` and ``dec_weight`` - in this case,
259the weight is increased (or decreased) by the provided value instead
Mikhail Glushenkov7e6d70a2008-11-26 22:59:45 +0000260of the default 2. It is also possible to change the default weight of
261an optional edge by using the ``default`` clause of the ``case``
262construct.
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +0000263
264When passing an input file through the graph, LLVMC picks the edge
265with the maximum weight. To avoid ambiguity, there should be only one
266default edge between two nodes (with the exception of the root node,
267which gets a special treatment - there you are allowed to specify one
268default edge *per language*).
269
Mikhail Glushenkov7e6d70a2008-11-26 22:59:45 +0000270When multiple plugins are loaded, their compilation graphs are merged
Mikhail Glushenkov3321b0f2008-11-28 00:12:09 +0000271together. Since multiple edges that have the same end nodes are not
272allowed (i.e. the graph is not a multigraph), an edge defined in
Mikhail Glushenkov7e6d70a2008-11-26 22:59:45 +0000273several plugins will be replaced by the definition from the plugin
274that was loaded last. Plugin load order can be controlled by using the
275plugin priority feature described above.
276
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +0000277To get a visual representation of the compilation graph (useful for
Mikhail Glushenkov113ec352008-11-25 21:38:12 +0000278debugging), run ``llvmc --view-graph``. You will need ``dot`` and
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +0000279``gsview`` installed for this to work properly.
280
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000281Describing options
282==================
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +0000283
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000284Command-line options that the plugin supports are defined by using an
285``OptionList``::
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000286
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000287 def Options : OptionList<[
288 (switch_option "E", (help "Help string")),
289 (alias_option "quiet", "q")
290 ...
291 ]>;
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000292
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000293As you can see, the option list is just a list of DAGs, where each DAG
294is an option description consisting of the option name and some
295properties. A plugin can define more than one option list (they are
296all merged together in the end), which can be handy if one wants to
297separate option groups syntactically.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000298
299* Possible option types:
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000300
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000301 - ``switch_option`` - a simple boolean switch without arguments, for example
302 ``-O2`` or ``-time``. At most one occurrence is allowed.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000303
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000304 - ``parameter_option`` - option that takes one argument, for example
305 ``-std=c99``. It is also allowed to use spaces instead of the equality
306 sign: ``-std c99``. At most one occurrence is allowed.
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000307
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000308 - ``parameter_list_option`` - same as the above, but more than one option
309 occurence is allowed.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000310
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000311 - ``prefix_option`` - same as the parameter_option, but the option name and
312 argument do not have to be separated. Example: ``-ofile``. This can be also
313 specified as ``-o file``; however, ``-o=file`` will be parsed incorrectly
314 (``=file`` will be interpreted as option value). At most one occurrence is
315 allowed.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000316
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000317 - ``prefix_list_option`` - same as the above, but more than one occurence of
318 the option is allowed; example: ``-lm -lpthread``.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000319
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000320 - ``alias_option`` - a special option type for creating aliases. Unlike other
321 option types, aliases are not allowed to have any properties besides the
322 aliased option name. Usage example: ``(alias_option "preprocess", "E")``
Mikhail Glushenkov0ab8ac32008-05-30 06:28:00 +0000323
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000324
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000325* Possible option properties:
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000326
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000327 - ``help`` - help string associated with this option. Used for ``--help``
328 output.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000329
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000330 - ``required`` - this option must be specified exactly once (or, in case of
331 the list options without the ``multi_val`` property, at least
332 once). Incompatible with ``zero_or_one`` and ``one_or_more``.
333
334 - ``one_or_more`` - the option must be specified at least one time. Useful
335 only for list options in conjunction with ``multi_val``; for ordinary lists
336 it is synonymous with ``required``. Incompatible with ``required`` and
337 ``zero_or_one``.
338
339 - ``zero_or_one`` - the option can be specified zero or one times. Useful
340 only for list options in conjunction with ``multi_val``. Incompatible with
341 ``required`` and ``one_or_more``.
Mikhail Glushenkov77ddce92008-05-06 18:17:19 +0000342
Mikhail Glushenkovf9b1d792009-01-15 02:42:40 +0000343 - ``hidden`` - the description of this option will not appear in
344 the ``--help`` output (but will appear in the ``--help-hidden``
345 output).
Mikhail Glushenkov739c7202008-11-28 00:13:25 +0000346
Mikhail Glushenkovf9b1d792009-01-15 02:42:40 +0000347 - ``really_hidden`` - the option will not be mentioned in any help
Mikhail Glushenkov739c7202008-11-28 00:13:25 +0000348 output.
349
Mikhail Glushenkov19d3e822009-01-28 03:47:20 +0000350 - ``multi_val n`` - this option takes *n* arguments (can be useful in some
351 special cases). Usage example: ``(parameter_list_option "foo", (multi_val
352 3))``. Only list options can have this attribute; you can, however, use
353 the ``one_or_more`` and ``zero_or_one`` properties.
354
Mikhail Glushenkovdad78202009-07-07 16:09:29 +0000355 - ``init`` - this option has a default value, either a string (if it is a
356 parameter), or a boolean (if it is a switch; boolean constants are called
357 ``true`` and ``false``). List options can't have this attribute. Usage
358 examples: ``(switch_option "foo", (init true))``; ``(prefix_option "bar",
359 (init "baz"))``.
360
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000361 - ``extern`` - this option is defined in some other plugin, see below.
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000362
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000363External options
364----------------
Mikhail Glushenkov0ab8ac32008-05-30 06:28:00 +0000365
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000366Sometimes, when linking several plugins together, one plugin needs to
367access options defined in some other plugin. Because of the way
Mikhail Glushenkovf9b1d792009-01-15 02:42:40 +0000368options are implemented, such options must be marked as
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000369``extern``. This is what the ``extern`` option property is
370for. Example::
Mikhail Glushenkov0ab8ac32008-05-30 06:28:00 +0000371
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000372 ...
373 (switch_option "E", (extern))
374 ...
Mikhail Glushenkov0ab8ac32008-05-30 06:28:00 +0000375
Mikhail Glushenkovbb41b2d2009-07-07 16:43:49 +0000376If an external option has additional attributes besides 'extern', they are
377ignored. See also the section on plugin `priorities`__.
Mikhail Glushenkov0ab8ac32008-05-30 06:28:00 +0000378
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000379__ priorities_
Mikhail Glushenkov0ab8ac32008-05-30 06:28:00 +0000380
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000381.. _case:
Mikhail Glushenkov83237482008-10-15 09:29:13 +0000382
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000383Conditional evaluation
384======================
Mikhail Glushenkov0ab8ac32008-05-30 06:28:00 +0000385
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000386The 'case' construct is the main means by which programmability is
387achieved in LLVMC. It can be used to calculate edge weights, program
388actions and modify the shell commands to be executed. The 'case'
389expression is designed after the similarly-named construct in
390functional languages and takes the form ``(case (test_1), statement_1,
391(test_2), statement_2, ... (test_N), statement_N)``. The statements
392are evaluated only if the corresponding tests evaluate to true.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000393
394Examples::
395
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000396 // Edge weight calculation
397
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000398 // Increases edge weight by 5 if "-A" is provided on the
399 // command-line, and by 5 more if "-B" is also provided.
400 (case
401 (switch_on "A"), (inc_weight 5),
402 (switch_on "B"), (inc_weight 5))
403
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000404
405 // Tool command line specification
406
407 // Evaluates to "cmdline1" if the option "-A" is provided on the
408 // command line; to "cmdline2" if "-B" is provided;
409 // otherwise to "cmdline3".
410
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000411 (case
412 (switch_on "A"), "cmdline1",
413 (switch_on "B"), "cmdline2",
414 (default), "cmdline3")
415
416Note the slight difference in 'case' expression handling in contexts
417of edge weights and command line specification - in the second example
418the value of the ``"B"`` switch is never checked when switch ``"A"`` is
419enabled, and the whole expression always evaluates to ``"cmdline1"`` in
420that case.
421
422Case expressions can also be nested, i.e. the following is legal::
423
424 (case (switch_on "E"), (case (switch_on "o"), ..., (default), ...)
425 (default), ...)
426
427You should, however, try to avoid doing that because it hurts
428readability. It is usually better to split tool descriptions and/or
429use TableGen inheritance instead.
430
431* Possible tests are:
432
Mikhail Glushenkov536637f2008-11-25 21:34:53 +0000433 - ``switch_on`` - Returns true if a given command-line switch is
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000434 provided by the user. Example: ``(switch_on "opt")``.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000435
436 - ``parameter_equals`` - Returns true if a command-line parameter equals
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000437 a given value.
438 Example: ``(parameter_equals "W", "all")``.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000439
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000440 - ``element_in_list`` - Returns true if a command-line parameter
441 list contains a given value.
442 Example: ``(parameter_in_list "l", "pthread")``.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000443
444 - ``input_languages_contain`` - Returns true if a given language
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000445 belongs to the current input language set.
446 Example: ``(input_languages_contain "c++")``.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000447
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000448 - ``in_language`` - Evaluates to true if the input file language
449 equals to the argument. At the moment works only with ``cmd_line``
450 and ``actions`` (on non-join nodes).
451 Example: ``(in_language "c++")``.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000452
453 - ``not_empty`` - Returns true if a given option (which should be
454 either a parameter or a parameter list) is set by the
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000455 user.
456 Example: ``(not_empty "o")``.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000457
Mikhail Glushenkov5c2b6b22008-12-17 02:47:01 +0000458 - ``empty`` - The opposite of ``not_empty``. Equivalent to ``(not (not_empty
459 X))``. Provided for convenience.
460
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000461 - ``default`` - Always evaluates to true. Should always be the last
462 test in the ``case`` expression.
463
Mikhail Glushenkovd66e8de2009-09-28 01:16:07 +0000464 - ``and`` - A standard binary logical combinator that returns true iff all of
465 its arguments return true. Used like this: ``(and (test1), (test2),
466 ... (testN))``. Nesting of ``and`` and ``or`` is allowed, but not
467 encouraged.
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000468
Mikhail Glushenkovd66e8de2009-09-28 01:16:07 +0000469 - ``or`` - A binary logical combinator that returns true iff any of its
470 arguments returns true. Example: ``(or (test1), (test2), ... (testN))``.
471
472 - ``not`` - Standard unary logical combinator that negates its
473 argument. Example: ``(not (or (test1), (test2), ... (testN)))``.
474
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000475
Mikhail Glushenkovcd0858e2008-05-30 06:14:42 +0000476
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000477Writing a tool description
478==========================
479
480As was said earlier, nodes in the compilation graph represent tools,
481which are described separately. A tool definition looks like this
482(taken from the ``include/llvm/CompilerDriver/Tools.td`` file)::
483
484 def llvm_gcc_cpp : Tool<[
485 (in_language "c++"),
486 (out_language "llvm-assembler"),
487 (output_suffix "bc"),
488 (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
489 (sink)
490 ]>;
491
492This defines a new tool called ``llvm_gcc_cpp``, which is an alias for
493``llvm-g++``. As you can see, a tool definition is just a list of
494properties; most of them should be self-explanatory. The ``sink``
495property means that this tool should be passed all command-line
496options that aren't mentioned in the option list.
497
498The complete list of all currently implemented tool properties follows.
499
500* Possible tool properties:
501
502 - ``in_language`` - input language name. Can be either a string or a
503 list, in case the tool supports multiple input languages.
504
505 - ``out_language`` - output language name. Tools are not allowed to
506 have multiple output languages.
507
508 - ``output_suffix`` - output file suffix. Can also be changed
509 dynamically, see documentation on actions.
510
511 - ``cmd_line`` - the actual command used to run the tool. You can
512 use ``$INFILE`` and ``$OUTFILE`` variables, output redirection
513 with ``>``, hook invocations (``$CALL``), environment variables
514 (via ``$ENV``) and the ``case`` construct.
515
516 - ``join`` - this tool is a "join node" in the graph, i.e. it gets a
517 list of input files and joins them together. Used for linkers.
518
519 - ``sink`` - all command-line options that are not handled by other
520 tools are passed to this tool.
521
522 - ``actions`` - A single big ``case`` expression that specifies how
523 this tool reacts on command-line options (described in more detail
524 below).
525
526Actions
527-------
528
529A tool often needs to react to command-line options, and this is
530precisely what the ``actions`` property is for. The next example
531illustrates this feature::
532
533 def llvm_gcc_linker : Tool<[
534 (in_language "object-code"),
535 (out_language "executable"),
536 (output_suffix "out"),
537 (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
538 (join),
539 (actions (case (not_empty "L"), (forward "L"),
540 (not_empty "l"), (forward "l"),
541 (not_empty "dummy"),
542 [(append_cmd "-dummy1"), (append_cmd "-dummy2")])
543 ]>;
544
545The ``actions`` tool property is implemented on top of the omnipresent
546``case`` expression. It associates one or more different *actions*
547with given conditions - in the example, the actions are ``forward``,
548which forwards a given option unchanged, and ``append_cmd``, which
549appends a given string to the tool execution command. Multiple actions
550can be associated with a single condition by using a list of actions
551(used in the example to append some dummy options). The same ``case``
552construct can also be used in the ``cmd_line`` property to modify the
553tool command line.
554
555The "join" property used in the example means that this tool behaves
556like a linker.
557
558The list of all possible actions follows.
559
560* Possible actions:
561
562 - ``append_cmd`` - append a string to the tool invocation
563 command.
Mikhail Glushenkov5c2b6b22008-12-17 02:47:01 +0000564 Example: ``(case (switch_on "pthread"), (append_cmd
565 "-lpthread"))``
566
567 - ``error` - exit with error.
568 Example: ``(error "Mixing -c and -S is not allowed!")``.
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000569
570 - ``forward`` - forward an option unchanged.
571 Example: ``(forward "Wall")``.
572
573 - ``forward_as`` - Change the name of an option, but forward the
574 argument unchanged.
Mikhail Glushenkove89331b2009-05-06 01:41:19 +0000575 Example: ``(forward_as "O0", "--disable-optimization")``.
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000576
577 - ``output_suffix`` - modify the output suffix of this
578 tool.
579 Example: ``(output_suffix "i")``.
580
581 - ``stop_compilation`` - stop compilation after this tool processes
582 its input. Used without arguments.
583
584 - ``unpack_values`` - used for for splitting and forwarding
585 comma-separated lists of options, e.g. ``-Wa,-foo=bar,-baz`` is
586 converted to ``-foo=bar -baz`` and appended to the tool invocation
587 command.
588 Example: ``(unpack_values "Wa,")``.
589
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000590Language map
Mikhail Glushenkov270cae32008-05-30 06:25:24 +0000591============
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000592
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000593If you are adding support for a new language to LLVMC, you'll need to
594modify the language map, which defines mappings from file extensions
595to language names. It is used to choose the proper toolchain(s) for a
596given input file set. Language map definition looks like this::
Anton Korobeynikovac67b7e2008-03-23 08:57:20 +0000597
598 def LanguageMap : LanguageMap<
599 [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
600 LangToSuffixes<"c", ["c"]>,
601 ...
602 ]>;
603
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000604For example, without those definitions the following command wouldn't work::
605
606 $ llvmc hello.cpp
607 llvmc: Unknown suffix: cpp
608
609The language map entries should be added only for tools that are
610linked with the root node. Since tools are not allowed to have
611multiple output languages, for nodes "inside" the graph the input and
612output languages should match. This is enforced at compile-time.
613
614
615More advanced topics
616====================
617
618.. _hooks:
619
620Hooks and environment variables
621-------------------------------
622
623Normally, LLVMC executes programs from the system ``PATH``. Sometimes,
Mikhail Glushenkova298bb72009-01-21 13:04:00 +0000624this is not sufficient: for example, we may want to specify tool paths
625or names in the configuration file. This can be easily achieved via
626the hooks mechanism. To write your own hooks, just add their
627definitions to the ``PluginMain.cpp`` or drop a ``.cpp`` file into the
628your plugin directory. Hooks should live in the ``hooks`` namespace
Mikhail Glushenkovb6b51412009-01-21 13:04:33 +0000629and have the signature ``std::string hooks::MyHookName ([const char*
Mikhail Glushenkova298bb72009-01-21 13:04:00 +0000630Arg0 [ const char* Arg2 [, ...]]])``. They can be used from the
631``cmd_line`` tool property::
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000632
633 (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
634
Mikhail Glushenkova298bb72009-01-21 13:04:00 +0000635To pass arguments to hooks, use the following syntax::
636
637 (cmd_line "$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2")
638
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000639It is also possible to use environment variables in the same manner::
640
641 (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
642
643To change the command line string based on user-provided options use
644the ``case`` expression (documented `above`__)::
645
646 (cmd_line
647 (case
648 (switch_on "E"),
649 "llvm-g++ -E -x c $INFILE -o $OUTFILE",
650 (default),
651 "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm"))
652
653__ case_
654
655.. _priorities:
656
657How plugins are loaded
658----------------------
659
660It is possible for LLVMC plugins to depend on each other. For example,
661one can create edges between nodes defined in some other plugin. To
662make this work, however, that plugin should be loaded first. To
663achieve this, the concept of plugin priority was introduced. By
664default, every plugin has priority zero; to specify the priority
665explicitly, put the following line in your plugin's TableGen file::
666
667 def Priority : PluginPriority<$PRIORITY_VALUE>;
668 # Where PRIORITY_VALUE is some integer > 0
669
670Plugins are loaded in order of their (increasing) priority, starting
671with 0. Therefore, the plugin with the highest priority value will be
672loaded last.
673
Mikhail Glushenkov9ecd30c2008-09-22 20:48:48 +0000674Debugging
Mikhail Glushenkov4410e322008-12-07 16:47:42 +0000675---------
Mikhail Glushenkov9ecd30c2008-09-22 20:48:48 +0000676
677When writing LLVMC plugins, it can be useful to get a visual view of
678the resulting compilation graph. This can be achieved via the command
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000679line option ``--view-graph``. This command assumes that Graphviz_ and
Mikhail Glushenkov4ad0d572009-03-27 12:58:29 +0000680Ghostview_ are installed. There is also a ``--write-graph`` option that
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000681creates a Graphviz source file (``compilation-graph.dot``) in the
Mikhail Glushenkov9ecd30c2008-09-22 20:48:48 +0000682current directory.
683
Mikhail Glushenkovf9b1d792009-01-15 02:42:40 +0000684Another useful ``llvmc`` option is ``--check-graph``. It checks the
685compilation graph for common errors like mismatched output/input
686language names, multiple default edges and cycles. These checks can't
687be performed at compile-time because the plugins can load code
688dynamically. When invoked with ``--check-graph``, ``llvmc`` doesn't
689perform any compilation tasks and returns the number of encountered
690errors as its status code.
Mikhail Glushenkovf8c430b2009-01-09 16:16:27 +0000691
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000692.. _Graphviz: http://www.graphviz.org/
693.. _Ghostview: http://pages.cs.wisc.edu/~ghost/
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000694
Mikhail Glushenkov875ace52009-06-30 00:16:00 +0000695Conditioning on the executable name
696-----------------------------------
697
698For now, the executable name (the value passed to the driver in ``argv[0]``) is
699accessible only in the C++ code (i.e. hooks). Use the following code::
700
701 namespace llvmc {
702 extern const char* ProgramName;
703 }
704
705 std::string MyHook() {
706 //...
707 if (strcmp(ProgramName, "mydriver") == 0) {
708 //...
709
710 }
711
712In general, you're encouraged not to make the behaviour dependent on the
713executable file name, and use command-line switches instead. See for example how
714the ``Base`` plugin behaves when it needs to choose the correct linker options
715(think ``g++`` vs. ``gcc``).
716
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000717.. raw:: html
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000718
719 <hr />
720 <address>
721 <a href="http://jigsaw.w3.org/css-validator/check/referer">
722 <img src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
723 alt="Valid CSS" /></a>
724 <a href="http://validator.w3.org/check?uri=referer">
725 <img src="http://www.w3.org/Icons/valid-xhtml10-blue"
726 alt="Valid XHTML 1.0 Transitional"/></a>
727
728 <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
729 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
730
731 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
732 </address>