| =================================== |
| Customizing LLVMC: Reference Manual |
| =================================== |
| .. |
| This file was automatically generated by rst2html. |
| Please do not edit directly! |
| The ReST source lives in the directory 'tools/llvmc/doc'. |
| |
| .. contents:: |
| |
| .. raw:: html |
| |
| <div class="doc_author"> |
| <p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p> |
| </div> |
| |
| 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 |
| files into a set of targets depending on configuration rules and user |
| options. What makes LLVMC different is that these transformation rules |
| are completely customizable - in fact, LLVMC knows nothing about the |
| specifics of transformation (even the command-line options are mostly |
| not hard-coded) and regards the transformation structure as an |
| 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 |
| need to be familiar with it to customize LLVMC. |
| |
| .. _TableGen: http://llvm.org/docs/TableGenFundamentals.html |
| |
| |
| 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:: |
| |
| $ # This works as expected: |
| $ 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++`` 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 |
| $ ./a.out |
| hello |
| |
| On the other hand, when using LLVMC as a linker to combine several C++ |
| object files you should provide the ``--linker`` option since it's |
| impossible for LLVMC to choose the right linker in that case:: |
| |
| $ llvmc -c hello.cpp |
| $ llvmc hello.o |
| [A lot of link-time errors skipped] |
| $ 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 ``clang`` compiler with the ``-clang`` option. |
| |
| |
| Predefined options |
| ================== |
| |
| LLVMC has some built-in options that can't be overridden in the |
| configuration libraries: |
| |
| * ``-o FILE`` - Output file name. |
| |
| * ``-x LANGUAGE`` - Specify the language of the following input files |
| until the next -x option. |
| |
| * ``-load PLUGIN_NAME`` - Load the specified plugin DLL. Example: |
| ``-load $LLVM_DIR/Release/lib/LLVMCSimple.so``. |
| |
| * ``-v`` - Enable verbose mode, i.e. print out all executed commands. |
| |
| * ``--save-temps`` - Write temporary files to the current directory and do not |
| delete them on exit. This option can also take an argument: the |
| ``--save-temps=obj`` switch will write files into the directory specified with |
| the ``-o`` option. The ``--save-temps=cwd`` and ``--save-temps`` switches are |
| both synonyms for the default behaviour. |
| |
| * ``--temp-dir DIRECTORY`` - Store temporary files in the given directory. This |
| directory is deleted on exit unless ``--save-temps`` is specified. If |
| ``--save-temps=obj`` is also specified, ``--temp-dir`` is given the |
| precedence. |
| |
| * ``--check-graph`` - Check the compilation for common errors like mismatched |
| output/input language names, multiple default edges and cycles. Because of |
| plugins, these checks can't be performed at compile-time. Exit with code zero |
| if no errors were found, and return the number of found errors |
| otherwise. Hidden option, useful for debugging LLVMC plugins. |
| |
| * ``--view-graph`` - Show a graphical representation of the compilation graph |
| and exit. Requires that you have ``dot`` and ``gv`` programs installed. Hidden |
| option, useful for debugging LLVMC plugins. |
| |
| * ``--write-graph`` - Write a ``compilation-graph.dot`` file in the current |
| directory with the compilation graph description in Graphviz format (identical |
| to the file used by the ``--view-graph`` option). The ``-o`` option can be |
| used to set the output file name. Hidden option, useful for debugging LLVMC |
| plugins. |
| |
| * ``--help``, ``--help-hidden``, ``--version`` - These options have |
| 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``:: |
| |
| $ cd $LLVMC_DIR/plugins |
| $ cp -r Simple MyPlugin |
| $ cd MyPlugin |
| $ ls |
| Makefile PluginMain.cpp Simple.td |
| |
| As you can see, our basic plugin consists of only two files (not |
| counting the build script). ``Simple.td`` contains TableGen |
| 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`__). |
| |
| __ hooks_ |
| |
| 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):: |
| |
| LLVMC_PLUGIN=MyPlugin |
| |
| It is also a good idea to rename ``Simple.td`` to something less |
| generic:: |
| |
| $ mv Simple.td MyPlugin.td |
| |
| To build your plugin as a dynamic library, just ``cd`` to its source |
| directory and run ``make``. The resulting file will be called |
| ``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/plugin_llvmc_Simple.so |
| |
| Compiling standalone LLVMC-based drivers |
| ======================================== |
| |
| 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 LLVMC_BUILTIN_PLUGINS="" |
| |
| |
| Customizing LLVMC: the compilation graph |
| ======================================== |
| |
| Each TableGen configuration file should include the common |
| definitions:: |
| |
| include "llvm/CompilerDriver/Common.td" |
| |
| Internally, LLVMC stores information about possible source |
| transformations in form of a graph. Nodes in this graph represent |
| tools, and edges between two nodes represent a transformation path. A |
| special "root" node is used to mark entry points for the |
| transformations. LLVMC also assigns a weight to each edge (more on |
| this later) to choose between several alternative edges. |
| |
| The definition of the compilation graph (see file |
| ``plugins/Base/Base.td`` for an example) is just a list of edges:: |
| |
| def CompilationGraph : CompilationGraph<[ |
| Edge<"root", "llvm_gcc_c">, |
| Edge<"root", "llvm_gcc_assembler">, |
| ... |
| |
| Edge<"llvm_gcc_c", "llc">, |
| Edge<"llvm_gcc_cpp", "llc">, |
| ... |
| |
| OptionalEdge<"llvm_gcc_c", "opt", (case (switch_on "opt"), |
| (inc_weight))>, |
| OptionalEdge<"llvm_gcc_cpp", "opt", (case (switch_on "opt"), |
| (inc_weight))>, |
| ... |
| |
| OptionalEdge<"llvm_gcc_assembler", "llvm_gcc_cpp_linker", |
| (case (input_languages_contain "c++"), (inc_weight), |
| (or (parameter_equals "linker", "g++"), |
| (parameter_equals "linker", "c++")), (inc_weight))>, |
| ... |
| |
| ]>; |
| |
| As you can see, the edges can be either default or optional, where |
| optional edges are differentiated by an additional ``case`` expression |
| used to calculate the weight of this edge. Notice also that we refer |
| to tools via their names (as strings). This makes it possible to add |
| edges to an existing compilation graph in plugins without having to |
| know about all tool definitions used in the graph. |
| |
| The default edges are assigned a weight of 1, and optional edges get a |
| weight of 0 + 2*N where N is the number of tests that evaluated to |
| true in the ``case`` expression. It is also possible to provide an |
| integer parameter to ``inc_weight`` and ``dec_weight`` - in this case, |
| the weight is increased (or decreased) by the provided value instead |
| of the default 2. It is also possible to change the default weight of |
| an optional edge by using the ``default`` clause of the ``case`` |
| construct. |
| |
| When passing an input file through the graph, LLVMC picks the edge |
| with the maximum weight. To avoid ambiguity, there should be only one |
| default edge between two nodes (with the exception of the root node, |
| which gets a special treatment - there you are allowed to specify one |
| default edge *per language*). |
| |
| When multiple plugins are loaded, their compilation graphs are merged |
| together. Since multiple edges that have the same end nodes are not |
| allowed (i.e. the graph is not a multigraph), an edge defined in |
| several plugins will be replaced by the definition from the plugin |
| that was loaded last. Plugin load order can be controlled by using the |
| plugin priority feature described above. |
| |
| To get a visual representation of the compilation graph (useful for |
| debugging), run ``llvmc --view-graph``. You will need ``dot`` and |
| ``gsview`` installed for this to work properly. |
| |
| Describing options |
| ================== |
| |
| Command-line options that the plugin supports are defined by using an |
| ``OptionList``:: |
| |
| def Options : OptionList<[ |
| (switch_option "E", (help "Help string")), |
| (alias_option "quiet", "q") |
| ... |
| ]>; |
| |
| As you can see, the option list is just a list of DAGs, where each DAG |
| is an option description consisting of the option name and some |
| properties. A plugin can define more than one option list (they are |
| all merged together in the end), which can be handy if one wants to |
| separate option groups syntactically. |
| |
| * Possible option types: |
| |
| - ``switch_option`` - a simple boolean switch without arguments, for example |
| ``-O2`` or ``-time``. At most one occurrence is allowed by default. |
| |
| - ``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")`` |
| |
| - ``switch_list_option`` - like ``switch_option`` with the ``zero_or_more`` |
| property, but remembers how many times the switch was turned on. Useful |
| mostly for forwarding. Example: when ``-foo`` is a switch option (with the |
| ``zero_or_more`` property), the command ``driver -foo -foo`` is forwarded |
| as ``some-tool -foo``, but when ``-foo`` is a switch list, the same command |
| is forwarded as ``some-tool -foo -foo``. |
| |
| |
| * Possible option properties: |
| |
| - ``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 ``optional`` and ``one_or_more``. |
| |
| - ``optional`` - the option can be specified either zero times or exactly |
| once. The default for switch options. Useful only for list options in |
| conjunction with ``multi_val``. Incompatible with ``required``, |
| ``zero_or_more`` and ``one_or_more``. |
| |
| - ``one_or_more`` - the option must be specified at least once. Can be useful |
| to allow switch options be both obligatory and be specified multiple |
| times. For list options is useful only in conjunction with ``multi_val``; |
| for ordinary it is synonymous with ``required``. Incompatible with |
| ``required``, ``optional`` and ``zero_or_more``. |
| |
| - ``zero_or_more`` - the option can be specified zero or more times. Useful |
| to allow a single switch option to be specified more than |
| once. Incompatible with ``required``, ``optional`` 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``, ``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; 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`__. |
| |
| __ extern_ |
| |
| .. _extern: |
| |
| 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 |
| ``extern``. This is what the ``extern`` option property is |
| for. Example:: |
| |
| ... |
| (switch_option "E", (extern)) |
| ... |
| |
| If an external option has additional attributes besides 'extern', they are |
| ignored. See also the section on plugin `priorities`__. |
| |
| __ priorities_ |
| |
| .. _case: |
| |
| 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' |
| expression is designed after the similarly-named construct in |
| functional languages and takes the form ``(case (test_1), statement_1, |
| (test_2), statement_2, ... (test_N), statement_N)``. The statements |
| are evaluated only if the corresponding tests evaluate to true. |
| |
| Examples:: |
| |
| // Edge weight calculation |
| |
| // Increases edge weight by 5 if "-A" is provided on the |
| // command-line, and by 5 more if "-B" is also provided. |
| (case |
| (switch_on "A"), (inc_weight 5), |
| (switch_on "B"), (inc_weight 5)) |
| |
| |
| // Tool command line specification |
| |
| // Evaluates to "cmdline1" if the option "-A" is provided on the |
| // command line; to "cmdline2" if "-B" is provided; |
| // otherwise to "cmdline3". |
| |
| (case |
| (switch_on "A"), "cmdline1", |
| (switch_on "B"), "cmdline2", |
| (default), "cmdline3") |
| |
| Note the slight difference in 'case' expression handling in contexts |
| of edge weights and command line specification - in the second example |
| the value of the ``"B"`` switch is never checked when switch ``"A"`` is |
| enabled, and the whole expression always evaluates to ``"cmdline1"`` in |
| that case. |
| |
| Case expressions can also be nested, i.e. the following is legal:: |
| |
| (case (switch_on "E"), (case (switch_on "o"), ..., (default), ...) |
| (default), ...) |
| |
| You should, however, try to avoid doing that because it hurts |
| readability. It is usually better to split tool descriptions and/or |
| use TableGen inheritance instead. |
| |
| * Possible tests are: |
| |
| - ``switch_on`` - Returns true if a given command-line switch is provided by |
| the user. Can be given a list as argument, in that case ``(switch_on ["foo", |
| "bar", "baz"])`` is equivalent to ``(and (switch_on "foo"), (switch_on |
| "bar"), (switch_on "baz"))``. |
| Example: ``(switch_on "opt")``. |
| |
| - ``any_switch_on`` - Given a list of switch options, returns true if any of |
| the switches is turned on. |
| Example: ``(any_switch_on ["foo", "bar", "baz"])`` is equivalent to ``(or |
| (switch_on "foo"), (switch_on "bar"), (switch_on "baz"))``. |
| |
| - ``parameter_equals`` - Returns true if a command-line parameter equals |
| a given value. |
| Example: ``(parameter_equals "W", "all")``. |
| |
| - ``element_in_list`` - Returns true if a command-line parameter |
| list contains a given value. |
| 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++")``. |
| |
| - ``in_language`` - Evaluates to true if the input file language is equal to |
| the argument. At the moment works only with ``cmd_line`` and ``actions`` (on |
| non-join nodes). |
| Example: ``(in_language "c++")``. |
| |
| - ``not_empty`` - Returns true if a given option (which should be either a |
| parameter or a parameter list) is set by the user. Like ``switch_on``, can |
| be also given a list as argument. |
| Example: ``(not_empty "o")``. |
| |
| - ``any_not_empty`` - Returns true if ``not_empty`` returns true for any of |
| the options in the list. |
| Example: ``(any_not_empty ["foo", "bar", "baz"])`` is equivalent to ``(or |
| (not_empty "foo"), (not_empty "bar"), (not_empty "baz"))``. |
| |
| - ``empty`` - The opposite of ``not_empty``. Equivalent to ``(not (not_empty |
| X))``. Provided for convenience. Can be given a list as argument. |
| |
| - ``any_not_empty`` - Returns true if ``not_empty`` returns true for any of |
| the options in the list. |
| Example: ``(any_empty ["foo", "bar", "baz"])`` is equivalent to ``(not (and |
| (not_empty "foo"), (not_empty "bar"), (not_empty "baz")))``. |
| |
| - ``single_input_file`` - Returns true if there was only one input file |
| provided on the command-line. Used without arguments: |
| ``(single_input_file)``. |
| |
| - ``multiple_input_files`` - Equivalent to ``(not (single_input_file))`` (the |
| case of zero input files is considered an error). |
| |
| - ``default`` - Always evaluates to true. Should always be the last |
| test in the ``case`` expression. |
| |
| - ``and`` - A standard binary logical combinator that returns true iff all of |
| its arguments return true. Used like this: ``(and (test1), (test2), |
| ... (testN))``. Nesting of ``and`` and ``or`` is allowed, but not |
| encouraged. |
| |
| - ``or`` - A binary logical combinator that returns true iff any of its |
| arguments returns true. Example: ``(or (test1), (test2), ... (testN))``. |
| |
| - ``not`` - Standard unary logical combinator that negates its |
| argument. Example: ``(not (or (test1), (test2), ... (testN)))``. |
| |
| |
| |
| 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):: |
| |
| def llvm_gcc_cpp : Tool<[ |
| (in_language "c++"), |
| (out_language "llvm-assembler"), |
| (output_suffix "bc"), |
| (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"), |
| (sink) |
| ]>; |
| |
| This defines a new tool called ``llvm_gcc_cpp``, which is an alias for |
| ``llvm-g++``. As you can see, a tool definition is just a list of |
| properties; most of them should be self-explanatory. The ``sink`` |
| property means that this tool should be passed all command-line |
| options that aren't mentioned in the option list. |
| |
| The complete list of all currently implemented tool properties follows. |
| |
| * Possible tool properties: |
| |
| - ``in_language`` - input language name. Can be either a string or a |
| list, in case the tool supports multiple input languages. |
| |
| - ``out_language`` - output language name. Multiple output languages are not |
| allowed. |
| |
| - ``output_suffix`` - output file suffix. Can also be changed |
| dynamically, see documentation on actions. |
| |
| - ``cmd_line`` - the actual command used to run the tool. You can |
| use ``$INFILE`` and ``$OUTFILE`` variables, output redirection |
| with ``>``, hook invocations (``$CALL``), environment variables |
| (via ``$ENV``) and the ``case`` construct. |
| |
| - ``join`` - this tool is a "join node" in the graph, i.e. it gets a |
| list of input files and joins them together. Used for linkers. |
| |
| - ``sink`` - all command-line options that are not handled by other |
| 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`__). |
| |
| __ actions_ |
| |
| .. _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:: |
| |
| def llvm_gcc_linker : Tool<[ |
| (in_language "object-code"), |
| (out_language "executable"), |
| (output_suffix "out"), |
| (cmd_line "llvm-gcc $INFILE -o $OUTFILE"), |
| (join), |
| (actions (case (not_empty "L"), (forward "L"), |
| (not_empty "l"), (forward "l"), |
| (not_empty "dummy"), |
| [(append_cmd "-dummy1"), (append_cmd "-dummy2")]) |
| ]>; |
| |
| The ``actions`` tool property is implemented on top of the omnipresent |
| ``case`` expression. It associates one or more different *actions* |
| with given conditions - in the example, the actions are ``forward``, |
| which forwards a given option unchanged, and ``append_cmd``, which |
| appends a given string to the tool execution command. Multiple actions |
| can be associated with a single condition by using a list of actions |
| (used in the example to append some dummy options). The same ``case`` |
| construct can also be used in the ``cmd_line`` property to modify the |
| tool command line. |
| |
| The "join" property used in the example means that this tool behaves |
| like a linker. |
| |
| The list of all possible actions follows. |
| |
| * Possible actions: |
| |
| - ``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. |
| Example: ``(warning "Specifying both -O1 and -O2 is meaningless!")``. |
| |
| - ``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")``. |
| |
| - ``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")``. |
| |
| __ hooks_ |
| |
| - ``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. |
| Example: ``(stop_compilation)``. |
| |
| |
| 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 |
| given input file set. Language map definition looks like this:: |
| |
| def LanguageMap : LanguageMap< |
| [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>, |
| LangToSuffixes<"c", ["c"]>, |
| ... |
| ]>; |
| |
| For example, without those definitions the following command wouldn't work:: |
| |
| $ llvmc hello.cpp |
| llvmc: Unknown suffix: cpp |
| |
| 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 |
| =================== |
| |
| 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 (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 ``-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 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 |
| ==================== |
| |
| .. _hooks: |
| |
| 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 |
| 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`__):: |
| |
| (cmd_line |
| (case |
| (switch_on "E"), |
| "llvm-g++ -E -x c $INFILE -o $OUTFILE", |
| (default), |
| "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm")) |
| |
| __ case_ |
| |
| .. _priorities: |
| |
| 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 |
| achieve this, the concept of plugin priority was introduced. By |
| default, every plugin has priority zero; to specify the priority |
| explicitly, put the following line in your plugin's TableGen file:: |
| |
| def Priority : PluginPriority<$PRIORITY_VALUE>; |
| # Where PRIORITY_VALUE is some integer > 0 |
| |
| Plugins are loaded in order of their (increasing) priority, starting |
| with 0. Therefore, the plugin with the highest priority value will be |
| loaded last. |
| |
| 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 |
| 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. |
| |
| .. _Graphviz: http://www.graphviz.org/ |
| .. _Ghostview: http://pages.cs.wisc.edu/~ghost/ |
| |
| 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:: |
| |
| 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 |
| the ``Base`` plugin behaves when it needs to choose the correct linker options |
| (think ``g++`` vs. ``gcc``). |
| |
| .. raw:: html |
| |
| <hr /> |
| <address> |
| <a href="http://jigsaw.w3.org/css-validator/check/referer"> |
| <img src="http://jigsaw.w3.org/css-validator/images/vcss-blue" |
| alt="Valid CSS" /></a> |
| <a href="http://validator.w3.org/check?uri=referer"> |
| <img src="http://www.w3.org/Icons/valid-xhtml10-blue" |
| alt="Valid XHTML 1.0 Transitional"/></a> |
| |
| <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br /> |
| <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br /> |
| |
| Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $ |
| </address> |