5 llvmc - The LLVM Compiler Driver
9 B<llvmc> [I<options>] [I<filenames>...]
13 The B<llvmc> command is a configurable driver for invoking other
14 LLVM (and non-LLVM) tools in order to compile, optimize and link software
15 for multiple languages. For those familiar with the GNU Compiler
16 Collection's B<gcc> tool, it is very similar. This tool has the
17 following main goals or purposes:
21 =item * A Single point of access to the LLVM tool set.
23 =item * Hide the complexities of the LLVM tools through a single interface.
25 =item * Make integration of existing non-LLVM tools simple.
27 =item * Extend the capabilities of minimal front ends.
29 =item * Make the interface for compiling consistent for all languages.
33 The tool itself does nothing with a user's program. It merely invokes other
34 tools to get the compilation tasks done.
36 The options supported by B<llvmc> generalize the compilation process and
37 provide a consistent and simple interface for multiple programming languages.
38 This makes it easier for developers to get their software compiled with LLVM.
39 Without B<llvmc>, developers would need to understand how to invoke the
40 front-end compiler, optimizer, assembler, and linker in order to compile their
41 programs. B<llvmc>'s sole mission is to trivialize that process.
43 =head2 Basic Operation
45 B<llvmc> always takes the following basic actions:
49 =item * Command line options and filenames are collected.
51 The command line options provide the marching orders to B<llvmc> on what actions
52 it should perform. This is the I<request> the user is making of B<llvmc> and it
55 =item * Configuration files are read.
57 Based on the options and the suffixes of the filenames presented, a set of
58 configuration files are read to configure the actions B<llvmc> will take.
59 Configuration files are provided by either LLVM or the front end compiler tools
60 that B<llvmc> invokes. Users generally don't need to be concerned with the
61 contents of the configuration files.
63 =item * Determine actions to take.
65 The tool chain needed to complete the task is determined. This is the primary
66 work of B<llvmc>. It breaks the request specified by the command line options
67 into a set of basic actions to be done:
71 =item * Pre-processing: gathering/filtering compiler input (optional).
73 =item * Translation: source language to bytecode conversion.
75 =item * Assembly: bytecode to native code conversion.
77 =item * Optimization: conversion of bytecode to something that runs faster.
79 =item * Linking: combining multiple bytecodes to produce executable program.
83 =item * Execute actions.
85 The actions determined previously are executed sequentially and then
92 =head2 Control Options
94 Control options tell B<llvmc> what to do at a high level. The
95 following control options are defined:
99 =item B<-c> or B<--compile>
101 This option specifies that the linking phase is not to be run. All
102 previous phases, if applicable will run. This is generally how a given
103 bytecode file is compiled and optimized for a source language module.
105 =item B<-k> or B<--link> or default
107 This option (or the lack of any control option) specifies that all stages
108 of compilation, optimization, and linking should be attempted. Source files
109 specified on the command line will be compiled and linked with objects and
110 libraries also specified.
114 This option specifies that compilation should end in the creation of
115 an LLVM assembly file that can be later converted to an LLVM object
120 This option specifies that no compilation or linking should be
121 performed. Only pre-processing, if applicable to the language being
122 compiled, is performed. For languages that support it, this will
123 result in the output containing the raw input to the compiler.
127 =head2 Optimization Options
129 Optimization with B<llvmc> is based on goals and specified with
130 the following -O options. The specific details of which
131 optimizations run is controlled by the configuration files because
132 each source language will have different needs.
136 =item B<-O1> or B<-O0> (default, fast compilation)
138 Only those optimizations that will hasten the compilation (mostly by reducing
139 the output) are applied. In general these are extremely fast and simple
140 optimizations that reduce emitted code size. The goal here is not to make the
141 resulting program fast but to make the compilation fast. If not specified,
142 this is the default level of optimization.
144 =item B<-O2> (basic optimization)
146 This level of optimization specifies a balance between generating good code
147 that will execute reasonably quickly and not spending too much time optimizing
148 the code to get there. For example, this level of optimization may include
149 things like global common subexpression elimination, aggressive dead code
150 elimination, and scalar replication.
152 =item B<-O3> (aggressive optimization)
154 This level of optimization aggressively optimizes each set of files compiled
155 together. However, no link-time inter-procedural optimization is performed.
156 This level implies all the optimizations of the B<-O1> and B<-O2> optimization
157 levels, and should also provide loop optimizations and compile time
158 inter-procedural optimizations. Essentially, this level tries to do as much
159 as it can with the input it is given but doesn't do any link time IPO.
161 =item B<-O4> (link time optimization)
163 In addition to the previous three levels of optimization, this level of
164 optimization aggressively optimizes each program at link time. It employs
165 basic analysis and basic link-time inter-procedural optimizations,
166 considering the program as a whole.
168 =item B<-O5> (aggressive link time optimization)
170 This is the same as B<-O4> except it employs aggressive analyses and
171 aggressive inter-procedural optimization.
173 =item B<-O6> (profile guided optimization: not implemented)
175 This is the same as B<-O5> except that it employs profile-guided
176 re-optimization of the program after it has executed. Note that this implies
177 a single level of re-optimization based on runtime profile analysis. Once
178 the re-optimization has completed, the profiling instrumentation is
179 removed and final optimizations are employed.
181 =item B<-O7> (lifelong optimization: not implemented)
183 This is the same as B<-O5> and similar to B<-O6> except that re-optimization
184 is performed through the life of the program. That is, each run will update
185 the profile by which future re-optimizations are directed.
193 =item B<-l> I<LIBRARY>
195 This option instructs B<llvmc> to locate a library named I<LIBRARY> and search
196 it for unresolved symbols when linking the program.
200 This option instructs B<llvmc> to add F<path> to the list of places in which
203 =item B<-x> I<LANGUAGE>
205 This option instructs B<llvmc> to regard the following input files as
206 containing programs in the language I<LANGUAGE>. Normally, input file languages
207 are identified by their suffix but this option will override that default
208 behavior. The B<-x> option stays in effect until the end of the options or
209 a new B<-x> option is encountered.
213 =head2 Output Options
219 This option selects the back end code generator to use. The I<arch> portion
220 of the option names the back end to use.
224 Normally, B<llvmc> produces bytecode files at most stages of compilation.
225 With this option, B<llvmc> will arrange for native object files to be
226 generated with the B<-c> option, native assembly files to be generated
227 with the B<-S> option, and native executables to be generated with the
228 B<--link> option. In the case of the B<-E> option, the output will not
229 differ as there is no I<native> version of pre-processed output.
231 =item B<-o> F<filename>
233 Specify the output file name. The contents of the file depend on other
238 =head2 Information Options
242 =item B<-n> or B<--no-op>
244 This option tells B<llvmc> to do everything but actually execute the
245 resulting tools. In combination with the B<-v> option, this causes B<llvmc>
246 to merely print out what it would have done.
248 =item B<-v> or B<--verbose>
250 This option will cause B<llvmc> to print out (on standard output) each of the
251 actions it takes to accomplish the objective. The output will immediately
252 precede the invocation of other tools.
256 Print all statistics gathered during the compilation to the standard error.
257 Note that this option is merely passed through to the sub-tools to do with
260 =item B<--time-passes>
262 Record the amount of time needed for each optimization pass and print it
263 to standard error. Like B<--stats> this option is just passed through to
264 the sub-tools to do with as they please.
266 =item B<--time-programs>
268 Record the amount of time each program (compilation tool) takes and print
269 it to the standard error.
273 =head2 Language Specific Options
277 =item B<-T,pre>=I<options>
279 Pass an arbitrary option to the pre-processor.
281 =item B<-T,opt>=I<options>
283 Pass an arbitrary option to the optimizer.
285 =item B<-T,lnk>=I<options>
287 Pass an arbitrary option to the linker.
289 =item B<-T,asm>=I<options>
291 Pass an arbitrary option to the code generator.
295 =head3 C/C++ Specific Options
301 This option is just passed through to a C or C++ front end compiler to tell it
302 where include files can be found.
306 This option is just passed through to a C or C++ front end compiler to tell it
311 =head2 Miscellaneous Options
317 Print a summary of command line options.
321 This option will cause B<llvmc> to print out its version number and terminate.
325 =head2 Advanced Options
327 You better know what you're doing if you use these options. Improper use
328 of these options can produce drastically wrong results.
332 =item B<--config-dir> F<dirname>
334 This option tells B<llvmc> to read configuration data from the I<directory>
335 named F<dirname>. Data from such directories will be read in the order
336 specified on the command line after all other standard configuration files have
337 been read. This allows users or groups of users to conveniently create
338 their own configuration directories in addition to the standard ones to which
339 they may not have write access.
342 =head2 Unimplemented Options
344 The options below are not currently implemented in B<llvmc> but will be
345 eventually. They are documented here as "future design".
349 =item B<--show-config> I<[suffixes...]>
351 When this option is given, the only action taken by B<llvmc> is to show its
352 final configuration state in the form of a configuration file. No compilation
353 tasks will be conducted when this option is given; processing will stop once
354 the configuration has been printed. The optional (comma separated) list of
355 suffixes controls what is printed. Without any suffixes, the configuration
356 for all languages is printed. With suffixes, only the languages pertaining
357 to those file suffixes will be printed. The configuration information is
358 printed after all command line options and configuration files have been
359 read and processed. This allows the user to verify that the correct
360 configuration data has been read by B<llvmc>.
362 =item B<--config> :I<section>:I<name>=I<value>
364 This option instructs B<llvmc> to accept I<value> as the value for configuration
365 item I<name> in the section named I<section>. This is a quick way to override
366 a configuration item on the command line without resorting to changing the
369 =item B<--config-only-from> F<dirname>
371 This option tells B<llvmc> to skip the normal processing of configuration
372 files and only configure from the contents of the F<dirname> directory. Multiple
373 B<--config-only-from> options may be given in which case the directories are
374 read in the order given on the command line.
376 =item B<--emit-raw-code>
378 No optimization is done whatsoever. The compilers invoked by B<llvmc> with
379 this option given will be instructed to produce raw, unoptimized code. This
380 option is useful only to front end language developers and therefore does not
381 participate in the list of B<-O> options. This is distinctly different from
382 the B<-O0> option (a synonym for B<-O1>) because those optimizations will
383 reduce code size to make compilation faster. With B<--emit-raw-code>, only
384 the full raw code produced by the compiler will be generated.
391 If B<llvmc> succeeds, it will exit with 0. Otherwise, if an error
392 occurs, it will exit with a non-zero value and no compilation actions
393 will be taken. If one of the compilation tools returns a non-zero
394 status, pending actions will be discarded and B<llvmc> will return the
395 same result code as the failing compilation tool.
399 L<gccas|gccas>, L<gccld|gccld>, L<llvm-as|llvm-as>, L<llvm-dis|llvm-dis>,
400 L<llc|llc>, L<llvm-link|llvm-link>
404 Maintained by the LLVM Team (L<http://llvm.cs.uiuc.edu>).