1 files changed, 129 insertions, 0 deletions
diff --git a/contrib/llvm/tools/llvmc/doc/LLVMC-Tutorial.rst b/contrib/llvm/tools/llvmc/doc/LLVMC-Tutorial.rst
new file mode 100644
index 0000000..e7e8f08
--- /dev/null
+++ b/contrib/llvm/tools/llvmc/doc/LLVMC-Tutorial.rst
@@ -0,0 +1,129 @@
+======================
+Tutorial - Using LLVMC
+======================
+..
+   This file was automatically generated by rst2html.
+   Please do not edit directly!
+   The ReST source lives in the directory 'tools/llvmc/doc'.
+
+.. contents::
+
+.. raw:: html
+
+   <div class="doc_author">
+   <p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p>
+   </div>
+
+Introduction
+============
+
+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. Most of
+LLVMC functionality is implemented via plugins, which can be loaded
+dynamically or compiled in. 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::
+
+     $ llvmc -O3 -Wall hello.cpp
+     $ ./a.out
+     hello
+
+This will invoke ``llvm-g++`` under the hood (you can see which
+commands are executed by using the ``-v`` option). For further help on
+command-line LLVMC usage, refer to the ``llvmc --help`` output.
+
+
+Using LLVMC to generate toolchain drivers
+=========================================
+
+LLVMC plugins are written mostly using TableGen_, so you need to
+be familiar with it to get anything done.
+
+.. _TableGen: http://llvm.org/docs/TableGenFundamentals.html
+
+Start by compiling ``example/Simple``, which is a primitive wrapper for
+``gcc``::
+
+    $ cd $LLVM_DIR/tools/llvmc
+    $ cp -r example/Simple plugins/Simple
+
+      # NB: A less verbose way to compile standalone LLVMC-based drivers is
+      # described in the reference manual.
+
+    $ make LLVMC_BASED_DRIVER_NAME=mygcc LLVMC_BUILTIN_PLUGINS=Simple
+    $ cat > hello.c
+    [...]
+    $ mygcc hello.c
+    $ ./hello.out
+    Hello
+
+Here we link our plugin with the LLVMC core statically to form an executable
+file called ``mygcc``. It is also possible to build our plugin as a dynamic
+library to be loaded by the ``llvmc`` executable (or any other LLVMC-based
+standalone driver); this is described in the reference manual.
+
+Contents of the file ``Simple.td`` look like this::
+
+    // Include common definitions
+    include "llvm/CompilerDriver/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 compilation graph: vertices in
+this graph are tools, and edges represent a transformation path
+between two tools (for example, assembly source produced by the
+compiler can be transformed into executable code by an assembler). The
+compilation graph is basically a list of edges; a special node named
+``root`` is used to mark graph entry points.
+
+Tool descriptions are represented as property lists: 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.
+
+The ``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 plugin source code in the ``plugins`` directory.
+
+.. raw:: html
+
+   <hr />
+   <address>
+   <a href="http://jigsaw.w3.org/css-validator/check/referer">
+   <img src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
+      alt="Valid CSS" /></a>
+   <a href="http://validator.w3.org/check?uri=referer">
+   <img src="http://www.w3.org/Icons/valid-xhtml10-blue"
+      alt="Valid XHTML 1.0 Transitional"/></a>
+
+   <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
+   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
+
+   Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
+   </address>