# Tutorial - Using LLVMC

Contents

- Introduction
- Using the `llvmc` program
- Using LLVMC to generate toolchain drivers

Written by Mikhail Glushenkov

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

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.