X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FCompilerDriver.html;h=5f5788c1edff2ecf3cde39b6438dc771e4130ee2;hb=bec487767c3e0a376eed7c37773c88d6fcc8e4d9;hp=761d6ee6810db1da1eaff7e5a4d9988e045278b5;hpb=8b67f774e9c38b7718b2b300b628388f966df4e0;p=oota-llvm.git diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html index 761d6ee6810..5f5788c1edf 100644 --- a/docs/CompilerDriver.html +++ b/docs/CompilerDriver.html @@ -17,28 +17,28 @@ The ReST source lives in the directory 'tools/llvmc/doc'. -->
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 @@ -63,7 +63,7 @@ example, as a build tool for game resources.
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:
@@ -100,7 +100,7 @@ hello 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:
@@ -176,7 +176,7 @@ $ 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 @@ -215,7 +215,7 @@ $ make LLVMC_BUILTIN_PLUGINS=""
Each TableGen configuration file should include the common definitions:
@@ -283,7 +283,7 @@ debugging), run llvmcgsview installed for this to work properly.
Command-line options that the plugin supports are defined by using an OptionList:
@@ -334,31 +334,37 @@ once). Incompatible with zero_or_
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
+
- optional - 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.
+- comma_separated - Indicates that any commas specified for an option's
+value should be used to split the value up into multiple values for the
+option. This property is valid only for list options. In conjunction with
+forward_value can be used to implement option forwarding in style of
+gcc's -Wa,.
- 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
+this attribute; you can, however, use the one_or_more, optional
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.
+parameter), or a boolean (if it is a switch; as in C++, boolean constants
+are called true and false). List options can't have init
+attribute.
+Usage examples: (switch_option "foo", (init true)); (prefix_option
+"bar", (init "baz")).
+- extern - this option is defined in some other plugin, see below.
-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
@@ -374,7 +380,7 @@ ignored. See also the section on plugin
-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'
@@ -433,7 +439,7 @@ a given value.
Example: (parameter_equals "W", "all").
- element_in_list - Returns true if a command-line parameter
list contains a given value.
-Example: (parameter_in_list "l", "pthread").
+Example: (element_in_list "l", "pthread").
- input_languages_contain - Returns true if a given language
belongs to the current input language set.
Example: (input_languages_contain "c++").
@@ -475,7 +481,7 @@ argument. Example: (not
-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):
@@ -512,12 +518,12 @@ list of input files and joins them together. Used for linkers.
tools are passed to this tool.
- actions - A single big case expression that specifies how
this tool reacts on command-line options (described in more detail
-below).
+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:
@@ -550,28 +556,31 @@ like a linker.
Possible actions:
-- append_cmd - append a string to the tool invocation
-command.
-Example: (case (switch_on "pthread"), (append_cmd
-"-lpthread"))
-- error - exit with error.
+
- append_cmd - Append a string to the tool invocation command.
+Example: (case (switch_on "pthread"), (append_cmd "-lpthread")).
+- error - Exit with error.
Example: (error "Mixing -c and -S is not allowed!").
-- warning - print a warning.
+
- warning - Print a warning.
Example: (warning "Specifying both -O1 and -O2 is meaningless!").
-- forward - forward an option unchanged. Example: (forward "Wall").
-- forward_as - Change the name of an option, but forward the
-argument unchanged.
+
- forward - Forward the option unchanged.
+Example: (forward "Wall").
+- forward_as - Change the option's name, but forward the argument
+unchanged.
Example: (forward_as "O0", "--disable-optimization").
-- output_suffix - modify the output suffix of this
-tool.
+
- forward_value - Forward only option's value. Cannot be used with switch
+options (since they don't have values), but works fine with lists.
+Example: (forward_value "Wa,").
+- forward_transformed_value - As above, but applies a hook to the
+option's value before forwarding (see below). When
+forward_transformed_value is applied to a list
+option, the hook must have signature
+std::string hooks::HookName (const std::vector<std::string>&).
+Example: (forward_transformed_value "m", "ConvertToMAttr").
+- output_suffix - Modify the output suffix of this tool.
Example: (output_suffix "i").
-- stop_compilation - stop compilation after this tool processes
-its input. Used without arguments.
-- unpack_values - used for for splitting and forwarding
-comma-separated lists of options, e.g. -Wa,-foo=bar,-baz is
-converted to -foo=bar -baz and appended to the tool invocation
-command.
-Example: (unpack_values "Wa,").
+- stop_compilation - Stop compilation after this tool processes its
+input. Used without arguments.
+Example: (stop_compilation).
@@ -579,7 +588,7 @@ 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
@@ -596,13 +605,13 @@ def LanguageMap : LanguageMap<
$ llvmc hello.cpp
llvmc: Unknown suffix: cpp
-
The language map entries should be added only for tools that are
-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.
+The language map entries are needed only for the tools that are linked from the
+root node. Since a tool can't have multiple output languages, for inner nodes of
+the graph the input and output languages should match. This is enforced at
+compile-time.
-Option preprocessor
+Option preprocessor
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
@@ -611,27 +620,35 @@ the driver with both of these options enabled.
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.")],
+(case (not (any_switch_on ["O0", "O1", "O2", "O3"])),
+ (set_option "O2"),
+ (and (switch_on "O3"), (any_switch_on ["O0", "O1", "O2"])),
+ (unset_option ["O0", "O1", "O2"]),
(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).
+Here, OptionPreprocessor is used to unset all spurious -O options so
+that they are not forwarded to the compiler. If no optimization options are
+specified, -O2 is enabled.
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.
+in OptionPreprocessor are error, warning, and two special actions:
+unset_option and set_option. As their names suggest, they can be used to
+set or unset a given option. To set an option with set_option, use the
+two-argument form: (set_option "parameter", VALUE). Here, VALUE can be
+either a string, a string list, or a boolean constant.
+For convenience, set_option and unset_option also work on lists. That
+is, instead of [(unset_option "A"), (unset_option "B")] you can use
+(unset_option ["A", "B"]). Obviously, (set_option ["A", "B"]) is valid
+only if both A and B are switches.
-More advanced topics
+More advanced topics
-Hooks and environment variables
+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
@@ -664,7 +681,7 @@ the case expression (
-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
@@ -680,7 +697,7 @@ 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
@@ -696,7 +713,7 @@ perform any compilation tasks and returns the number of encountered
errors as its status code.
-Conditioning on the executable name
+Conditioning on the executable name
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:
@@ -704,12 +721,16 @@ namespace llvmc {
extern const char* ProgramName;
}
+namespace hooks {
+
std::string MyHook() {
//...
if (strcmp(ProgramName, "mydriver") == 0) {
//...
}
+
+} // end namespace hooks
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
@@ -727,7 +748,7 @@ the Base plugin behav
Mikhail Glushenkov
LLVM Compiler Infrastructure
-Last modified: $Date$
+Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $