diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html index 761d6ee6810..0a3f8771623 100644 --- a/docs/CompilerDriver.html +++ b/docs/CompilerDriver.html @@ -17,28 +17,28 @@ The ReST source lives in the directory 'tools/llvmc/doc'. -->

Contents

-

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 +517,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 +555,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 +587,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 @@ -602,7 +610,7 @@ multiple output languages, for nodes "inside" 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 @@ -629,9 +637,9 @@ in OptionPreprocessor convenience, unset_option also works on lists.

    -

    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 +672,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 +688,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 +704,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 +712,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 +739,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) $