Customizing LLVMC: Reference Manual

+ -

Introduction

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 +56,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.

Compiling with 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:

@@ -96,8 +97,8 @@ hello also possible to choose the work-in-progress clang compiler with the -clang option.

Predefined options

LLVMC has some built-in options that can't be overridden in the configuration libraries:

@@ -125,8 +126,8 @@ and do not delete them on exit. Hidden option, useful for debugging. their standard meaning.

Compiling LLVMC plugins

It's easiest to start working on your own LLVMC plugin by copying the skeleton project which lives under $LLVMC_DIR/plugins/Simple:

@@ -141,7 +142,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):
@@ -178,8 +179,8 @@ $ cd $LLVMC_DIR
 $ make BUILTIN_PLUGINS=""

- -Customizing LLVMC: the compilation graph + +Customizing LLVMC: the compilation graph Each TableGen configuration file should include the common definitions: @@ -246,8 +247,8 @@ plugin priority feature described above. debugging), run llvmc --view-graph. You will need dot and gsview installed for this to work properly. - -Describing options + +Describing options Command-line options that the plugin supports are defined by using an OptionList: @@ -315,8 +316,8 @@ the one_or_more and < - -External options + +External options 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 @@ -327,11 +328,11 @@ for. Example: (switch_option "E", (extern)) ... -See also the section on plugin priorities. +See also the section on plugin priorities. - -Conditional evaluation + +Conditional evaluation 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' @@ -410,8 +411,8 @@ one of its arguments returns true. Example: - -Writing a tool description + +Writing a tool description 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): @@ -452,8 +453,8 @@ below). - -Actions + +Actions 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: @@ -496,7 +497,7 @@ Example: (case (forward "Wall"). forward_as - Change the name of an option, but forward the argument unchanged. -Example: (forward_as "O0" "--disable-optimization"). +Example: (forward_as "O0", "--disable-optimization"). output_suffix - modify the output suffix of this tool. Example: (output_suffix "i"). @@ -513,8 +514,8 @@ Example: (unpack_values - -Language map + +Language map 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 @@ -536,10 +537,10 @@ 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. - -More advanced topics - -Hooks and environment variables + +More advanced topics + +Hooks and environment variables 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 @@ -561,7 +562,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): +the case expression (documented above): (cmd_line (case @@ -571,8 +572,8 @@ the case expression ( "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm")) - -How plugins are loaded + +How plugins are loaded 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 @@ -587,12 +588,12 @@ def Priority : PluginPriority<$PRIORITY_VALUE>; with 0. Therefore, the plugin with the highest priority value will be loaded last. - -Debugging + +Debugging 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 --write-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 diff --git a/docs/CompilerDriverTutorial.html b/docs/CompilerDriverTutorial.html index d2b3a595e17..a5780173795 100644 --- a/docs/CompilerDriverTutorial.html +++ b/docs/CompilerDriverTutorial.html @@ -3,28 +3,29 @@ - + Tutorial - Using LLVMC Tutorial - Using LLVMC + - -Contents + +Contents -Introduction -Compiling with LLVMC -Using LLVMC to generate toolchain drivers +Introduction +Compiling with LLVMC +Using LLVMC to generate toolchain drivers Written by Mikhail Glushenkov - -Introduction + +Introduction LLVMC is a generic compiler driver, which plays the same role for LLVM as the gcc program does for GCC - the difference being that LLVMC is designed to be more adaptable and easier to customize. Most of @@ -32,8 +33,8 @@ LLVMC functionality is implemented via plugins, which can be loaded dynamically or compiled in. This tutorial describes the basic usage and configuration of LLVMC. - -Compiling with LLVMC + +Compiling with LLVMC In general, LLVMC tries to be command-line compatible with gcc as much as possible, so most of the familiar options work: @@ -45,9 +46,9 @@ hello commands are executed by using the -v option). For further help on command-line LLVMC usage, refer to the llvmc --help output. - -Using LLVMC to generate toolchain drivers -LLVMC plugins are written mostly using TableGen, so you need to + +Using LLVMC to generate toolchain drivers +LLVMC plugins are written mostly using TableGen, so you need to be familiar with it to get anything done. Start by compiling plugins/Simple/Simple.td, which is a primitive wrapper for gcc: diff --git a/docs/llvm.css b/docs/llvm.css index 29d40c518e6..f572b5e5714 100644 --- a/docs/llvm.css +++ b/docs/llvm.css @@ -72,7 +72,7 @@ h3, .doc_subsubsection { margin: 2.0em 0.5em 0.5em 0.5em; /* It is preferrable to use everywhere instead of the * ... construct. - * + * * Once all docs use for code regions, this style can be merged with the * one above, and we can drop the [pre] qualifier. */ @@ -95,6 +95,6 @@ th.layout { border: none; font-weight: bold; font-size: 105%; /* ReST-specific */ .title { margin-top: 0 } -#contents { display: none } +.topic-title{ display: none } div.contents ul { list-style-type: decimal } .toc-backref { color: black; text-decoration: none; }