diff --git a/tools/llvmc2/doc/LLVMC-Reference.rst b/tools/llvmc2/doc/LLVMC-Reference.rst index 18ebf0d5f50..b0f88fc7ab6 100644 --- a/tools/llvmc2/doc/LLVMC-Reference.rst +++ b/tools/llvmc2/doc/LLVMC-Reference.rst @@ -1,3 +1,4 @@ +=================================== Customizing LLVMC: Reference Manual =================================== @@ -15,8 +16,12 @@ 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. + +.. contents:: + + 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, @@ -50,9 +55,30 @@ impossible for LLVMC to choose the right linker in that case:: $ ./a.out hello +Predefined options +================== + +LLVMC has some built-in options that can't be overridden in the +configuration files: + +* ``-o FILE`` - Output file name. + +* ``-x LANGUAGE`` - Specify the language of the following input files + until the next -x option. + +* ``-v`` - Enable verbose mode, i.e. print out all executed commands. + +* ``--view-graph`` - Show a graphical representation of the compilation + graph. Requires that you have ``dot`` and ``gv`` commands + installed. Hidden option, useful for debugging. + +* ``--write-graph`` - Write a ``compilation-graph.dot`` file in the + current directory with the compilation graph description in the + Graphviz format. Hidden option, useful for debugging. + 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 recompile the @@ -125,65 +151,8 @@ debugging), run ``llvmc2 --view-graph``. You will need ``dot`` and ``gsview`` installed for this to work properly. -The 'case' expression ---------------------- - -The 'case' construct can be used to calculate weights of the 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)``. The statements are evaluated only if the corresponding -tests evaluate to true. - -Examples:: - - // 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)) - - // Evaluates to "cmdline1" if option "-A" is provided on the - // command line, otherwise to "cmdline2" - (case - (switch_on "A"), ("cmdline1"), - (default), ("cmdline2")) - - -* Possible tests 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")``. - - - ``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 always be the last - test in the ``case`` expression. - - - ``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, which are described separately. A tool definition looks like this @@ -285,8 +254,8 @@ currently implemented option types and properties are described below: - ``required`` - this option is obligatory. -Hooks and environment variables -------------------------------- +Using hooks and environment variables in the ``cmd_line`` property +================================================================== Normally, LLVMC executes programs from the system ``PATH``. Sometimes, this is not sufficient: for example, we may want to specify tool names @@ -303,7 +272,7 @@ 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):: +the ``case`` expression (documented below):: (cmd_line (case @@ -312,9 +281,89 @@ the ``case`` expression (which we have already seen before):: (default), "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm")) +Conditional evaluation: the ``case`` expression +=============================================== + +The 'case' construct can be used to calculate weights of the 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)``. The statements are evaluated only if the corresponding +tests evaluate to true. + +Examples:: + + // 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)) + + // Evaluates to "cmdline1" if option "-A" is provided on the + // command line, otherwise to "cmdline2" + (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 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")``. + + - ``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 language of the input + file equals to the argument. Valid only when using ``case`` + expression in a ``cmd_line`` tool property. 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. Example: ```(not_empty "o")``. + + - ``default`` - Always evaluates to true. Should always be the last + test in the ``case`` expression. + + - ``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))``. + Language map ------------- +============ 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 diff --git a/tools/llvmc2/doc/LLVMC-Tutorial.rst b/tools/llvmc2/doc/LLVMC-Tutorial.rst index eed6a5efb78..29c81443c9b 100644 --- a/tools/llvmc2/doc/LLVMC-Tutorial.rst +++ b/tools/llvmc2/doc/LLVMC-Tutorial.rst @@ -1,3 +1,4 @@ +====================== Tutorial - Using LLVMC ====================== @@ -6,8 +7,12 @@ 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. + +.. contents:: + + 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:: @@ -20,7 +25,7 @@ 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