Tutorial - Using LLVMC

- - -

Contents

Introduction
Compiling with LLVMC
Using LLVMC to generate toolchain drivers

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.

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.

- -

- -

- -Mikhail Glushenkov
-LLVM Compiler Infrastructure
- -Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $ -