docs/CommandGuide/llvmc.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 llvmc - The LLVM Compiler Driver (experimental)
   6
   7 =head1 SYNOPSIS
   8
   9 B<llvmc> [I<options>] [I<filenames>...]
  10
  11 =head1 DESCRIPTION
  12
  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:
  17
  18 =over
  19
  20 =item * provide a single point of access to the LLVM tool set,
  21
  22 =item * hide the complexities of the LLVM tools through a single interface,
  23
  24 =item * make integration of existing non-LLVM tools simple,
  25
  26 =item * extend the capabilities of minimal front ends, and
  27
  28 =item * make the interface for compiling consistent for all languages.
  29
  30 =back
  31
  32 The tool itself does nothing with a user's program. It merely invokes other
  33 tools to get the compilation tasks done.
  34
  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.
  41
  42 =head2 Basic Operation
  43
  44 B<llvmc> always takes the following basic actions:
  45
  46 =over
  47
  48 =item * Command line options and filenames are collected.
  49
  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
  52 is interpreted first.
  53
  54 =item * Configuration files are read.
  55
  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.
  61
  62 =item * Determine actions to take.
  63
  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:
  67
  68 =over
  69
  70 =item * Pre-processing: gathering/filtering compiler input (optional).
  71
  72 =item * Translation: source language to bitcode conversion.
  73
  74 =item * Assembly: bitcode to native code conversion.
  75
  76 =item * Optimization: conversion of bitcode to something that runs faster.
  77
  78 =item * Linking: combining multiple bitcode files to produce executable program.
  79
  80 =back
  81
  82 =item * Execute actions.
  83
  84 The actions determined previously are executed sequentially and then
  85 B<llvmc> terminates.
  86
  87 =back
  88
  89 =head1 OPTIONS
  90
  91 =head2 Control Options
  92
  93 Control options tell B<llvmc> what to do at a high level. The
  94 following control options are defined:
  95
  96 =over
  97
  98 =item B<-c> or B<--compile>
  99
 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 bitcode file is compiled and optimized for a source language module.
 103
 104 =item B<-k> or B<--link> or default
 105
 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.
 110
 111 =item B<-S>
 112
 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
 115 file.
 116
 117 =item B<-E>
 118
 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.
 123
 124 =back
 125
 126 =head2 Optimization Options
 127
 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.
 132
 133 =over
 134
 135 =item B<-O1> or B<-O0> (default, fast compilation)
 136
 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.
 142
 143 =item B<-O2> (basic optimization)
 144
 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 sub-expression elimination, aggressive dead code
 149 elimination, and scalar replication.
 150
 151 =item B<-O3> (aggressive optimization)
 152
 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.
 159
 160 =item B<-O4> (link time optimization)
 161
 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.
 166
 167 =item B<-O5> (aggressive link time optimization)
 168
 169 This is the same as B<-O4> except it employs aggressive analyses and
 170 aggressive inter-procedural optimization.
 171
 172 =item B<-O6> (profile guided optimization: not implemented)
 173
 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 run time profile analysis. Once
 177 the re-optimization has completed, the profiling instrumentation is
 178 removed and final optimizations are employed.
 179
 180 =item B<-O7> (lifelong optimization: not implemented)
 181
 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.
 185
 186 =back
 187
 188 =head2 Input Options
 189
 190 =over
 191
 192 =item B<-l> I<LIBRARY>
 193
 194 This option instructs B<llvmc> to locate a library named I<LIBRARY> and search
 195 it for unresolved symbols when linking the program.
 196
 197 =item B<-L> F<path>
 198
 199 This option instructs B<llvmc> to add F<path> to the list of places in which
 200 the linker will
 201
 202 =item B<-x> I<LANGUAGE>
 203
 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.
 209
 210 =back
 211
 212 =head2 Output Options
 213
 214 =over
 215
 216 =item B<-m>I<arch>
 217
 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.
 220
 221 =item B<--native>
 222
 223 Normally, B<llvmc> produces bitcode 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.
 229
 230 =item B<-o> F<filename>
 231
 232 Specify the output file name.  The contents of the file  depend on other
 233 options.
 234
 235 =back
 236
 237 =head2 Information Options
 238
 239 =over
 240
 241 =item B<-n> or B<--no-op>
 242
 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.
 246
 247 =item B<-v> or B<--verbose>
 248
 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.
 252
 253 =item B<--stats>
 254
 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
 257 as they please.
 258
 259 =item B<--time-passes>
 260
 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.
 264
 265 =item B<--time-programs>
 266
 267 Record the amount of time each program (compilation tool) takes and print
 268 it to the standard error.
 269
 270 =back
 271
 272 =head2 Language Specific Options
 273
 274 =over
 275
 276 =item B<-T,pre>=I<options>
 277
 278 Pass an arbitrary option to the pre-processor.
 279
 280 =item B<-T,opt>=I<options>
 281
 282 Pass an arbitrary option to the optimizer.
 283
 284 =item B<-T,lnk>=I<options>
 285
 286 Pass an arbitrary option to the linker.
 287
 288 =item B<-T,asm>=I<options>
 289
 290 Pass an arbitrary option to the code generator.
 291
 292 =back
 293
 294 =head2 C/C++ Specific Options
 295
 296 =over
 297
 298 =item B<-I>F<path>
 299
 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.
 302
 303 =item B<-D>F<symbol>
 304
 305 This option is just passed through to a C or C++ front end compiler to tell it
 306 to define a symbol.
 307
 308 =back
 309
 310 =head2 Miscellaneous Options
 311
 312 =over
 313
 314 =item B<--help>
 315
 316 Print a summary of command line options.
 317
 318 =item B<--version>
 319
 320 This option will cause B<llvmc> to print out its version number and terminate.
 321
 322 =back
 323
 324 =head2 Advanced Options
 325
 326 You better know what you're doing if you use these options. Improper use
 327 of these options can produce drastically wrong results.
 328
 329 =over
 330
 331 =item B<--config-dir> F<dirname>
 332
 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.
 339
 340 =back
 341
 342
 343 =head2 Unimplemented Options
 344
 345 The options below are not currently implemented in B<llvmc> but will be
 346 eventually. They are documented here as "future design".
 347
 348 =over
 349
 350 =item B<--show-config> I<[suffixes...]>
 351
 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>.
 362
 363 =item B<--config> :I<section>:I<name>=I<value>
 364
 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
 368 configuration files.
 369
 370 =item B<--config-only-from> F<dirname>
 371
 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.
 376
 377 =item B<--emit-raw-code>
 378
 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.
 386
 387 =back
 388
 389
 390 =head1 EXIT STATUS
 391
 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.
 397
 398 =head1 DEFICIENCIES
 399
 400 B<llvmc> is considered an experimental LLVM tool because it has these
 401 deficiencies:
 402
 403 =over
 404
 405 =item Insufficient support for native linking
 406
 407 Because B<llvm-ld> doesn't handle native linking, neither can B<llvmc>
 408
 409 =item Poor configuration support
 410
 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.
 415
 416 =item Does not handle target specific configurations
 417
 418 This is one of the major deficiencies, also addressed in
 419 L<http://llvm.org/PR686>
 420
 421 =back
 422
 423 =head1 SEE ALSO
 424
 425 L<llvm-as|llvm-as>, L<llvm-dis|llvm-dis>, L<llc|llc>, L<llvm-link|llvm-link>
 426
 427 =head1 AUTHORS
 428
 429 Maintained by the LLVM Team (L<http://llvm.org>).
 430
 431 =cut