NAME

llvmc - The LLVM Compiler Driver (experimental)


SYNOPSIS

llvmc [options] [filenames...]


DESCRIPTION

llvmc is a configurable driver for invoking other LLVM (and non-LLVM) tools in order to compile, optimize and link software for multiple languages. For those familiar with FSF's gcc tool, it is very similar. Please note that llvmc is considered an experimental tool. llvmc has the following goals:

The tool itself does nothing with a user's program. It merely invokes other tools to get the compilation tasks done.

The options supported by llvmc generalize the compilation process and provide a consistent and simple interface for multiple programming languages. This makes it easier for developers to get their software compiled with LLVM. Without llvmc, developers would need to understand how to invoke the front-end compiler, optimizer, assembler, and linker in order to compile their programs. llvmc's sole mission is to trivialize that process.

Basic Operation

llvmc always takes the following basic actions:


OPTIONS

Control Options

Control options tell llvmc what to do at a high level. The following control options are defined:

-c or --compile
This option specifies that the linking phase is not to be run. All previous phases, if applicable will run. This is generally how a given bytecode file is compiled and optimized for a source language module.

-k or --link or default
This option (or the lack of any control option) specifies that all stages of compilation, optimization, and linking should be attempted. Source files specified on the command line will be compiled and linked with objects and libraries also specified.

-S
This option specifies that compilation should end in the creation of an LLVM assembly file that can be later converted to an LLVM object file.

-E
This option specifies that no compilation or linking should be performed. Only pre-processing, if applicable to the language being compiled, is performed. For languages that support it, this will result in the output containing the raw input to the compiler.

Optimization Options

Optimization with llvmc is based on goals and specified with the following -O options. The specific details of which optimizations run is controlled by the configuration files because each source language will have different needs.

-O1 or -O0 (default, fast compilation)
Only those optimizations that will hasten the compilation (mostly by reducing the output) are applied. In general these are extremely fast and simple optimizations that reduce emitted code size. The goal here is not to make the resulting program fast but to make the compilation fast. If not specified, this is the default level of optimization.

-O2 (basic optimization)
This level of optimization specifies a balance between generating good code that will execute reasonably quickly and not spending too much time optimizing the code to get there. For example, this level of optimization may include things like global common subexpression elimination, aggressive dead code elimination, and scalar replication.

-O3 (aggressive optimization)
This level of optimization aggressively optimizes each set of files compiled together. However, no link-time inter-procedural optimization is performed. This level implies all the optimizations of the -O1 and -O2 optimization levels, and should also provide loop optimizations and compile time inter-procedural optimizations. Essentially, this level tries to do as much as it can with the input it is given but doesn't do any link time IPO.

-O4 (link time optimization)
In addition to the previous three levels of optimization, this level of optimization aggressively optimizes each program at link time. It employs basic analysis and basic link-time inter-procedural optimizations, considering the program as a whole.

-O5 (aggressive link time optimization)
This is the same as -O4 except it employs aggressive analyses and aggressive inter-procedural optimization.

-O6 (profile guided optimization: not implemented)
This is the same as -O5 except that it employs profile-guided re-optimization of the program after it has executed. Note that this implies a single level of re-optimization based on runtime profile analysis. Once the re-optimization has completed, the profiling instrumentation is removed and final optimizations are employed.

-O7 (lifelong optimization: not implemented)
This is the same as -O5 and similar to -O6 except that re-optimization is performed through the life of the program. That is, each run will update the profile by which future re-optimizations are directed.

Input Options

-l LIBRARY
This option instructs llvmc to locate a library named LIBRARY and search it for unresolved symbols when linking the program.

-L path
This option instructs llvmc to add path to the list of places in which the linker will

-x LANGUAGE
This option instructs llvmc to regard the following input files as containing programs in the language LANGUAGE. Normally, input file languages are identified by their suffix but this option will override that default behavior. The -x option stays in effect until the end of the options or a new -x option is encountered.

Output Options

-march
This option selects the back end code generator to use. The arch portion of the option names the back end to use.

--native
Normally, llvmc produces bytecode files at most stages of compilation. With this option, llvmc will arrange for native object files to be generated with the -c option, native assembly files to be generated with the -S option, and native executables to be generated with the --link option. In the case of the -E option, the output will not differ as there is no native version of pre-processed output.

-o filename
Specify the output file name. The contents of the file depend on other options.

Information Options

-n or --no-op
This option tells llvmc to do everything but actually execute the resulting tools. In combination with the -v option, this causes llvmc to merely print out what it would have done.

-v or --verbose
This option will cause llvmc to print out (on standard output) each of the actions it takes to accomplish the objective. The output will immediately precede the invocation of other tools.

--stats
Print all statistics gathered during the compilation to the standard error. Note that this option is merely passed through to the sub-tools to do with as they please.

--time-passes
Record the amount of time needed for each optimization pass and print it to standard error. Like --stats this option is just passed through to the sub-tools to do with as they please.

--time-programs
Record the amount of time each program (compilation tool) takes and print it to the standard error.

Language Specific Options

-T,pre=options
Pass an arbitrary option to the pre-processor.

-T,opt=options
Pass an arbitrary option to the optimizer.

-T,lnk=options
Pass an arbitrary option to the linker.

-T,asm=options
Pass an arbitrary option to the code generator.

C/C++ Specific Options

-Ipath
This option is just passed through to a C or C++ front end compiler to tell it where include files can be found.

-Dsymbol
This option is just passed through to a C or C++ front end compiler to tell it to define a symbol.

Miscellaneous Options

--help
Print a summary of command line options.

--version
This option will cause llvmc to print out its version number and terminate.

Advanced Options

You better know what you're doing if you use these options. Improper use of these options can produce drastically wrong results.

--config-dir dirname
This option tells llvmc to read configuration data from the directory named dirname. Data from such directories will be read in the order specified on the command line after all other standard configuration files have been read. This allows users or groups of users to conveniently create their own configuration directories in addition to the standard ones to which they may not have write access.

Unimplemented Options

The options below are not currently implemented in llvmc but will be eventually. They are documented here as ``future design''.

--show-config [suffixes...]
When this option is given, the only action taken by llvmc is to show its final configuration state in the form of a configuration file. No compilation tasks will be conducted when this option is given; processing will stop once the configuration has been printed. The optional (comma separated) list of suffixes controls what is printed. Without any suffixes, the configuration for all languages is printed. With suffixes, only the languages pertaining to those file suffixes will be printed. The configuration information is printed after all command line options and configuration files have been read and processed. This allows the user to verify that the correct configuration data has been read by llvmc.

--config :section:name=value
This option instructs llvmc to accept value as the value for configuration item name in the section named section. This is a quick way to override a configuration item on the command line without resorting to changing the configuration files.

--config-only-from dirname
This option tells llvmc to skip the normal processing of configuration files and only configure from the contents of the dirname directory. Multiple --config-only-from options may be given in which case the directories are read in the order given on the command line.

--emit-raw-code
No optimization is done whatsoever. The compilers invoked by llvmc with this option given will be instructed to produce raw, unoptimized code. This option is useful only to front end language developers and therefore does not participate in the list of -O options. This is distinctly different from the -O0 option (a synonym for -O1) because those optimizations will reduce code size to make compilation faster. With --emit-raw-code, only the full raw code produced by the compiler will be generated.


EXIT STATUS

If llvmc succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non-zero value and no compilation actions will be taken. If one of the compilation tools returns a non-zero status, pending actions will be discarded and llvmc will return the same result code as the failing compilation tool.


DEFICIENCIES

llvmc is considered an experimental LLVM tool because it has these deficiencies:

Insufficient support for native linking
Because llvm-ld doesn't handle native linking, neither can llvmc

Poor configuration support
The support for configuring new languages, etc. is weak. There are many command line configurations that cannot be achieved with the current support. Furthermore the grammar is cumbersome for configuration files. Please see http://llvm.org/PR686 for further details.

Does not handle target specific configurations
This is one of the major deficiencies, also addressed in http://llvm.org/PR686


SEE ALSO

llvm-as, llvm-dis, llc, llvm-link


AUTHORS

Maintained by the LLVM Team (http://llvm.org).