5 llvmc - The LLVM Compiler Driver (experimental)
9 B<llvmc> [I<options>] [I<filenames>...]
13 B<llvmc> is a configurable driver for invoking other LLVM (and non-LLVM) tools
14 in order to compile, optimize and link software for multiple languages. For
15 those familiar with FSF's B<gcc> tool, it is very similar. Please note that
16 B<llvmc> is considered an experimental tool. B<llvmc> has the following goals:
20 =item * provide a single point of access to the LLVM tool set,
22 =item * hide the complexities of the LLVM tools through a single interface,
24 =item * make integration of existing non-LLVM tools simple,
26 =item * extend the capabilities of minimal front ends, and
28 =item * make the interface for compiling consistent for all languages.
32 The tool itself does nothing with a user's program. It merely invokes other
33 tools to get the compilation tasks done.
35 The options supported by B<llvmc> generalize the compilation process and
36 provide a consistent and simple interface for multiple programming languages.
37 This makes it easier for developers to get their software compiled with LLVM.
38 Without B<llvmc>, developers would need to understand how to invoke the
39 front-end compiler, optimizer, assembler, and linker in order to compile their
40 programs. B<llvmc>'s sole mission is to trivialize that process.
42 =head2 Basic Operation
44 B<llvmc> always takes the following basic actions:
48 =item * Command line options and filenames are collected.
50 The command line options provide the marching orders to B<llvmc> on what actions
51 it should perform. This is the I<request> the user is making of B<llvmc> and it
54 =item * Configuration files are read.
56 Based on the options and the suffixes of the filenames presented, a set of
57 configuration files are read to configure the actions B<llvmc> will take.
58 Configuration files are provided by either LLVM or the front end compiler tools
59 that B<llvmc> invokes. Users generally don't need to be concerned with the
60 contents of the configuration files.
62 =item * Determine actions to take.
64 The tool chain needed to complete the task is determined. This is the primary
65 work of B<llvmc>. It breaks the request specified by the command line options
66 into a set of basic actions to be done:
70 =item * Pre-processing: gathering/filtering compiler input (optional).
72 =item * Translation: source language to bytecode conversion.
74 =item * Assembly: bytecode to native code conversion.
76 =item * Optimization: conversion of bytecode to something that runs faster.
78 =item * Linking: combining multiple bytecodes to produce executable program.
82 =item * Execute actions.
84 The actions determined previously are executed sequentially and then
91 =head2 Control Options
93 Control options tell B<llvmc> what to do at a high level. The
94 following control options are defined:
98 =item B<-c> or B<--compile>
100 This option specifies that the linking phase is not to be run. All
101 previous phases, if applicable will run. This is generally how a given
102 bytecode file is compiled and optimized for a source language module.
104 =item B<-k> or B<--link> or default
106 This option (or the lack of any control option) specifies that all stages
107 of compilation, optimization, and linking should be attempted. Source files
108 specified on the command line will be compiled and linked with objects and
109 libraries also specified.
113 This option specifies that compilation should end in the creation of
114 an LLVM assembly file that can be later converted to an LLVM object
119 This option specifies that no compilation or linking should be
120 performed. Only pre-processing, if applicable to the language being
121 compiled, is performed. For languages that support it, this will
122 result in the output containing the raw input to the compiler.
126 =head2 Optimization Options
128 Optimization with B<llvmc> is based on goals and specified with
129 the following -O options. The specific details of which
130 optimizations run is controlled by the configuration files because
131 each source language will have different needs.
135 =item B<-O1> or B<-O0> (default, fast compilation)
137 Only those optimizations that will hasten the compilation (mostly by reducing
138 the output) are applied. In general these are extremely fast and simple
139 optimizations that reduce emitted code size. The goal here is not to make the
140 resulting program fast but to make the compilation fast. If not specified,
141 this is the default level of optimization.
143 =item B<-O2> (basic optimization)
145 This level of optimization specifies a balance between generating good code
146 that will execute reasonably quickly and not spending too much time optimizing
147 the code to get there. For example, this level of optimization may include
148 things like global common subexpression elimination, aggressive dead code
149 elimination, and scalar replication.
151 =item B<-O3> (aggressive optimization)
153 This level of optimization aggressively optimizes each set of files compiled
154 together. However, no link-time inter-procedural optimization is performed.
155 This level implies all the optimizations of the B<-O1> and B<-O2> optimization
156 levels, and should also provide loop optimizations and compile time
157 inter-procedural optimizations. Essentially, this level tries to do as much
158 as it can with the input it is given but doesn't do any link time IPO.
160 =item B<-O4> (link time optimization)
162 In addition to the previous three levels of optimization, this level of
163 optimization aggressively optimizes each program at link time. It employs
164 basic analysis and basic link-time inter-procedural optimizations,
165 considering the program as a whole.
167 =item B<-O5> (aggressive link time optimization)
169 This is the same as B<-O4> except it employs aggressive analyses and
170 aggressive inter-procedural optimization.
172 =item B<-O6> (profile guided optimization: not implemented)
174 This is the same as B<-O5> except that it employs profile-guided
175 re-optimization of the program after it has executed. Note that this implies
176 a single level of re-optimization based on runtime profile analysis. Once
177 the re-optimization has completed, the profiling instrumentation is
178 removed and final optimizations are employed.
180 =item B<-O7> (lifelong optimization: not implemented)
182 This is the same as B<-O5> and similar to B<-O6> except that re-optimization
183 is performed through the life of the program. That is, each run will update
184 the profile by which future re-optimizations are directed.
192 =item B<-l> I<LIBRARY>
194 This option instructs B<llvmc> to locate a library named I<LIBRARY> and search
195 it for unresolved symbols when linking the program.
199 This option instructs B<llvmc> to add F<path> to the list of places in which
202 =item B<-x> I<LANGUAGE>
204 This option instructs B<llvmc> to regard the following input files as
205 containing programs in the language I<LANGUAGE>. Normally, input file languages
206 are identified by their suffix but this option will override that default
207 behavior. The B<-x> option stays in effect until the end of the options or
208 a new B<-x> option is encountered.
212 =head2 Output Options
218 This option selects the back end code generator to use. The I<arch> portion
219 of the option names the back end to use.
223 Normally, B<llvmc> produces bytecode files at most stages of compilation.
224 With this option, B<llvmc> will arrange for native object files to be
225 generated with the B<-c> option, native assembly files to be generated
226 with the B<-S> option, and native executables to be generated with the
227 B<--link> option. In the case of the B<-E> option, the output will not
228 differ as there is no I<native> version of pre-processed output.
230 =item B<-o> F<filename>
232 Specify the output file name. The contents of the file depend on other
237 =head2 Information Options
241 =item B<-n> or B<--no-op>
243 This option tells B<llvmc> to do everything but actually execute the
244 resulting tools. In combination with the B<-v> option, this causes B<llvmc>
245 to merely print out what it would have done.
247 =item B<-v> or B<--verbose>
249 This option will cause B<llvmc> to print out (on standard output) each of the
250 actions it takes to accomplish the objective. The output will immediately
251 precede the invocation of other tools.
255 Print all statistics gathered during the compilation to the standard error.
256 Note that this option is merely passed through to the sub-tools to do with
259 =item B<--time-passes>
261 Record the amount of time needed for each optimization pass and print it
262 to standard error. Like B<--stats> this option is just passed through to
263 the sub-tools to do with as they please.
265 =item B<--time-programs>
267 Record the amount of time each program (compilation tool) takes and print
268 it to the standard error.
272 =head2 Language Specific Options
276 =item B<-T,pre>=I<options>
278 Pass an arbitrary option to the pre-processor.
280 =item B<-T,opt>=I<options>
282 Pass an arbitrary option to the optimizer.
284 =item B<-T,lnk>=I<options>
286 Pass an arbitrary option to the linker.
288 =item B<-T,asm>=I<options>
290 Pass an arbitrary option to the code generator.
294 =head2 C/C++ Specific Options
300 This option is just passed through to a C or C++ front end compiler to tell it
301 where include files can be found.
305 This option is just passed through to a C or C++ front end compiler to tell it
310 =head2 Miscellaneous Options
316 Print a summary of command line options.
320 This option will cause B<llvmc> to print out its version number and terminate.
324 =head2 Advanced Options
326 You better know what you're doing if you use these options. Improper use
327 of these options can produce drastically wrong results.
331 =item B<--config-dir> F<dirname>
333 This option tells B<llvmc> to read configuration data from the I<directory>
334 named F<dirname>. Data from such directories will be read in the order
335 specified on the command line after all other standard configuration files have
336 been read. This allows users or groups of users to conveniently create
337 their own configuration directories in addition to the standard ones to which
338 they may not have write access.
343 =head2 Unimplemented Options
345 The options below are not currently implemented in B<llvmc> but will be
346 eventually. They are documented here as "future design".
350 =item B<--show-config> I<[suffixes...]>
352 When this option is given, the only action taken by B<llvmc> is to show its
353 final configuration state in the form of a configuration file. No compilation
354 tasks will be conducted when this option is given; processing will stop once
355 the configuration has been printed. The optional (comma separated) list of
356 suffixes controls what is printed. Without any suffixes, the configuration
357 for all languages is printed. With suffixes, only the languages pertaining
358 to those file suffixes will be printed. The configuration information is
359 printed after all command line options and configuration files have been
360 read and processed. This allows the user to verify that the correct
361 configuration data has been read by B<llvmc>.
363 =item B<--config> :I<section>:I<name>=I<value>
365 This option instructs B<llvmc> to accept I<value> as the value for configuration
366 item I<name> in the section named I<section>. This is a quick way to override
367 a configuration item on the command line without resorting to changing the
370 =item B<--config-only-from> F<dirname>
372 This option tells B<llvmc> to skip the normal processing of configuration
373 files and only configure from the contents of the F<dirname> directory. Multiple
374 B<--config-only-from> options may be given in which case the directories are
375 read in the order given on the command line.
377 =item B<--emit-raw-code>
379 No optimization is done whatsoever. The compilers invoked by B<llvmc> with
380 this option given will be instructed to produce raw, unoptimized code. This
381 option is useful only to front end language developers and therefore does not
382 participate in the list of B<-O> options. This is distinctly different from
383 the B<-O0> option (a synonym for B<-O1>) because those optimizations will
384 reduce code size to make compilation faster. With B<--emit-raw-code>, only
385 the full raw code produced by the compiler will be generated.
392 If B<llvmc> succeeds, it will exit with 0. Otherwise, if an error
393 occurs, it will exit with a non-zero value and no compilation actions
394 will be taken. If one of the compilation tools returns a non-zero
395 status, pending actions will be discarded and B<llvmc> will return the
396 same result code as the failing compilation tool.
400 B<llvmc> is considered an experimental LLVM tool because it has these
405 =item Insufficient support for native linking
407 Because B<llvm-ld> doesn't handle native linking, neither can B<llvmc>
409 =item Poor configuration support
411 The support for configuring new languages, etc. is weak. There are many
412 command line configurations that cannot be achieved with the current
413 support. Furthermore the grammar is cumbersome for configuration files.
414 Please see L<http://llvm.org/PR686> for further details.
416 =item Does not handle target specific configurations
418 This is one of the major deficiencies, also addressed in
419 L<http://llvm.org/PR686>
425 L<llvm-as|llvm-as>, L<llvm-dis|llvm-dis>, L<llc|llc>, L<llvm-link|llvm-link>
429 Maintained by the LLVM Team (L<http://llvm.org>).