| ====================== |
| 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> |