[llvm-commits] [llvm] r51736 - in /llvm/trunk/tools/llvmc2: Makefile doc/LLVMC-Reference.rst doc/LLVMC-Tutorial.rst examples/ examples/Clang.td examples/Simple.td
Mikhail Glushenkov
foldr at codedgers.com
Thu May 29 23:14:42 PDT 2008
Author: foldr
Date: Fri May 30 01:14:42 2008
New Revision: 51736
URL: http://llvm.org/viewvc/llvm-project?rev=51736&view=rev
Log:
Update documentation, add examples.
Added:
llvm/trunk/tools/llvmc2/doc/LLVMC-Tutorial.rst
llvm/trunk/tools/llvmc2/examples/
llvm/trunk/tools/llvmc2/examples/Clang.td
llvm/trunk/tools/llvmc2/examples/Simple.td
Modified:
llvm/trunk/tools/llvmc2/Makefile
llvm/trunk/tools/llvmc2/doc/LLVMC-Reference.rst
Modified: llvm/trunk/tools/llvmc2/Makefile
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/tools/llvmc2/Makefile?rev=51736&r1=51735&r2=51736&view=diff
==============================================================================
--- llvm/trunk/tools/llvmc2/Makefile (original)
+++ llvm/trunk/tools/llvmc2/Makefile Fri May 30 01:14:42 2008
@@ -15,8 +15,9 @@
include $(LEVEL)/Makefile.common
GRAPH=Graph.td
-TOOLS=Tools.td
-TOOLS_SOURCE=$(GRAPH) $(TOOLS) Common.td
+$(GRAPH) : Common.td
+Graph.td : Tools.td
+TOOLS_SOURCE=$(GRAPH)
# TOFIX: integrate this part into Makefile.rules?
# The degree of horrorshowness in that file is too much for me atm.
Modified: llvm/trunk/tools/llvmc2/doc/LLVMC-Reference.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/tools/llvmc2/doc/LLVMC-Reference.rst?rev=51736&r1=51735&r2=51736&view=diff
==============================================================================
--- llvm/trunk/tools/llvmc2/doc/LLVMC-Reference.rst (original)
+++ llvm/trunk/tools/llvmc2/doc/LLVMC-Reference.rst Fri May 30 01:14:42 2008
@@ -1,5 +1,5 @@
-Tutorial - Writing LLVMC Configuration files
-=============================================
+Customizing LLVMC: Reference Manual
+===================================
LLVMC is a generic compiler driver, designed to be customizable and
extensible. It plays the same role for LLVM as the ``gcc`` program
@@ -10,8 +10,7 @@
specifics of transformation (even the command-line options are mostly
not hard-coded) and regards the transformation structure as an
abstract graph. This makes it possible to adapt LLVMC for other
-purposes - for example, as a build tool for game resources. This
-tutorial describes the basic usage and configuration of LLVMC.
+purposes - for example, as a build tool for game resources.
Because LLVMC employs TableGen [1]_ as its configuration language, you
need to be familiar with it to customize LLVMC.
@@ -19,19 +18,21 @@
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::
+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:
$ llvmc2 -O3 -Wall hello.cpp
$ ./a.out
hello
-One nice feature of LLVMC is that you don't have to distinguish
+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 extension). If
-you want to force files ending with ".c" compile as C++, use the
-``-x`` option, just like you would do it with ``gcc``::
+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``::
$ llvmc2 -x c hello.cpp
$ # hello.cpp is really a C file
@@ -49,25 +50,36 @@
$ ./a.out
hello
-For further help on command-line LLVMC usage, refer to the ``llvmc
---help`` output.
Customizing LLVMC: the compilation graph
----------------------------------------
At the time of writing LLVMC does not support on-the-fly reloading of
-configuration, so to customize LLVMC you'll have to edit and recompile
-the source code (which lives under ``$LLVM_DIR/tools/llvmc2``). The
-relevant files are ``Common.td``, ``Tools.td`` and ``Example.td``.
-
-Internally, LLVMC stores information about possible 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 represents entry points for the transformations. LLVMC also
-assigns a weight to each edge (more on that below) to choose between
-several alternative edges.
+configuration, so to customize LLVMC you'll have to recompile the
+source code (which lives under ``$LLVM_DIR/tools/llvmc2``). The
+default configuration files are ``Common.td`` (contains common
+definitions, don't forget to ``include`` it in your configuration
+files), ``Tools.td`` (tool descriptions) and ``Graph.td`` (compilation
+graph definition).
+
+To compile LLVMC with your own configuration file (say,``MyGraph.td``),
+run ``make`` like this::
+
+ $ cd $LLVM_DIR/tools/llvmc2
+ $ make GRAPH=MyGraph.td TOOLNAME=my_llvmc
+
+This will build an executable named ``my_llvmc``. There are also
+several sample configuration files in the ``llvmc2/examples``
+subdirectory that should help to get you started.
+
+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 ``Example.td``) is
+The definition of the compilation graph (see file ``Graph.td``) is
just a list of edges::
def CompilationGraph : CompilationGraph<[
@@ -84,25 +96,46 @@
...
OptionalEdge<llvm_gcc_assembler, llvm_gcc_cpp_linker,
- [(if_input_languages_contain "c++"),
- (or (parameter_equals "linker", "g++"),
- (parameter_equals "linker", "c++"))]>,
+ (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 sporting a list of patterns (or
-edge properties) which are used to calculate the edge's weight. 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 succesful edge property
-matches. 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*).
+optional edges are differentiated by sporting a ``case`` expression
+used to calculate the edge's weight.
-* Possible edge properties are:
+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.
+
+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*).
+
+To get a visual representation of the compilation graph (useful for
+debugging), run ``llvmc2 --view-graph``. You will need ``dot`` and
+``gsview`` installed for this to work properly.
+
+
+The 'case' construct
+--------------------
+
+The 'case' construct can be used to calculate weights for optional
+edges and to choose between several alternative command line strings
+in the ``cmd_line`` tool property. It 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)``.
+
+* Possible tests are:
- ``switch_on`` - Returns true if a given command-line option is
provided by the user. Example: ``(switch_on "opt")``. Note that
@@ -116,35 +149,28 @@
- ``element_in_list`` - Returns true if a command-line parameter list
includes a given value. Example: ``(parameter_in_list "l", "pthread")``.
- - ``if_input_languages_contain`` - Returns true if a given input
- language belongs to the current input language set.
-
- - ``and`` - Edge property combinator. Returns true if all of its
- arguments return true. Used like this: ``(and (prop1), (prop2),
- ... (propN))``. Nesting is allowed, but not encouraged.
-
- - ``or`` - Edge property combinator that returns true if any one of its
- arguments returns true. Example: ``(or (prop1), (prop2), ... (propN))``.
-
- - ``weight`` - Makes it possible to explicitly specify the quantity
- added to the edge weight if this edge property matches. Used like
- this: ``(weight N, (prop))``. The inner property can include
- ``and`` and ``or`` combinators. When N is equal to 2, equivalent
- to ``(prop)``.
-
- Example: ``(weight 8, (and (switch_on "a"), (switch_on "b")))``.
-
-
-To get a visual representation of the compilation graph (useful for
-debugging), run ``llvmc2 --view-graph``. You will need ``dot`` and
-``gsview`` installed for this to work properly.
+ - ``input_languages_contain`` - Returns true if a given language
+ belongs to the current input language set. Example:
+ ```(input_languages_contain "c++")``.
+
+ - ``default`` - Always evaluates to true. Should be used
+
+ - ``and`` - A standard 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`` - Another logical combinator that returns true only if any
+ one of its arguments returns true. Example: ``(or (test1),
+ (test2), ... (testN))``.
Writing a tool description
--------------------------
-As was said earlier, nodes in the compilation graph represent tools. A
-tool definition looks like this (taken from the ``Tools.td`` file)::
+As was said earlier, nodes in the compilation graph represent tools,
+which are described separately. A tool definition looks like this
+(taken from the ``Tools.td`` file)::
def llvm_gcc_cpp : Tool<[
(in_language "c++"),
@@ -156,9 +182,9 @@
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-evident. The ``sink`` property
-means that this tool should be passed all command-line options that
-aren't handled by the other tools.
+properties; most of them should be self-explanatory. The ``sink``
+property means that this tool should be passed all command-line
+options that lack explicit descriptions.
The complete list of the currently implemented tool properties follows:
@@ -170,9 +196,10 @@
- ``output_suffix`` - output file suffix.
- - ``cmd_line`` - the actual command used to run the tool. You can use
- ``$INFILE`` and ``$OUTFILE`` variables, as well as output
- redirection with ``>``.
+ - ``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 (more on this below).
- ``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.
@@ -188,14 +215,16 @@
(output_suffix "out"),
(cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
(join),
- (prefix_list_option "L", (forward), (help "add a directory to link path")),
- (prefix_list_option "l", (forward), (help "search a library when linking")),
- (prefix_list_option "Wl", (unpack_values), (help "pass options to linker"))
+ (prefix_list_option "L", (forward),
+ (help "add a directory to link path")),
+ (prefix_list_option "l", (forward),
+ (help "search a library when linking")),
+ (prefix_list_option "Wl", (unpack_values),
+ (help "pass options to linker"))
]>;
This tool has a "join" property, which means that it behaves like a
-linker (because of that this tool should be the last in the
-toolchain). This tool also defines several command-line options: ``-l``,
+linker. This tool also defines several command-line options: ``-l``,
``-L`` and ``-Wl`` which have their usual meaning. An option has two
attributes: a name and a (possibly empty) list of properties. All
currently implemented option types and properties are described below:
@@ -223,6 +252,9 @@
- ``forward`` - forward this option unchanged.
+ - ``output_suffix`` - modify the output suffix of this
+ tool. Example : ``(switch "E", (output_suffix "i")``.
+
- ``stop_compilation`` - stop compilation after this phase.
- ``unpack_values`` - used for for splitting and forwarding
@@ -230,19 +262,48 @@
converted to ``-foo=bar -baz`` and appended to the tool invocation
command.
- - ``help`` - help string associated with this option.
+ - ``help`` - help string associated with this option. Used for
+ ``--help`` output.
- ``required`` - this option is obligatory.
+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 names
+in the configuration file. This can be achieved via the mechanism of
+hooks - to compile LLVMC with your hooks, just drop a .cpp file into
+``tools/llvmc2`` directory. Hooks should live in the ``hooks``
+namespace and have the signature ``std::string hooks::MyHookName
+(void)``. They can be used from the ``cmd_line`` tool property::
+
+ (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)")
+
+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 (which we have already seen before)::
+
+ (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"))
+
+
Language map
------------
-One last thing that you need to modify when adding support for a new
-language to LLVMC is the language map, which defines mappings from
+One last thing that you will need to modify when adding support for a
+new language to LLVMC is the language map, which defines mappings from
file extensions to language names. It is used to choose the proper
-toolchain based on the input. Language map definition is located in
-the file ``Tools.td`` and looks like this::
+toolchain(s) for a given input file set. Language map definition is
+located in the file ``Tools.td`` and looks like this::
def LanguageMap : LanguageMap<
[LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
Added: llvm/trunk/tools/llvmc2/doc/LLVMC-Tutorial.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/tools/llvmc2/doc/LLVMC-Tutorial.rst?rev=51736&view=auto
==============================================================================
--- llvm/trunk/tools/llvmc2/doc/LLVMC-Tutorial.rst (added)
+++ llvm/trunk/tools/llvmc2/doc/LLVMC-Tutorial.rst Fri May 30 01:14:42 2008
@@ -0,0 +1,87 @@
+Tutorial - Using LLVMC
+======================
+
+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. This
+tutorial describes the basic usage and configuration of 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::
+
+ $ llvmc2 -O3 -Wall hello.cpp
+ $ ./a.out
+ hello
+
+For further help on command-line LLVMC usage, refer to the ``llvmc
+--help`` output.
+
+Using LLVMC to generate toolchain drivers
+-----------------------------------------
+
+At the time of writing LLVMC does not support on-the-fly reloading of
+configuration, so it will be necessary to recompile its source
+code. LLVMC uses TableGen [1]_ as its configuration language, so
+you'll need to familiar with it.
+
+Start by compiling ``examples/Simple.td``, which is a simple wrapper
+for ``gcc``::
+
+ $ cd $LLVM_DIR/tools/llvmc2
+ $ make TOOLNAME=mygcc GRAPH=examples/Simple.td
+ $ edit hello.c
+ $ mygcc hello.c
+ $ ./hello.out
+ Hello
+
+Contents of the file ``Simple.td`` look like this::
+
+ // Include common definitions
+ include "Common.td"
+
+ // Tool descriptions
+ def gcc : Tool<
+ [(in_language "c"),
+ (out_language "executable"),
+ (output_suffix "out"),
+ (cmd_line "gcc $INFILE -o $OUTFILE"),
+ (sink)
+ ]>;
+
+ // Language map
+ def LanguageMap : LanguageMap<[LangToSuffixes<"c", ["c"]>]>;
+
+ // Compilation graph
+ def CompilationGraph : CompilationGraph<[Edge<root, gcc>]>;
+
+As you can see, this file consists of three parts: tool descriptions,
+language map, and the compilation graph definition.
+
+At the heart of LLVMC is the idea of a transformation graph: vertices
+in this graph are tools, and edges signify that there is a
+transformation path between two tools (for example, assembly source
+produced by the compiler can be transformed into executable code by an
+assembler). A special node named ``root`` is used to mark graph entry
+points.
+
+Tool descriptions are basically lists of properties: most properties
+in the example above should be self-explanatory; the ``sink`` property
+means that all options lacking an explicit description should be
+forwarded to this tool.
+
+``LanguageMap`` associates a language name with a list of suffixes and
+is used for deciding which toolchain corresponds to a given input
+file.
+
+To learn more about LLVMC customization, refer to the reference
+manual and sample configuration files in the ``examples`` directory.
+
+References
+==========
+
+.. [1] TableGen Fundamentals
+ http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html
+
Added: llvm/trunk/tools/llvmc2/examples/Clang.td
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/tools/llvmc2/examples/Clang.td?rev=51736&view=auto
==============================================================================
(empty)
Added: llvm/trunk/tools/llvmc2/examples/Simple.td
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/tools/llvmc2/examples/Simple.td?rev=51736&view=auto
==============================================================================
--- llvm/trunk/tools/llvmc2/examples/Simple.td (added)
+++ llvm/trunk/tools/llvmc2/examples/Simple.td Fri May 30 01:14:42 2008
@@ -0,0 +1,15 @@
+// A simple wrapper for gcc.
+
+include "Common.td"
+
+def gcc : Tool<
+[(in_language "c"),
+ (out_language "executable"),
+ (output_suffix "out"),
+ (cmd_line "gcc $INFILE -o $OUTFILE"),
+ (sink)
+]>;
+
+def LanguageMap : LanguageMap<[LangToSuffixes<"c", ["c"]>]>;
+
+def CompilationGraph : CompilationGraph<[Edge<root, gcc>]>;
More information about the llvm-commits
mailing list