From: Mikhail Glushenkov Date: Fri, 30 May 2008 06:14:01 +0000 (+0000) Subject: Rename LLVMC-Tutorial.rst to LLVMC-Reference.rst X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=1e4bab2c02a4c926df59f1485ce51e5b38c033b5;p=oota-llvm.git Rename LLVMC-Tutorial.rst to LLVMC-Reference.rst git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@51735 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/tools/llvmc2/doc/LLVMC-Reference.rst b/tools/llvmc2/doc/LLVMC-Reference.rst new file mode 100644 index 00000000000..b8a364f606c --- /dev/null +++ b/tools/llvmc2/doc/LLVMC-Reference.rst @@ -0,0 +1,258 @@ +Tutorial - Writing LLVMC Configuration files +============================================= + +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. 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. + +Because LLVMC employs TableGen [1]_ as its configuration language, you +need to be familiar with it to customize 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 + +One nice feature of LLVMC is that you don'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``:: + + $ llvmc2 -x c hello.cpp + $ # hello.cpp is really a C file + $ ./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:: + + $ llvmc2 -c hello.cpp + $ llvmc2 hello.o + [A lot of link-time errors skipped] + $ llvmc2 --linker=c++ hello.o + $ ./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. + +The definition of the compilation graph (see file ``Example.td``) is +just a list of edges:: + + def CompilationGraph : CompilationGraph<[ + Edge, + Edge, + ... + + Edge, + Edge, + ... + + OptionalEdge, + OptionalEdge, + ... + + OptionalEdge, + ... + + ]>; + +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*). + +* Possible edge properties are: + + - ``switch_on`` - Returns true if a given command-line option is + provided by the user. Example: ``(switch_on "opt")``. Note that + you have to define all possible command-line options separately in + the tool descriptions. See the next section for the discussion of + different kinds of command-line options. + + - ``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 + 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. + + +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):: + + 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-evident. The ``sink`` property +means that this tool should be passed all command-line options that +aren't handled by the other tools. + +The complete list of the currently implemented tool properties follows: + +* Possible tool properties: + + - ``in_language`` - input language name. + + - ``out_language`` - output language name. + + - ``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 ``>``. + + - ``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. + +The next tool definition is slightly more complex:: + + def llvm_gcc_linker : Tool<[ + (in_language "object-code"), + (out_language "executable"), + (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")) + ]>; + +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``, +``-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: + +* Possible option types: + + - ``switch_option`` - a simple boolean switch, for example ``-time``. + + - ``parameter_option`` - option that takes an argument, for example + ``-std=c99``; + + - ``parameter_list_option`` - same as the above, but more than one + occurence of the option is allowed. + + - ``prefix_option`` - same as the parameter_option, but the option name + and parameter value are not separated. + + - ``prefix_list_option`` - same as the above, but more than one + occurence of the option is allowed; example: ``-lm -lpthread``. + + +* Possible option properties: + + - ``append_cmd`` - append a string to the tool invocation command. + + - ``forward`` - forward this option unchanged. + + - ``stop_compilation`` - stop compilation after this phase. + + - ``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. + + - ``help`` - help string associated with this option. + + - ``required`` - this option is obligatory. + + +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 +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:: + + def LanguageMap : LanguageMap< + [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>, + LangToSuffixes<"c", ["c"]>, + ... + ]>; + + +References +========== + +.. [1] TableGen Fundamentals + http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html diff --git a/tools/llvmc2/doc/LLVMC-Tutorial.rst b/tools/llvmc2/doc/LLVMC-Tutorial.rst deleted file mode 100644 index b8a364f606c..00000000000 --- a/tools/llvmc2/doc/LLVMC-Tutorial.rst +++ /dev/null @@ -1,258 +0,0 @@ -Tutorial - Writing LLVMC Configuration files -============================================= - -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. 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. - -Because LLVMC employs TableGen [1]_ as its configuration language, you -need to be familiar with it to customize 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 - -One nice feature of LLVMC is that you don'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``:: - - $ llvmc2 -x c hello.cpp - $ # hello.cpp is really a C file - $ ./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:: - - $ llvmc2 -c hello.cpp - $ llvmc2 hello.o - [A lot of link-time errors skipped] - $ llvmc2 --linker=c++ hello.o - $ ./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. - -The definition of the compilation graph (see file ``Example.td``) is -just a list of edges:: - - def CompilationGraph : CompilationGraph<[ - Edge, - Edge, - ... - - Edge, - Edge, - ... - - OptionalEdge, - OptionalEdge, - ... - - OptionalEdge, - ... - - ]>; - -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*). - -* Possible edge properties are: - - - ``switch_on`` - Returns true if a given command-line option is - provided by the user. Example: ``(switch_on "opt")``. Note that - you have to define all possible command-line options separately in - the tool descriptions. See the next section for the discussion of - different kinds of command-line options. - - - ``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 - 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. - - -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):: - - 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-evident. The ``sink`` property -means that this tool should be passed all command-line options that -aren't handled by the other tools. - -The complete list of the currently implemented tool properties follows: - -* Possible tool properties: - - - ``in_language`` - input language name. - - - ``out_language`` - output language name. - - - ``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 ``>``. - - - ``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. - -The next tool definition is slightly more complex:: - - def llvm_gcc_linker : Tool<[ - (in_language "object-code"), - (out_language "executable"), - (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")) - ]>; - -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``, -``-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: - -* Possible option types: - - - ``switch_option`` - a simple boolean switch, for example ``-time``. - - - ``parameter_option`` - option that takes an argument, for example - ``-std=c99``; - - - ``parameter_list_option`` - same as the above, but more than one - occurence of the option is allowed. - - - ``prefix_option`` - same as the parameter_option, but the option name - and parameter value are not separated. - - - ``prefix_list_option`` - same as the above, but more than one - occurence of the option is allowed; example: ``-lm -lpthread``. - - -* Possible option properties: - - - ``append_cmd`` - append a string to the tool invocation command. - - - ``forward`` - forward this option unchanged. - - - ``stop_compilation`` - stop compilation after this phase. - - - ``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. - - - ``help`` - help string associated with this option. - - - ``required`` - this option is obligatory. - - -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 -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:: - - def LanguageMap : LanguageMap< - [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>, - LangToSuffixes<"c", ["c"]>, - ... - ]>; - - -References -========== - -.. [1] TableGen Fundamentals - http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html