llvm.org GIT mirror llvm / 834b93b
Remove all references to plugins from the LLVMC docs. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@130090 91177308-0d34-0410-b5e6-96231b3b80d8 Mikhail Glushenkov 9 years ago
2 changed file(s) with 235 addition(s) and 332 deletion(s). Raw diff Collapse all Expand all
1717 ============
1818
1919 LLVMC is a generic compiler driver, designed to be customizable and
20 extensible. It plays the same role for LLVM as the ``gcc`` program
21 does for GCC - LLVMC's job is essentially to transform a set of input
22 files into a set of targets depending on configuration rules and user
23 options. What makes LLVMC different is that these transformation rules
24 are completely customizable - in fact, LLVMC knows nothing about the
25 specifics of transformation (even the command-line options are mostly
26 not hard-coded) and regards the transformation structure as an
27 abstract graph. The structure of this graph is completely determined
28 by plugins, which can be either statically or dynamically linked. This
29 makes it possible to easily adapt LLVMC for other purposes - for
30 example, as a build tool for game resources.
20 extensible. It plays the same role for LLVM as the ``gcc`` program does for
21 GCC - LLVMC's job is essentially to transform a set of input files into a set of
22 targets depending on configuration rules and user options. What makes LLVMC
23 different is that these transformation rules are completely customizable - in
24 fact, LLVMC knows nothing about the specifics of transformation (even the
25 command-line options are mostly not hard-coded) and regards the transformation
26 structure as an abstract graph. The structure of this graph is described in
27 high-level TableGen code, from which an efficient C++ representation is
28 automatically derived. This makes it possible to adapt LLVMC for other
29 purposes - for example, as a build tool for game resources.
3130
3231 Because LLVMC employs TableGen_ as its configuration language, you
3332 need to be familiar with it to customize LLVMC.
3534 .. _TableGen: http://llvm.org/docs/TableGenFundamentals.html
3635
3736
38 Compiling with LLVMC
39 ====================
37 Compiling with ``llvmc``
38 ========================
4039
4140 LLVMC tries hard to be as compatible with ``gcc`` as possible,
4241 although there are some small differences. Most of the time, however,
7776 Predefined options
7877 ==================
7978
80 LLVMC has some built-in options that can't be overridden in the
81 configuration libraries:
79 LLVMC has some built-in options that can't be overridden in the TableGen code:
8280
8381 * ``-o FILE`` - Output file name.
8482
8583 * ``-x LANGUAGE`` - Specify the language of the following input files
8684 until the next -x option.
87
88 * ``-load PLUGIN_NAME`` - Load the specified plugin DLL. Example:
89 ``-load $LLVM_DIR/Release/lib/LLVMCSimple.so``.
9085
9186 * ``-v`` - Enable verbose mode, i.e. print out all executed commands.
9287
10297 precedence.
10398
10499 * ``--check-graph`` - Check the compilation for common errors like mismatched
105 output/input language names, multiple default edges and cycles. Because of
106 plugins, these checks can't be performed at compile-time. Exit with code zero
107 if no errors were found, and return the number of found errors
108 otherwise. Hidden option, useful for debugging LLVMC plugins.
100 output/input language names, multiple default edges and cycles. Exit with code
101 zero if no errors were found, and return the number of found errors
102 otherwise. Hidden option, useful for debugging.
109103
110104 * ``--view-graph`` - Show a graphical representation of the compilation graph
111105 and exit. Requires that you have ``dot`` and ``gv`` programs installed. Hidden
112 option, useful for debugging LLVMC plugins.
106 option, useful for debugging.
113107
114108 * ``--write-graph`` - Write a ``compilation-graph.dot`` file in the current
115109 directory with the compilation graph description in Graphviz format (identical
116110 to the file used by the ``--view-graph`` option). The ``-o`` option can be
117 used to set the output file name. Hidden option, useful for debugging LLVMC
118 plugins.
111 used to set the output file name. Hidden option, useful for debugging.
119112
120113 * ``--help``, ``--help-hidden``, ``--version`` - These options have
121114 their standard meaning.
122115
123 Compiling LLVMC plugins
124 =======================
125
126 It's easiest to start working on your own LLVMC plugin by copying the
127 skeleton project which lives under ``$LLVMC_DIR/plugins/Simple``::
128
129 $ cd $LLVMC_DIR/plugins
130 $ cp -r Simple MyPlugin
131 $ cd MyPlugin
116 Compiling LLVMC-based drivers
117 =============================
118
119 It's easiest to start working on your own LLVMC driver by copying the skeleton
120 project which lives under ``$LLVMC_DIR/examples/Skeleton``::
121
122 $ cd $LLVMC_DIR/examples
123 $ cp -r Skeleton MyDriver
124 $ cd MyDriver
132125 $ ls
133 Makefile PluginMain.cpp Simple.td
134
135 As you can see, our basic plugin consists of only two files (not
136 counting the build script). ``Simple.td`` contains TableGen
137 description of the compilation graph; its format is documented in the
138 following sections. ``PluginMain.cpp`` is just a helper file used to
139 compile the auto-generated C++ code produced from TableGen source. It
140 can also contain hook definitions (see `below`__).
126 AutoGenerated.td Hooks.cpp Main.cpp Makefile
127
128 As you can see, our basic driver consists of only three files (not counting the
129 build script). ``AutoGenerated.td`` contains TableGen description of the
130 compilation graph; its format is documented in the following
131 sections. ``Hooks.cpp`` is an empty file that should be used for hook
132 definitions (see `below`__). ``Main.cpp`` is just a helper used to compile the
133 auto-generated C++ code produced from TableGen source.
141134
142135 __ hooks_
143136
144 The first thing that you should do is to change the ``LLVMC_PLUGIN``
145 variable in the ``Makefile`` to avoid conflicts (since this variable
146 is used to name the resulting library)::
147
148 LLVMC_PLUGIN=MyPlugin
149
150 It is also a good idea to rename ``Simple.td`` to something less
151 generic::
152
153 $ mv Simple.td MyPlugin.td
154
155 To build your plugin as a dynamic library, just ``cd`` to its source
156 directory and run ``make``. The resulting file will be called
157 ``plugin_llvmc_$(LLVMC_PLUGIN).$(DLL_EXTENSION)`` (in our case,
158 ``plugin_llvmc_MyPlugin.so``). This library can be then loaded in with the
159 ``-load`` option. Example::
160
161 $ cd $LLVMC_DIR/plugins/Simple
162 $ make
163 $ llvmc -load $LLVM_DIR/Release/lib/plugin_llvmc_Simple.so
164
165 Compiling standalone LLVMC-based drivers
166 ========================================
167
168 By default, the ``llvmc`` executable consists of a driver core plus several
169 statically linked plugins (``Base`` and ``Clang`` at the moment). You can
170 produce a standalone LLVMC-based driver executable by linking the core with your
171 own plugins. The recommended way to do this is by starting with the provided
172 ``Skeleton`` example (``$LLVMC_DIR/example/Skeleton``)::
173
174 $ cd $LLVMC_DIR/example/
175 $ cp -r Skeleton mydriver
176 $ cd mydriver
177 $ vim Makefile
178 [...]
179 $ make
137 The first thing that you should do is to change the ``LLVMC_BASED_DRIVER``
138 variable in the ``Makefile``::
139
140 LLVMC_BASED_DRIVER=MyDriver
141
142 It can also be a good idea to put your TableGen code into a file with a less
143 generic name::
144
145 $ touch MyDriver.td
146 $ vim AutoGenerated.td
147 [...]
148 include "MyDriver.td"
149
150 If you have more than one TableGen source file, they all should be included from
151 ``AutoGenerated.td``, since this file is used by the build system to generate
152 C++ code.
153
154 To build your driver, just ``cd`` to its source directory and run ``make``. The
155 resulting executable will be put into ``$LLVM_OBJ_DIR/$(BuildMode)/bin``.
180156
181157 If you're compiling LLVM with different source and object directories, then you
182158 must perform the following additional steps before running ``make``::
183159
184160 # LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/
185161 # LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/
186 $ cp $LLVMC_SRC_DIR/example/mydriver/Makefile \
187 $LLVMC_OBJ_DIR/example/mydriver/
188 $ cd $LLVMC_OBJ_DIR/example/mydriver
162 $ mkdir $LLVMC_OBJ_DIR/examples/MyDriver/
163 $ cp $LLVMC_SRC_DIR/examples/MyDriver/Makefile \
164 $LLVMC_OBJ_DIR/examples/MyDriver/
165 $ cd $LLVMC_OBJ_DIR/examples/MyDriver
189166 $ make
190
191 Another way to do the same thing is by using the following command::
192
193 $ cd $LLVMC_DIR
194 $ make LLVMC_BUILTIN_PLUGINS=MyPlugin LLVMC_BASED_DRIVER_NAME=mydriver
195
196 This works with both srcdir == objdir and srcdir != objdir, but assumes that the
197 plugin source directory was placed under ``$LLVMC_DIR/plugins``.
198
199 Sometimes, you will want a 'bare-bones' version of LLVMC that has no
200 built-in plugins. It can be compiled with the following command::
201
202 $ cd $LLVMC_DIR
203 $ make LLVMC_BUILTIN_PLUGINS=""
204167
205168
206169 Customizing LLVMC: the compilation graph
207170 ========================================
208171
209 Each TableGen configuration file should include the common
210 definitions::
172 Each TableGen configuration file should include the common definitions::
211173
212174 include "llvm/CompilerDriver/Common.td"
213175
214 Internally, LLVMC stores information about possible source
215 transformations in form of a graph. Nodes in this graph represent
216 tools, and edges between two nodes represent a transformation path. A
217 special "root" node is used to mark entry points for the
218 transformations. LLVMC also assigns a weight to each edge (more on
219 this later) to choose between several alternative edges.
220
221 The definition of the compilation graph (see file
222 ``plugins/Base/Base.td`` for an example) is just a list of edges::
176 Internally, LLVMC stores information about possible source transformations in
177 form of a graph. Nodes in this graph represent tools, and edges between two
178 nodes represent a transformation path. A special "root" node is used to mark
179 entry points for the transformations. LLVMC also assigns a weight to each edge
180 (more on this later) to choose between several alternative edges.
181
182 The definition of the compilation graph (see file ``llvmc/src/Base.td`` for an
183 example) is just a list of edges::
223184
224185 def CompilationGraph : CompilationGraph<[
225186 Edge<"root", "llvm_gcc_c">,
244205
245206 ]>;
246207
247 As you can see, the edges can be either default or optional, where
248 optional edges are differentiated by an additional ``case`` expression
249 used to calculate the weight of this edge. Notice also that we refer
250 to tools via their names (as strings). This makes it possible to add
251 edges to an existing compilation graph in plugins without having to
252 know about all tool definitions used in the graph.
253
254 The default edges are assigned a weight of 1, and optional edges get a
255 weight of 0 + 2*N where N is the number of tests that evaluated to
256 true in the ``case`` expression. It is also possible to provide an
257 integer parameter to ``inc_weight`` and ``dec_weight`` - in this case,
258 the weight is increased (or decreased) by the provided value instead
259 of the default 2. It is also possible to change the default weight of
260 an optional edge by using the ``default`` clause of the ``case``
208 As you can see, the edges can be either default or optional, where optional
209 edges are differentiated by an additional ``case`` expression used to calculate
210 the weight of this edge. Notice also that we refer to tools via their names (as
211 strings). This makes it possible to add edges to an existing compilation graph
212 without having to know about all tool definitions used in the graph.
213
214 The default edges are assigned a weight of 1, and optional edges get a weight of
215 0 + 2*N where N is the number of tests that evaluated to true in the ``case``
216 expression. It is also possible to provide an integer parameter to
217 ``inc_weight`` and ``dec_weight`` - in this case, the weight is increased (or
218 decreased) by the provided value instead of the default 2. Default weight of an
219 optional edge can be changed by using the ``default`` clause of the ``case``
261220 construct.
262221
263 When passing an input file through the graph, LLVMC picks the edge
264 with the maximum weight. To avoid ambiguity, there should be only one
265 default edge between two nodes (with the exception of the root node,
266 which gets a special treatment - there you are allowed to specify one
267 default edge *per language*).
268
269 When multiple plugins are loaded, their compilation graphs are merged
270 together. Since multiple edges that have the same end nodes are not
271 allowed (i.e. the graph is not a multigraph), an edge defined in
272 several plugins will be replaced by the definition from the plugin
273 that was loaded last. Plugin load order can be controlled by using the
274 plugin priority feature described above.
275
276 To get a visual representation of the compilation graph (useful for
277 debugging), run ``llvmc --view-graph``. You will need ``dot`` and
278 ``gsview`` installed for this to work properly.
222 When passing an input file through the graph, LLVMC picks the edge with the
223 maximum weight. To avoid ambiguity, there should be only one default edge
224 between two nodes (with the exception of the root node, which gets a special
225 treatment - there you are allowed to specify one default edge *per language*).
226
227 When multiple compilation graphs are defined, they are merged together. Multiple
228 edges with the same end nodes are not allowed (i.e. the graph is not a
229 multigraph), and will lead to a compile-time error.
230
231 To get a visual representation of the compilation graph (useful for debugging),
232 run ``llvmc --view-graph``. You will need ``dot`` and ``gsview`` installed for
233 this to work properly.
279234
280235 Describing options
281236 ==================
282237
283 Command-line options that the plugin supports are defined by using an
238 Command-line options supported by the driver are defined by using an
284239 ``OptionList``::
285240
286241 def Options : OptionList<[
289244 ...
290245 ]>;
291246
292 As you can see, the option list is just a list of DAGs, where each DAG
293 is an option description consisting of the option name and some
294 properties. A plugin can define more than one option list (they are
295 all merged together in the end), which can be handy if one wants to
296 separate option groups syntactically.
247 As you can see, the option list is just a list of DAGs, where each DAG is an
248 option description consisting of the option name and some properties. More than
249 one option list can be defined (they are all merged together in the end), which
250 can be handy if one wants to separate option groups syntactically.
297251
298252 * Possible option types:
299253
379333 Usage examples: ``(switch_option "foo", (init true))``; ``(prefix_option
380334 "bar", (init "baz"))``.
381335
382 - ``extern`` - this option is defined in some other plugin, see `below`__.
383
384 __ extern_
385
386 .. _extern:
387
388 External options
389 ----------------
390
391 Sometimes, when linking several plugins together, one plugin needs to
392 access options defined in some other plugin. Because of the way
393 options are implemented, such options must be marked as
394 ``extern``. This is what the ``extern`` option property is
395 for. Example::
396
397 ...
398 (switch_option "E", (extern))
399 ...
400
401 If an external option has additional attributes besides 'extern', they are
402 ignored. See also the section on plugin `priorities`__.
403
404 __ priorities_
405
406336 .. _case:
407337
408338 Conditional evaluation
409339 ======================
410340
411 The 'case' construct is the main means by which programmability is
412 achieved in LLVMC. It can be used to calculate edge weights, program
413 actions and modify the shell commands to be executed. The 'case'
414 expression is designed after the similarly-named construct in
415 functional languages and takes the form ``(case (test_1), statement_1,
416 (test_2), statement_2, ... (test_N), statement_N)``. The statements
417 are evaluated only if the corresponding tests evaluate to true.
341 The 'case' construct is the main means by which programmability is achieved in
342 LLVMC. It can be used to calculate edge weights, program actions and modify the
343 shell commands to be executed. The 'case' expression is designed after the
344 similarly-named construct in functional languages and takes the form ``(case
345 (test_1), statement_1, (test_2), statement_2, ... (test_N), statement_N)``. The
346 statements are evaluated only if the corresponding tests evaluate to true.
418347
419348 Examples::
420349
438367 (switch_on "B"), "cmdline2",
439368 (default), "cmdline3")
440369
441 Note the slight difference in 'case' expression handling in contexts
442 of edge weights and command line specification - in the second example
443 the value of the ``"B"`` switch is never checked when switch ``"A"`` is
444 enabled, and the whole expression always evaluates to ``"cmdline1"`` in
445 that case.
370 Note the slight difference in 'case' expression handling in contexts of edge
371 weights and command line specification - in the second example the value of the
372 ``"B"`` switch is never checked when switch ``"A"`` is enabled, and the whole
373 expression always evaluates to ``"cmdline1"`` in that case.
446374
447375 Case expressions can also be nested, i.e. the following is legal::
448376
449377 (case (switch_on "E"), (case (switch_on "o"), ..., (default), ...)
450378 (default), ...)
451379
452 You should, however, try to avoid doing that because it hurts
453 readability. It is usually better to split tool descriptions and/or
454 use TableGen inheritance instead.
380 You should, however, try to avoid doing that because it hurts readability. It is
381 usually better to split tool descriptions and/or use TableGen inheritance
382 instead.
455383
456384 * Possible tests are:
457385
525453 Example: ``(not (or (test1), (test2), ... (testN)))``.
526454
527455
528
529456 Writing a tool description
530457 ==========================
531458
532 As was said earlier, nodes in the compilation graph represent tools,
533 which are described separately. A tool definition looks like this
534 (taken from the ``include/llvm/CompilerDriver/Tools.td`` file)::
459 As was said earlier, nodes in the compilation graph represent tools, which are
460 described separately. A tool definition looks like this (taken from the
461 ``llvmc/src/Base.td`` file)::
535462
536463 def llvm_gcc_cpp : Tool<[
537464 (in_language "c++"),
538465 (out_language "llvm-assembler"),
539466 (output_suffix "bc"),
540 (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
467 (command "llvm-g++ -c -emit-llvm"),
541468 (sink)
542469 ]>;
543470
544471 This defines a new tool called ``llvm_gcc_cpp``, which is an alias for
545 ``llvm-g++``. As you can see, a tool definition is just a list of
546 properties; most of them should be self-explanatory. The ``sink``
547 property means that this tool should be passed all command-line
548 options that aren't mentioned in the option list.
472 ``llvm-g++``. As you can see, a tool definition is just a list of properties;
473 most of them should be self-explanatory. The ``sink`` property means that this
474 tool should be passed all command-line options that aren't mentioned in the
475 option list.
549476
550477 The complete list of all currently implemented tool properties follows.
551478
552479 * Possible tool properties:
553480
554481 - ``in_language`` - input language name. Can be given multiple arguments, in
555 case the tool supports multiple input languages.
482 case the tool supports multiple input languages. Used for typechecking and
483 mapping file extensions to tools.
556484
557485 - ``out_language`` - output language name. Multiple output languages are
558 allowed.
559
560 - ``output_suffix`` - output file suffix. Can also be changed
561 dynamically, see documentation on actions.
562
563 - ``cmd_line`` - the actual command used to run the tool. You can
564 use ``$INFILE`` and ``$OUTFILE`` variables, output redirection
565 with ``>``, hook invocations (``$CALL``), environment variables
486 allowed. Used for typechecking the compilation graph.
487
488 - ``output_suffix`` - output file suffix. Can also be changed dynamically, see
489 documentation on `actions`__.
490
491 __ actions_
492
493 - ``command`` - the actual command used to run the tool. You can use output
494 redirection with ``>``, hook invocations (``$CALL``), environment variables
566495 (via ``$ENV``) and the ``case`` construct.
567496
568 - ``join`` - this tool is a "join node" in the graph, i.e. it gets a
569 list of input files and joins them together. Used for linkers.
570
571 - ``sink`` - all command-line options that are not handled by other
572 tools are passed to this tool.
573
574 - ``actions`` - A single big ``case`` expression that specifies how
575 this tool reacts on command-line options (described in more detail
576 `below`__).
497 - ``join`` - this tool is a "join node" in the graph, i.e. it gets a list of
498 input files and joins them together. Used for linkers.
499
500 - ``sink`` - all command-line options that are not handled by other tools are
501 passed to this tool.
502
503 - ``actions`` - A single big ``case`` expression that specifies how this tool
504 reacts on command-line options (described in more detail `below`__).
577505
578506 __ actions_
507
508 - ``out_file_option``, ``in_file_option`` - Options appended to the
509 ``command`` string to designate output and input files. Default values are
510 ``"-o"`` and ``""``, respectively.
579511
580512 .. _actions:
581513
582514 Actions
583515 -------
584516
585 A tool often needs to react to command-line options, and this is
586 precisely what the ``actions`` property is for. The next example
587 illustrates this feature::
517 A tool often needs to react to command-line options, and this is precisely what
518 the ``actions`` property is for. The next example illustrates this feature::
588519
589520 def llvm_gcc_linker : Tool<[
590521 (in_language "object-code"),
591522 (out_language "executable"),
592523 (output_suffix "out"),
593 (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
524 (command "llvm-gcc"),
594525 (join),
595526 (actions (case (not_empty "L"), (forward "L"),
596527 (not_empty "l"), (forward "l"),
598529 [(append_cmd "-dummy1"), (append_cmd "-dummy2")])
599530 ]>;
600531
601 The ``actions`` tool property is implemented on top of the omnipresent
602 ``case`` expression. It associates one or more different *actions*
603 with given conditions - in the example, the actions are ``forward``,
604 which forwards a given option unchanged, and ``append_cmd``, which
605 appends a given string to the tool execution command. Multiple actions
606 can be associated with a single condition by using a list of actions
607 (used in the example to append some dummy options). The same ``case``
608 construct can also be used in the ``cmd_line`` property to modify the
609 tool command line.
610
611 The "join" property used in the example means that this tool behaves
612 like a linker.
532 The ``actions`` tool property is implemented on top of the omnipresent ``case``
533 expression. It associates one or more different *actions* with given
534 conditions - in the example, the actions are ``forward``, which forwards a given
535 option unchanged, and ``append_cmd``, which appends a given string to the tool
536 execution command. Multiple actions can be associated with a single condition by
537 using a list of actions (used in the example to append some dummy options). The
538 same ``case`` construct can also be used in the ``cmd_line`` property to modify
539 the tool command line.
540
541 The "join" property used in the example means that this tool behaves like a
542 linker.
613543
614544 The list of all possible actions follows.
615545
655585 Language map
656586 ============
657587
658 If you are adding support for a new language to LLVMC, you'll need to
659 modify the language map, which defines mappings from file extensions
660 to language names. It is used to choose the proper toolchain(s) for a
661 given input file set. Language map definition looks like this::
588 If you are adding support for a new language to LLVMC, you'll need to modify the
589 language map, which defines mappings from file extensions to language names. It
590 is used to choose the proper toolchain(s) for a given input file set. Language
591 map definition looks like this::
662592
663593 def LanguageMap : LanguageMap<
664594 [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
672602 llvmc: Unknown suffix: cpp
673603
674604 The language map entries are needed only for the tools that are linked from the
675 root node. Since a tool can't have multiple output languages, for inner nodes of
676 the graph the input and output languages should match. This is enforced at
677 compile-time.
605 root node. A tool can have multiple output languages.
678606
679607 Option preprocessor
680608 ===================
685613 the driver with both of these options enabled.
686614
687615 The ``OptionPreprocessor`` feature is reserved specially for these
688 occasions. Example (adapted from the built-in Base plugin)::
616 occasions. Example (adapted from ``llvm/src/Base.td.in``)::
689617
690618
691619 def Preprocess : OptionPreprocessor<
704632 specified, ``-O2`` is enabled.
705633
706634 ``OptionPreprocessor`` is basically a single big ``case`` expression, which is
707 evaluated only once right after the plugin is loaded. The only allowed actions
635 evaluated only once right after the driver is started. The only allowed actions
708636 in ``OptionPreprocessor`` are ``error``, ``warning``, and two special actions:
709637 ``unset_option`` and ``set_option``. As their names suggest, they can be used to
710638 set or unset a given option. To set an option with ``set_option``, use the
725653 Hooks and environment variables
726654 -------------------------------
727655
728 Normally, LLVMC executes programs from the system ``PATH``. Sometimes,
729 this is not sufficient: for example, we may want to specify tool paths
730 or names in the configuration file. This can be easily achieved via
731 the hooks mechanism. To write your own hooks, just add their
732 definitions to the ``PluginMain.cpp`` or drop a ``.cpp`` file into the
733 your plugin directory. Hooks should live in the ``hooks`` namespace
734 and have the signature ``std::string hooks::MyHookName ([const char*
735 Arg0 [ const char* Arg2 [, ...]]])``. They can be used from the
736 ``cmd_line`` tool property::
737
738 (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
656 Normally, LLVMC searches for programs in the system ``PATH``. Sometimes, this is
657 not sufficient: for example, we may want to specify tool paths or names in the
658 configuration file. This can be achieved via the hooks mechanism. To write your
659 own hooks, add their definitions to the ``Hooks.cpp`` or drop a ``.cpp`` file
660 into your driver directory. Hooks should live in the ``hooks`` namespace and
661 have the signature ``std::string hooks::MyHookName ([const char* Arg0 [ const
662 char* Arg2 [, ...]]])``. They can be used from the ``command`` tool property::
663
664 (command "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
739665
740666 To pass arguments to hooks, use the following syntax::
741667
742 (cmd_line "$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2")
668 (command "$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2")
743669
744670 It is also possible to use environment variables in the same manner::
745671
746 (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
672 (command "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
747673
748674 To change the command line string based on user-provided options use
749675 the ``case`` expression (documented `above`__)::
750676
751 (cmd_line
677 (command
752678 (case
753679 (switch_on "E"),
754680 "llvm-g++ -E -x c $INFILE -o $OUTFILE",
757683
758684 __ case_
759685
760 .. _priorities:
761
762 How plugins are loaded
763 ----------------------
764
765 It is possible for LLVMC plugins to depend on each other. For example,
766 one can create edges between nodes defined in some other plugin. To
767 make this work, however, that plugin should be loaded first. To
768 achieve this, the concept of plugin priority was introduced. By
769 default, every plugin has priority zero; to specify the priority
770 explicitly, put the following line in your plugin's TableGen file::
771
772 def Priority : PluginPriority<$PRIORITY_VALUE>;
773 # Where PRIORITY_VALUE is some integer > 0
774
775 Plugins are loaded in order of their (increasing) priority, starting
776 with 0. Therefore, the plugin with the highest priority value will be
777 loaded last.
778
779686 Debugging
780687 ---------
781688
782 When writing LLVMC plugins, it can be useful to get a visual view of
783 the resulting compilation graph. This can be achieved via the command
784 line option ``--view-graph``. This command assumes that Graphviz_ and
785 Ghostview_ are installed. There is also a ``--write-graph`` option that
786 creates a Graphviz source file (``compilation-graph.dot``) in the
787 current directory.
788
789 Another useful ``llvmc`` option is ``--check-graph``. It checks the
790 compilation graph for common errors like mismatched output/input
791 language names, multiple default edges and cycles. These checks can't
792 be performed at compile-time because the plugins can load code
793 dynamically. When invoked with ``--check-graph``, ``llvmc`` doesn't
794 perform any compilation tasks and returns the number of encountered
795 errors as its status code.
689 When writing LLVMC-based drivers, it can be useful to get a visual view of the
690 resulting compilation graph. This can be achieved via the command line option
691 ``--view-graph`` (which assumes that Graphviz_ and Ghostview_ are
692 installed). There is also a ``--write-graph`` option that creates a Graphviz
693 source file (``compilation-graph.dot``) in the current directory.
694
695 Another useful ``llvmc`` option is ``--check-graph``. It checks the compilation
696 graph for common errors like mismatched output/input language names, multiple
697 default edges and cycles. When invoked with ``--check-graph``, ``llvmc`` doesn't
698 perform any compilation tasks and returns the number of encountered errors as
699 its status code. In the future, these checks will be performed at compile-time
700 and this option will disappear.
796701
797702 .. _Graphviz: http://www.graphviz.org/
798703 .. _Ghostview: http://pages.cs.wisc.edu/~ghost/
820725
821726 In general, you're encouraged not to make the behaviour dependent on the
822727 executable file name, and use command-line switches instead. See for example how
823 the ``Base`` plugin behaves when it needs to choose the correct linker options
728 the ``llvmc`` program behaves when it needs to choose the correct linker options
824729 (think ``g++`` vs. ``gcc``).
825730
826731 .. raw:: html
1616 Introduction
1717 ============
1818
19 LLVMC is a generic compiler driver, which plays the same role for LLVM
20 as the ``gcc`` program does for GCC - the difference being that LLVMC
21 is designed to be more adaptable and easier to customize. Most of
22 LLVMC functionality is implemented via plugins, which can be loaded
23 dynamically or compiled in. This tutorial describes the basic usage
24 and configuration of LLVMC.
19 LLVMC is a generic compiler driver, which plays the same role for LLVM as the
20 ``gcc`` program does for GCC - the difference being that LLVMC is designed to be
21 more adaptable and easier to customize. Most of LLVMC functionality is
22 implemented via high-level TableGen code, from which a corresponding C++ source
23 file is automatically generated. This tutorial describes the basic usage and
24 configuration of LLVMC.
2525
2626
27 Compiling with LLVMC
28 ====================
27 Using the ``llvmc`` program
28 ===========================
2929
30 In general, LLVMC tries to be command-line compatible with ``gcc`` as
31 much as possible, so most of the familiar options work::
30 In general, ``llvmc`` tries to be command-line compatible with ``gcc`` as much
31 as possible, so most of the familiar options work::
3232
3333 $ llvmc -O3 -Wall hello.cpp
3434 $ ./a.out
3535 hello
3636
37 This will invoke ``llvm-g++`` under the hood (you can see which
38 commands are executed by using the ``-v`` option). For further help on
39 command-line LLVMC usage, refer to the ``llvmc --help`` output.
37 This will invoke ``llvm-g++`` under the hood (you can see which commands are
38 executed by using the ``-v`` option). For further help on command-line LLVMC
39 usage, refer to the ``llvmc --help`` output.
4040
4141
4242 Using LLVMC to generate toolchain drivers
4343 =========================================
4444
45 LLVMC plugins are written mostly using TableGen_, so you need to
46 be familiar with it to get anything done.
45 LLVMC-based drivers are written mostly using TableGen_, so you need to be
46 familiar with it to get anything done.
4747
4848 .. _TableGen: http://llvm.org/docs/TableGenFundamentals.html
4949
5050 Start by compiling ``example/Simple``, which is a primitive wrapper for
5151 ``gcc``::
5252
53 $ cd $LLVM_DIR/tools/llvmc
54 $ cp -r example/Simple plugins/Simple
55
56 # NB: A less verbose way to compile standalone LLVMC-based drivers is
57 # described in the reference manual.
58
59 $ make LLVMC_BASED_DRIVER_NAME=mygcc LLVMC_BUILTIN_PLUGINS=Simple
53 $ cd $LLVM_OBJ_DIR/tools/examples/Simple
54 $ make
6055 $ cat > hello.c
61 [...]
62 $ mygcc hello.c
56 #include
57 int main() { printf("Hello\n"); }
58 $ $LLVM_BIN_DIR/Simple -v hello.c
59 gcc hello.c -o hello.out
6360 $ ./hello.out
6461 Hello
6562
66 Here we link our plugin with the LLVMC core statically to form an executable
67 file called ``mygcc``. It is also possible to build our plugin as a dynamic
68 library to be loaded by the ``llvmc`` executable (or any other LLVMC-based
69 standalone driver); this is described in the reference manual.
70
71 Contents of the file ``Simple.td`` look like this::
63 We have thus produced a simple driver called, appropriately, ``Simple``, from
64 the input TableGen file ``Simple.td``. The ``llvmc`` program itself is generated
65 using a similar process (see ``llvmc/src``). Contents of the file ``Simple.td``
66 look like this::
7267
7368 // Include common definitions
7469 include "llvm/CompilerDriver/Common.td"
7873 [(in_language "c"),
7974 (out_language "executable"),
8075 (output_suffix "out"),
81 (cmd_line "gcc $INFILE -o $OUTFILE"),
82 (sink)
76 (command "gcc"),
77 (sink),
78
79 // -o is what is used by default, out_file_option here is included for
80 // instructive purposes.
81 (out_file_option "-o")
8382 ]>;
8483
8584 // Language map
86 def LanguageMap : LanguageMap<[LangToSuffixes<"c", ["c"]>]>;
85 def LanguageMap : LanguageMap<[(lang_to_suffixes "c", "c")]>;
8786
8887 // Compilation graph
89 def CompilationGraph : CompilationGraph<[Edge<"root", "gcc">]>;
88 def CompilationGraph : CompilationGraph<[(edge "root", "gcc")]>;
9089
91 As you can see, this file consists of three parts: tool descriptions,
92 language map, and the compilation graph definition.
90 As you can see, this file consists of three parts: tool descriptions, language
91 map, and the compilation graph definition.
9392
94 At the heart of LLVMC is the idea of a compilation graph: vertices in
95 this graph are tools, and edges represent a transformation path
96 between two tools (for example, assembly source produced by the
97 compiler can be transformed into executable code by an assembler). The
98 compilation graph is basically a list of edges; a special node named
99 ``root`` is used to mark graph entry points.
93 At the heart of LLVMC is the idea of a compilation graph: vertices in this graph
94 are tools, and edges represent a transformation path between two tools (for
95 example, assembly source produced by the compiler can be transformed into
96 executable code by an assembler). The compilation graph is basically a list of
97 edges; a special node named ``root`` is used to mark graph entry points.
10098
101 Tool descriptions are represented as property lists: most properties
102 in the example above should be self-explanatory; the ``sink`` property
103 means that all options lacking an explicit description should be
104 forwarded to this tool.
99 Tool descriptions are represented as property lists: most properties in the
100 example above should be self-explanatory; the ``sink`` property means that all
101 options lacking an explicit description should be forwarded to this tool.
105102
106 The ``LanguageMap`` associates a language name with a list of suffixes
107 and is used for deciding which toolchain corresponds to a given input
108 file.
103 The ``LanguageMap`` associates a language name with a list of suffixes and is
104 used for deciding which toolchain corresponds to a given input file.
109105
110 To learn more about LLVMC customization, refer to the reference
111 manual and plugin source code in the ``plugins`` directory.
106 To learn more about writing your own drivers with LLVMC, refer to the reference
107 manual and examples in the ``examples`` directory. Of a particular interest is
108 the ``Skeleton`` example, which can serve as a template for your LLVMC-based
109 drivers.
112110
113111 .. raw:: html
114112