From 4d9c9e9d31408d9c7756ac241588862ffbe309ea Mon Sep 17 00:00:00 2001 From: Mikhail Glushenkov Date: Wed, 26 Mar 2008 21:37:43 +0000 Subject: Another test commit (with git-svn) git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@48843 91177308-0d34-0410-b5e6-96231b3b80d8 --- tools/llvmc2/doc/LLVMC-Enhancements.rst | 4 + tools/llvmc2/doc/LLVMC-Tutorial.rst | 153 ++++++++++++++++++++++++++++++++ tools/llvmc2/doc/LLVMCC-Tutorial.rst | 153 -------------------------------- 3 files changed, 157 insertions(+), 153 deletions(-) create mode 100644 tools/llvmc2/doc/LLVMC-Tutorial.rst delete mode 100644 tools/llvmc2/doc/LLVMCC-Tutorial.rst (limited to 'tools/llvmc2') diff --git a/tools/llvmc2/doc/LLVMC-Enhancements.rst b/tools/llvmc2/doc/LLVMC-Enhancements.rst index 2b77816005..671c993b89 100644 --- a/tools/llvmc2/doc/LLVMC-Enhancements.rst +++ b/tools/llvmc2/doc/LLVMC-Enhancements.rst @@ -1,6 +1,10 @@ Introduction ============ +Disclaimer: this document is currently somewhat out-of-date and is +retained for reference; for documentation, refer to +LLVMC-Tutorial.rst. + A complete rewrite of the LLVMC compiler driver is proposed, aimed at making it more configurable and useful. diff --git a/tools/llvmc2/doc/LLVMC-Tutorial.rst b/tools/llvmc2/doc/LLVMC-Tutorial.rst new file mode 100644 index 0000000000..9f66e74313 --- /dev/null +++ b/tools/llvmc2/doc/LLVMC-Tutorial.rst @@ -0,0 +1,153 @@ +Tutorial - Writing LLVMCC Configuration files +============================================= + +LLVMCC is a generic compiler driver (just like ``gcc``), designed to be +customizable and extensible. Its job is essentially to transform a set +of input files into a set of targets, depending on configuration rules +and user options. This tutorial describes how one can write +configuration files for ``llvmcc``. + +Because LLVMCC uses TableGen [1]_ as the language of its configuration +files, you need to be familiar with it. + +Describing a toolchain +---------------------- + +The main concept that ``llvmcc`` operates with is a *toolchain*, which +is just a list of tools that process input files in a pipeline-like +fashion. Toolchain definitions look like this:: + + def ToolChains : ToolChains<[ + ToolChain<[llvm_gcc_c, llc, llvm_gcc_assembler, llvm_gcc_linker]>, + ToolChain<[llvm_gcc_cpp, llc, llvm_gcc_assembler, llvm_gcc_linker]>, + ... + ]>; + +Every configuration file should have a single toolchains list called +``ToolChains``. + +At the time of writing, ``llvmcc`` does not support mixing various +toolchains together - in other words, all input files should be in the +same language. + +Another temporary limitation is that every toolchain should end with a +"join" node - a linker-like program that combines its inputs into a +single output file. + +Describing a tool +----------------- + +A single element of a toolchain is a tool. 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. + + - 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 bit that you probably should change is the language map, +which defines mappings between language names and file extensions. It +is used internally to choose the proper toolchain based on the names +of the input files. 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"]>, + ... + ]>; + + +Putting it all together +----------------------- + +Since at the time of writing LLVMCC does not support on-the-fly +reloading of the configuration, the only way to test your changes is +to recompile the program. To do this, ``cd`` to the source code +directory and run ``make``. + +References +========== + +.. [1] TableGen Fundamentals + http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html diff --git a/tools/llvmc2/doc/LLVMCC-Tutorial.rst b/tools/llvmc2/doc/LLVMCC-Tutorial.rst deleted file mode 100644 index 9f66e74313..0000000000 --- a/tools/llvmc2/doc/LLVMCC-Tutorial.rst +++ /dev/null @@ -1,153 +0,0 @@ -Tutorial - Writing LLVMCC Configuration files -============================================= - -LLVMCC is a generic compiler driver (just like ``gcc``), designed to be -customizable and extensible. Its job is essentially to transform a set -of input files into a set of targets, depending on configuration rules -and user options. This tutorial describes how one can write -configuration files for ``llvmcc``. - -Because LLVMCC uses TableGen [1]_ as the language of its configuration -files, you need to be familiar with it. - -Describing a toolchain ----------------------- - -The main concept that ``llvmcc`` operates with is a *toolchain*, which -is just a list of tools that process input files in a pipeline-like -fashion. Toolchain definitions look like this:: - - def ToolChains : ToolChains<[ - ToolChain<[llvm_gcc_c, llc, llvm_gcc_assembler, llvm_gcc_linker]>, - ToolChain<[llvm_gcc_cpp, llc, llvm_gcc_assembler, llvm_gcc_linker]>, - ... - ]>; - -Every configuration file should have a single toolchains list called -``ToolChains``. - -At the time of writing, ``llvmcc`` does not support mixing various -toolchains together - in other words, all input files should be in the -same language. - -Another temporary limitation is that every toolchain should end with a -"join" node - a linker-like program that combines its inputs into a -single output file. - -Describing a tool ------------------ - -A single element of a toolchain is a tool. 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. - - - 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 bit that you probably should change is the language map, -which defines mappings between language names and file extensions. It -is used internally to choose the proper toolchain based on the names -of the input files. 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"]>, - ... - ]>; - - -Putting it all together ------------------------ - -Since at the time of writing LLVMCC does not support on-the-fly -reloading of the configuration, the only way to test your changes is -to recompile the program. To do this, ``cd`` to the source code -directory and run ``make``. - -References -========== - -.. [1] TableGen Fundamentals - http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html -- cgit v1.2.3