llvm-6502/tools/llvmc2/doc/LLVMC-Tutorial.rst

93 lines
2.7 KiB
ReStructuredText
Raw Normal View History

======================
Tutorial - Using LLVMC
======================
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. This
tutorial describes the basic usage and configuration of LLVMC.
.. contents::
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::
$ llvmc2 -O3 -Wall hello.cpp
$ ./a.out
hello
For further help on command-line LLVMC usage, refer to the ``llvmc
--help`` output.
Using LLVMC to generate toolchain drivers
=========================================
At the time of writing LLVMC does not support on-the-fly reloading of
configuration, so it will be necessary to recompile its source
code. LLVMC uses TableGen [1]_ as its configuration language, so
you'll need to familiar with it.
Start by compiling ``examples/Simple.td``, which is a simple wrapper
for ``gcc``::
$ cd $LLVM_DIR/tools/llvmc2
$ make TOOLNAME=mygcc GRAPH=examples/Simple.td
$ edit hello.c
$ mygcc hello.c
$ ./hello.out
Hello
Contents of the file ``Simple.td`` look like this::
// Include common definitions
include "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 transformation graph: vertices
in this graph are tools, and edges signify that there is a
transformation path between two tools (for example, assembly source
produced by the compiler can be transformed into executable code by an
assembler). A special node named ``root`` is used to mark the graph
entry points.
Tool descriptions are basically lists of properties: 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.
``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 sample configuration files in the ``examples`` directory.
References
==========
.. [1] TableGen Fundamentals
http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html