X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FCompilerDriver.html;h=761d6ee6810db1da1eaff7e5a4d9988e045278b5;hb=f9be95f867745b6754b2402b9b72f9eaeabd637f;hp=fc687f1667511468f6742a4f6a73184c6c19b780;hpb=5303c75a4929ebb233e612f3b52b7dc4b11ae6b5;p=oota-llvm.git diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html index fc687f16675..761d6ee6810 100644 --- a/docs/CompilerDriver.html +++ b/docs/CompilerDriver.html @@ -3,46 +3,50 @@
- +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:
@@ -138,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):
@@ -150,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:
@@ -243,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:
@@ -305,15 +344,21 @@ output). output.
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 must be marked as @@ -324,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' @@ -373,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):
@@ -431,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:
@@ -487,13 +554,14 @@ like a linker. command. Example: (case (switch_on "pthread"), (append_cmd "-lpthread")) -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 @@ -533,10 +601,37 @@ 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 paths
or names in the configuration file. This can be easily achieved via
@@ -558,7 +653,7 @@ and have the signature std::strin
(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):
(cmd_line
(case
@@ -568,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 @@ -584,12 +679,12 @@ 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 @@ -599,6 +694,27 @@ 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).