Contents
LLVMC is a generic compiler driver, designed to be customizable and extensible. It plays the same role for LLVM as the gcc program does for GCC - LLVMC's job is essentially to transform a set of input @@ -55,11 +59,11 @@ abstract graph. The structure of this graph is completely determined by plugins, which can be either statically or dynamically linked. This makes it possible to easily adapt LLVMC for other purposes - for example, as a build tool for game resources.
-Because LLVMC employs TableGen as its configuration language, you +
Because LLVMC employs TableGen as its configuration language, you need to be familiar with it to customize LLVMC.
LLVMC tries hard to be as compatible with gcc as possible, although there are some small differences. Most of the time, however, you shouldn't be able to notice them:
@@ -69,12 +73,12 @@ $ llvmc -O3 -Wall hello.cpp $ ./a.out hello -One nice feature of LLVMC is that one doesn't have to distinguish -between different compilers for different languages (think g++ and -gcc) - the right toolchain is chosen automatically based on input -language names (which are, in turn, determined from file -extensions). If you want to force files ending with ".c" to compile as -C++, use the -x option, just like you would do it with gcc:
+One nice feature of LLVMC is that one doesn't have to distinguish between +different compilers for different languages (think g++ vs. gcc) - the +right toolchain is chosen automatically based on input language names (which +are, in turn, determined from file extensions). If you want to force files +ending with ".c" to compile as C++, use the -x option, just like you would +do it with gcc:
$ # hello.c is really a C++ file $ llvmc -x c++ hello.c @@ -92,12 +96,11 @@ $ llvmc --linker=c++ hello.o $ ./a.out hello-
By default, LLVMC uses llvm-gcc to compile the source code. It is -also possible to choose the work-in-progress clang compiler with -the -clang option.
+By default, LLVMC uses llvm-gcc to compile the source code. It is also +possible to choose the clang compiler with the -clang option.
LLVMC has some built-in options that can't be overridden in the configuration libraries:
It's easiest to start working on your own LLVMC plugin by copying the skeleton project which lives under $LLVMC_DIR/plugins/Simple:
@@ -135,7 +152,7 @@ counting the build script). Simpl
description of the compilation graph; its format is documented in the
following sections. PluginMain.cpp is just a helper file used to
compile the auto-generated C++ code produced from TableGen source. It
-can also contain hook definitions (see below).
+can also contain hook definitions (see below).
The first thing that you should do is to change the LLVMC_PLUGIN
variable in the Makefile to avoid conflicts (since this variable
is used to name the resulting library):
@@ -147,33 +164,58 @@ generic:
$ mv Simple.td MyPlugin.td
-Note that the plugin source directory must be placed under
-$LLVMC_DIR/plugins to make use of the existing build
-infrastructure. To build a version of the LLVMC executable called
-mydriver with your plugin compiled in, use the following command:
-
-$ cd $LLVMC_DIR
-$ make BUILTIN_PLUGINS=MyPlugin DRIVER_NAME=mydriver
-
To build your plugin as a dynamic library, just cd to its source
directory and run make. The resulting file will be called
-LLVMC$(LLVMC_PLUGIN).$(DLL_EXTENSION) (in our case,
-LLVMCMyPlugin.so). This library can be then loaded in with the
+plugin_llvmc_$(LLVMC_PLUGIN).$(DLL_EXTENSION) (in our case,
+plugin_llvmc_MyPlugin.so). This library can be then loaded in with the
-load option. Example:
$ cd $LLVMC_DIR/plugins/Simple
$ make
-$ llvmc -load $LLVM_DIR/Release/lib/LLVMCSimple.so
+$ llvmc -load $LLVM_DIR/Release/lib/plugin_llvmc_Simple.so
+By default, the llvmc executable consists of a driver core plus several +statically linked plugins (Base and Clang at the moment). You can +produce a standalone LLVMC-based driver executable by linking the core with your +own plugins. The recommended way to do this is by starting with the provided +Skeleton example ($LLVMC_DIR/example/Skeleton):
++$ cd $LLVMC_DIR/example/ +$ cp -r Skeleton mydriver +$ cd mydriver +$ vim Makefile +[...] +$ make ++
If you're compiling LLVM with different source and object directories, then you +must perform the following additional steps before running make:
++# LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/ +# LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/ +$ cp $LLVMC_SRC_DIR/example/mydriver/Makefile \ + $LLVMC_OBJ_DIR/example/mydriver/ +$ cd $LLVMC_OBJ_DIR/example/mydriver +$ make ++
Another way to do the same thing is by using the following command:
++$ cd $LLVMC_DIR +$ make LLVMC_BUILTIN_PLUGINS=MyPlugin LLVMC_BASED_DRIVER_NAME=mydriver ++
This works with both srcdir == objdir and srcdir != objdir, but assumes that the +plugin source directory was placed under $LLVMC_DIR/plugins.
Sometimes, you will want a 'bare-bones' version of LLVMC that has no built-in plugins. It can be compiled with the following command:
$ cd $LLVMC_DIR -$ make BUILTIN_PLUGINS="" +$ make LLVMC_BUILTIN_PLUGINS=""
Each TableGen configuration file should include the common definitions:
@@ -240,8 +282,8 @@ plugin priority feature described above. debugging), run llvmc --view-graph. You will need dot and gsview installed for this to work properly.
Command-line options that the plugin supports are defined by using an OptionList:
@@ -260,42 +302,66 @@ separate option groups syntactically.
Possible option types:
-
- switch_option - a simple boolean switch, for example -time.
-- parameter_option - option that takes an argument, for example --std=c99;
-- parameter_list_option - same as the above, but more than one -occurence of the option is allowed.
-- prefix_option - same as the parameter_option, but the option name -and parameter value are not separated.
-- prefix_list_option - same as the above, but more than one -occurence of the option is allowed; example: -lm -lpthread.
-- alias_option - a special option type for creating -aliases. Unlike other option types, aliases are not allowed to -have any properties besides the aliased option name. Usage -example: (alias_option "preprocess", "E")
+- switch_option - a simple boolean switch without arguments, for example +-O2 or -time. At most one occurrence is allowed.
+- parameter_option - option that takes one argument, for example +-std=c99. It is also allowed to use spaces instead of the equality +sign: -std c99. At most one occurrence is allowed.
+- parameter_list_option - same as the above, but more than one option +occurence is allowed.
+- prefix_option - same as the parameter_option, but the option name and +argument do not have to be separated. Example: -ofile. This can be also +specified as -o file; however, -o=file will be parsed incorrectly +(=file will be interpreted as option value). At most one occurrence is +allowed.
+- prefix_list_option - same as the above, but more than one occurence of +the option is allowed; example: -lm -lpthread.
+- alias_option - a special option type for creating aliases. Unlike other +option types, aliases are not allowed to have any properties besides the +aliased option name. Usage example: (alias_option "preprocess", "E")
Possible option properties:
-
- help - help string associated with this option. Used for ---help output.
-- required - this option is obligatory.
-- hidden - this option should not appear in the --help -output (but should appear in the --help-hidden output).
-- really_hidden - the option should not appear in any help +
- help - help string associated with this option. Used for --help +output.
+- required - this option must be specified exactly once (or, in case of +the list options without the multi_val property, at least +once). Incompatible with zero_or_one and one_or_more.
+- one_or_more - the option must be specified at least one time. Useful +only for list options in conjunction with multi_val; for ordinary lists +it is synonymous with required. Incompatible with required and +zero_or_one.
+- zero_or_one - the option can be specified zero or one times. Useful +only for list options in conjunction with multi_val. Incompatible with +required and one_or_more.
+- hidden - the description of this option will not appear in +the --help output (but will appear in the --help-hidden +output).
+- really_hidden - the option will not be mentioned in any help output.
+- multi_val n - this option takes n arguments (can be useful in some +special cases). Usage example: (parameter_list_option "foo", (multi_val +3)); the command-line syntax is '-foo a b c'. Only list options can have +this attribute; you can, however, use the one_or_more, zero_or_one +and required properties.
+- init - this option has a default value, either a string (if it is a +parameter), or a boolean (if it is a switch; boolean constants are called +true and false). List options can't have this attribute. Usage +examples: (switch_option "foo", (init true)); (prefix_option "bar", +(init "baz")).
- extern - this option is defined in some other plugin, see below.
Sometimes, when linking several plugins together, one plugin needs to access options defined in some other plugin. Because of the way -options are implemented, such options should be marked as +options are implemented, such options must be marked as extern. This is what the extern option property is for. Example:
@@ -303,11 +369,12 @@ for. Example: (switch_option "E", (extern)) ...-
See also the section on plugin priorities.
+If an external option has additional attributes besides 'extern', they are +ignored. See also the section on plugin priorities.
The 'case' construct is the main means by which programmability is achieved in LLVMC. It can be used to calculate edge weights, program actions and modify the shell commands to be executed. The 'case' @@ -352,8 +419,15 @@ readability. It is usually better to split tool descriptions and/or use TableGen inheritance instead.
As was said earlier, nodes in the compilation graph represent tools, which are described separately. A tool definition looks like this (taken from the include/llvm/CompilerDriver/Tools.td file):
@@ -408,8 +498,8 @@ options that aren't mentioned in the option list.A tool often needs to react to command-line options, and this is precisely what the actions property is for. The next example illustrates this feature:
@@ -462,12 +552,16 @@ like a linker.If you are adding support for a new language to LLVMC, you'll need to modify the language map, which defines mappings from file extensions to language names. It is used to choose the proper toolchain(s) for a @@ -507,27 +601,59 @@ linked with the root node. Since tools are not allowed to have multiple output languages, for nodes "inside" the graph the input and output languages should match. This is enforced at compile-time.
It is sometimes useful to run error-checking code before processing the +compilation graph. For example, if optimization options "-O1" and "-O2" are +implemented as switches, we might want to output a warning if the user invokes +the driver with both of these options enabled.
+The OptionPreprocessor feature is reserved specially for these +occasions. Example (adapted from the built-in Base plugin):
++def Preprocess : OptionPreprocessor< +(case (and (switch_on "O3"), (any_switch_on ["O0", "O1", "O2"])), + [(unset_option ["O0", "O1", "O2"]), + (warning "Multiple -O options specified, defaulted to -O3.")], + (and (switch_on "O2"), (any_switch_on ["O0", "O1"])), + (unset_option ["O0", "O1"]), + (and (switch_on "O1"), (switch_on "O0")), + (unset_option "O0")) +>; ++
Here, OptionPreprocessor is used to unset all spurious optimization options +(so that they are not forwarded to the compiler).
+OptionPreprocessor is basically a single big case expression, which is +evaluated only once right after the plugin is loaded. The only allowed actions +in OptionPreprocessor are error, warning and a special action +unset_option, which, as the name suggests, unsets a given option. For +convenience, unset_option also works on lists.
+Normally, LLVMC executes programs from the system PATH. Sometimes, -this is not sufficient: for example, we may want to specify tool names -in the configuration file. This can be achieved via the mechanism of -hooks - to write your own hooks, just add their definitions to the -PluginMain.cpp or drop a .cpp file into the -$LLVMC_DIR/driver directory. Hooks should live in the hooks -namespace and have the signature std::string hooks::MyHookName -(void). They can be used from the cmd_line tool property:
+this is not sufficient: for example, we may want to specify tool paths +or names in the configuration file. This can be easily achieved via +the hooks mechanism. To write your own hooks, just add their +definitions to the PluginMain.cpp or drop a .cpp file into the +your plugin directory. Hooks should live in the hooks namespace +and have the signature std::string hooks::MyHookName ([const char* +Arg0 [ const char* Arg2 [, ...]]]). They can be used from the +cmd_line tool property:(cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")+
To pass arguments to hooks, use the following syntax:
++(cmd_line "$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2") +
It is also possible to use environment variables in the same manner:
(cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)")
To change the command line string based on user-provided options use -the case expression (documented above):
+the case expression (documented above):
(cmd_line
(case
@@ -537,8 +663,8 @@ the case expression (
"llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm"))
It is possible for LLVMC plugins to depend on each other. For example, one can create edges between nodes defined in some other plugin. To make this work, however, that plugin should be loaded first. To @@ -553,14 +679,42 @@ def Priority : PluginPriority<$PRIORITY_VALUE>; with 0. Therefore, the plugin with the highest priority value will be loaded last.
When writing LLVMC plugins, it can be useful to get a visual view of the resulting compilation graph. This can be achieved via the command -line option --view-graph. This command assumes that Graphviz and -Ghostview are installed. There is also a --dump-graph option that +line option --view-graph. This command assumes that Graphviz and +Ghostview are installed. There is also a --write-graph option that creates a Graphviz source file (compilation-graph.dot) in the current directory.
+Another useful llvmc option is --check-graph. It checks the +compilation graph for common errors like mismatched output/input +language names, multiple default edges and cycles. These checks can't +be performed at compile-time because the plugins can load code +dynamically. When invoked with --check-graph, llvmc doesn't +perform any compilation tasks and returns the number of encountered +errors as its status code.
+For now, the executable name (the value passed to the driver in argv[0]) is +accessible only in the C++ code (i.e. hooks). Use the following code:
+
+namespace llvmc {
+extern const char* ProgramName;
+}
+
+std::string MyHook() {
+//...
+if (strcmp(ProgramName, "mydriver") == 0) {
+ //...
+
+}
+
+In general, you're encouraged not to make the behaviour dependent on the +executable file name, and use command-line switches instead. See for example how +the Base plugin behaves when it needs to choose the correct linker options +(think g++ vs. gcc).