tools/llvmc/doc/LLVMC-Tutorial.rst

======================
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 high-level TableGen code, from which a corresponding C++ source
file is automatically generated. This tutorial describes the basic usage and
configuration of LLVMC.


Using the ``llvmc`` program
===========================

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-based drivers 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_OBJ_DIR/tools/examples/Simple
    $ make
    $ cat > hello.c
    #include <stdio.h>
    int main() { printf("Hello\n"); }
    $ $LLVM_BIN_DIR/Simple -v hello.c
    gcc hello.c -o hello.out
    $ ./hello.out
    Hello

We have thus produced a simple driver called, appropriately, ``Simple``, from
the input TableGen file ``Simple.td``. The ``llvmc`` program itself is generated
using a similar process (see ``llvmc/src``). 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"),
     (command "gcc"),
     (sink),

     // -o is what is used by default, out_file_option here is included for
     // instructive purposes.
     (out_file_option "-o")
    ]>;

    // Language map
    def LanguageMap : LanguageMap<[(lang_to_suffixes "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 writing your own drivers with LLVMC, refer to the reference
manual and examples in the ``examples`` directory. Of a particular interest is
the ``Skeleton`` example, which can serve as a template for your LLVMC-based
drivers.

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