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.
--- /dev/null
+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
+++ /dev/null
-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
projects / oota-llvm.git / commitdiff