The llvmc tool is a configurable compiler - driver. As such, it isn't the compiler, optimizer, - or linker itself but it drives (invokes) other software that perform those +
The llvmc tool is a configurable compiler + driver. As such, it isn't a compiler, optimizer, + or a linker itself but it drives (invokes) other software that perform those tasks. If you are familiar with the GNU Compiler Collection's gcc tool, llvmc is very similar.
The following introductory sections will help you understand why this tool @@ -68,8 +66,8 @@
llvmc was invented to make compilation with LLVM based compilers - easier. To accomplish this, llvmc strives to:
+llvmc was invented to make compilation of user programs with + LLVM-based tools easier. To accomplish this, llvmc strives to:
- Be the single point of access to most of the LLVM tool set.
- Hide the complexities of the LLVM tools through a single interface. @@ -79,15 +77,14 @@ with LLVM, because it:
- Makes integration of existing non-LLVM tools simple. -
- Extends the capabilities of minimal front ends by optimizing their +
- Extends the capabilities of minimal compiler tools by optimizing their output.
- Reduces the number of interfaces a compiler writer must know about before a working compiler can be completed (essentially only the VMCore interfaces need to be understood).
- Supports source language translator invocation via both dynamically loadable shared objects and invocation of an executable. - - +
At a high level, llvmc operation is very simple. The basic action
taken by llvmc is to simply invoke some tool or set of tools to fill
the user's request for compilation. Every execution of llvmctakes the
- following sequence of steps:
+ following sequence of steps:
- Collect Command Line Options
- The command line options provide the marching orders to llvmc @@ -107,10 +104,11 @@
- Read Configuration Files
- Based on the options and the suffixes of the filenames presented, a set
of configuration files are read to configure the actions llvmc will
- take. Configuration files are provided by either LLVM or the front end
- compiler tools that B
invokes. These files determine what actions - llvmc will take in response to the user's request. See the section - on configuration for more details.
+ take. Configuration files are provided by either LLVM or the
+ compiler tools that llvmc invokes. These files determine what
+ actions llvmc will take in response to the user's request. See
+ the section on configuration for more details.
+
- Determine Phases To Execute
- Based on the command line options and configuration files,
llvmc determines the compilation phases that
@@ -132,18 +130,18 @@
- If any action fails (returns a non-zero result code), llvmc also fails and returns the result code from the failing action. If everything succeeds, llvmc will return a zero result code.
-
llvmc's operation must be simple, regular and predictable. Developers need to be able to rely on it to take a consistent approach to compilation. For example, the invocation:
-- llvmc -O2 x.c y.c z.c -o xyz+
+ llvmc -O2 x.c y.c z.c -o xyz
must produce exactly the same results as:
-- llvmc -O2 x.c - llvmc -O2 y.c - llvmc -O2 z.c - llvmc -O2 x.o y.o z.o -o xyz+
+ llvmc -O2 x.c -o x.o + llvmc -O2 y.c -o y.o + llvmc -O2 z.c -o z.o + llvmc -O2 x.o y.o z.o -o xyz
To accomplish this, llvmc uses a very simple goal oriented procedure to do its work. The overall goal is to produce a functioning executable. To accomplish this, llvmc always attempts to execute a @@ -178,7 +176,7 @@ program.
The following table shows the inputs, outputs, and command line options - applicabe to each phase.
+ applicable to each phase.| Phase | @@ -201,7 +199,7 @@
|
Optimization |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Linking |
|
|
An action, with regard to llvmc is a basic operation that it takes in order to fulfill the user's request. Each phase of compilation will invoke zero or more actions in order to accomplish that phase. -Actions come in two forms:
Actions come in two forms: +
+
@@ -272,11 +265,11 @@
This section of the document describes the configuration files used by
llvmc. Configuration information is relatively static for a
- given release of LLVM and a front end compiler. However, the details may
+ given release of LLVM and a compiler tool. However, the details may
change from release to release of either. Users are encouraged to simply use
- the various options of the B Because llvmc just invokes other programs, it must deal with the available command line options for those programs regardless of whether they -were written for LLVM or not. Furthermore, not all compilation front ends will -have the same capabilities. Some front ends will simply generate LLVM assembly -code, others will be able to generate fully optimized byte code. In general, +were written for LLVM or not. Furthermore, not all compiler tools will +have the same capabilities. Some compiler tools will simply generate LLVM assembly +code, others will be able to generate fully optimized bitcode. In general, llvmc doesn't make any assumptions about the capabilities or command -line options of a sub-tool. It simply uses the details found in the configuration -files and leaves it to the compiler writer to specify the configuration -correctly. - -This approach means that new compiler front ends can be up and working very -quickly. As a first cut, a front end can simply compile its source to raw -(unoptimized) bytecode or LLVM assembly and llvmc can be configured -to pick up the slack (translate LLVM assembly to bytecode, optimize the -bytecode, generate native assembly, link, etc.). In fact, the front end need -not use any LLVM libraries, and it could be written in any language (instead of -C++). The configuration data will allow the full range of optimization, -assembly, and linking capabilities that LLVM provides to be added to these kinds -of tools. Enabling the rapid development of front-ends is one of the primary -goals of llvmc. - -As a compiler front end matures, it may utilize the LLVM libraries and tools -to more efficiently produce optimized bytecode directly in a single compilation +line options of a sub-tool. It simply uses the details found in the +configuration files and leaves it to the compiler writer to specify the +configuration correctly. + +This approach means that new compiler tools can be up and working very +quickly. As a first cut, a tool can simply compile its source to raw +(unoptimized) bitcode or LLVM assembly and llvmc can be configured +to pick up the slack (translate LLVM assembly to bitcode, optimize the +bitcode, generate native assembly, link, etc.). In fact, the compiler tools +need not use any LLVM libraries, and it could be written in any language +(instead of C++). The configuration data will allow the full range of +optimization, assembly, and linking capabilities that LLVM provides to be added +to these kinds of tools. Enabling the rapid development of front-ends is one +of the primary goals of llvmc. + +As a compiler tool matures, it may utilize the LLVM libraries and tools +to more efficiently produce optimized bitcode directly in a single compilation and optimization program. In these cases, multiple tools would not be needed and the configuration data for the compiler would change. Configuring llvmc to the needs and capabilities of a source language -compiler is relatively straight forward. A compiler writer must provide a +compiler is relatively straight-forward. A compiler writer must provide a definition of what to do for each of the five compilation phases for each of the optimization levels. The specification consists simply of prototypical command lines into which llvmc can substitute command line @@ -334,24 +327,24 @@ optimization. - + + +
+
+
+
+
Each configuration file provides the details for a single source language + that is to be compiled. This configuration information tells llvmc + how to invoke the language's pre-processor, translator, optimizer, assembler + and linker. Note that a given source language needn't provide all these tools + as many of them exist in llvm currently. +
-
+
+
+File Types-There are two types of configuration files: the master configuration file - and the language specific configuration file. The master configuration file - contains the general configuration of llvmc itself and is supplied - with the tool. It contains information that is source language agnostic. - Language specific configuration files tell llvmc how to invoke the - language's compiler for a variety of different tasks and what other tools - are needed to backfill the compiler's missing features (e.g. - optimization). - -Directory Searchllvmc always looks for files of a specific name. It uses the
first file with the name its looking for by searching directories in the
following order:
The first file found in this search will be used. Other files with the + same name will be ignored even if they exist in one of the subsequent search locations. +
+
- In the directories searched, each configuration file is given a specific + name to foster faster lookup (so llvmc doesn't have to do directory searches). + The name of a given language specific configuration file is simply the same + as the suffix used to identify files containing source in that language. + For example, a configuration file for C++ source might be named + cpp, C, or cxx. For languages that support multiple + file suffixes, multiple (probably identical) files (or symbolic links) will + need to be provided. +File Names-In the directories searched, a file named master will be - recognized as the master configuration file for llvmc. Note that - users may override the master file with a copy in their home directory - but they are advised not to. This capability is only useful for compiler - implementers needing to alter the master configuration while developing - their compiler front end. When reading the configuration files, the master - files are always read first. -Language specific configuration files are given specific names to foster - faster lookup. The name of a given language specific configuration file is - the same as the suffix used to identify files containing source in that - language. For example, a configuration file for C++ source might be named - cpp, C, or cxx. - -What Gets Read-The master configuration file is always read. Which language specific - configuration files are read depends on the command line options and the - suffixes of the file names provided on llvmc's command line. Note - that the --x LANGUAGE option alters the language that llvmc - uses for the subsequent files on the command line. Only the language - specific configuration files actually needed to complete llvmc's - task are read. Other language specific files will be ignored. + +
+
Which configuration files are read depends on the command line options and + the suffixes of the file names provided on llvmc's command line. Note + that the -x LANGUAGE option alters the language that llvmc + uses for the subsequent files on the command line. Only the configuration + files actually needed to complete llvmc's task are read. Other + language specific files will be ignored.
-
-
+
The syntax of the configuration files is yet to be determined. There are
- two viable options remaining: The syntax of the configuration files is very simple and somewhat + compatible with Java's property files. Here are the syntax rules:
-
+
+
+
+The following description of configuration items is syntax-less and simply - uses a naming hierarchy to describe the configuration items. Whatever - syntax is chosen will need to map the hierarchy to the given syntax. +The table below provides definitions of the allowed configuration items + that may appear in a configuration file. Every item has a default value and + does not need to appear in the configuration file. Missing items will have the + default value. Each identifier may appear as all lower case, first letter + capitalized or all upper case.
+
+
+
+On any configuration item that ends in command, you must + specify substitution tokens. Substitution tokens begin and end with a percent + sign (%) and are replaced by the corresponding text. Any substitution + token may be given on any command line but some are more useful than + others. In particular each command should have both an %in% + and an %out% substitution. The table below provides definitions of + each of the allowed substitution tokens. +
+
+
@@ -448,7 +761,7 @@ optimization.
defined below.
Since an example is always instructive, here's how the Stacker language + configuration file looks. ++# Stacker Configuration File For llvmc + +########################################################## +# Language definitions +########################################################## + lang.name=Stacker + lang.opt1=-simplifycfg -instcombine -mem2reg + lang.opt2=-simplifycfg -instcombine -mem2reg -load-vn \ + -gcse -dse -scalarrepl -sccp + lang.opt3=-simplifycfg -instcombine -mem2reg -load-vn \ + -gcse -dse -scalarrepl -sccp -branch-combine -adce \ + -globaldce -inline -licm + lang.opt4=-simplifycfg -instcombine -mem2reg -load-vn \ + -gcse -dse -scalarrepl -sccp -ipconstprop \ + -branch-combine -adce -globaldce -inline -licm + lang.opt5=-simplifycfg -instcombine -mem2reg --load-vn \ + -gcse -dse scalarrepl -sccp -ipconstprop \ + -branch-combine -adce -globaldce -inline -licm \ + -block-placement + +########################################################## +# Pre-processor definitions +########################################################## + + # Stacker doesn't have a preprocessor but the following + # allows the -E option to be supported + preprocessor.command=cp %in% %out% + preprocessor.required=false + +########################################################## +# Translator definitions +########################################################## + + # To compile stacker source, we just run the stacker + # compiler with a default stack size of 2048 entries. + translator.command=stkrc -s 2048 %in% -o %out% %time% \ + %stats% %force% %args% + + # stkrc doesn't preprocess but we set this to true so + # that we don't run the cp command by default. + translator.preprocesses=true + + # The translator is required to run. + translator.required=true + + # stkrc doesn't handle the -On options + translator.output=bitcode + +########################################################## +# Optimizer definitions +########################################################## + + # For optimization, we use the LLVM "opt" program + optimizer.command=opt %in% -o %out% %opt% %time% %stats% \ + %force% %args% + + optimizer.required = true + + # opt doesn't translate + optimizer.translates = no + + # opt doesn't preprocess + optimizer.preprocesses=no + + # opt produces bitcode + optimizer.output = bc + +########################################################## +# Assembler definitions +########################################################## + assembler.command=llc %in% -o %out% %target% %time% %stats% ++ -The LLVM Compiler Infrastructure +The LLVM Compiler Infrastructure Last modified: $Date$ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||