| .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 |
| .\" |
| .\" Standard preamble: |
| .\" ======================================================================== |
| .de Sh \" Subsection heading |
| .br |
| .if t .Sp |
| .ne 5 |
| .PP |
| \fB\\$1\fR |
| .PP |
| .. |
| .de Sp \" Vertical space (when we can't use .PP) |
| .if t .sp .5v |
| .if n .sp |
| .. |
| .de Vb \" Begin verbatim text |
| .ft CW |
| .nf |
| .ne \\$1 |
| .. |
| .de Ve \" End verbatim text |
| .ft R |
| .fi |
| .. |
| .\" Set up some character translations and predefined strings. \*(-- will |
| .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| .\" double quote, and \*(R" will give a right double quote. | will give a |
| .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
| .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
| .\" expand to `' in nroff, nothing in troff, for use with C<>. |
| .tr \(*W-|\(bv\*(Tr |
| .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| .ie n \{\ |
| . ds -- \(*W- |
| . ds PI pi |
| . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| . ds L" "" |
| . ds R" "" |
| . ds C` "" |
| . ds C' "" |
| 'br\} |
| .el\{\ |
| . ds -- \|\(em\| |
| . ds PI \(*p |
| . ds L" `` |
| . ds R" '' |
| 'br\} |
| .\" |
| .\" If the F register is turned on, we'll generate index entries on stderr for |
| .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
| .\" entries marked with X<> in POD. Of course, you'll have to process the |
| .\" output yourself in some meaningful fashion. |
| .if \nF \{\ |
| . de IX |
| . tm Index:\\$1\t\\n%\t"\\$2" |
| .. |
| . nr % 0 |
| . rr F |
| .\} |
| .\" |
| .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| .\" way too many mistakes in technical documents. |
| .hy 0 |
| .if n .na |
| .\" |
| .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| .\" Fear. Run. Save yourself. No user-serviceable parts. |
| . \" fudge factors for nroff and troff |
| .if n \{\ |
| . ds #H 0 |
| . ds #V .8m |
| . ds #F .3m |
| . ds #[ \f1 |
| . ds #] \fP |
| .\} |
| .if t \{\ |
| . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| . ds #V .6m |
| . ds #F 0 |
| . ds #[ \& |
| . ds #] \& |
| .\} |
| . \" simple accents for nroff and troff |
| .if n \{\ |
| . ds ' \& |
| . ds ` \& |
| . ds ^ \& |
| . ds , \& |
| . ds ~ ~ |
| . ds / |
| .\} |
| .if t \{\ |
| . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| .\} |
| . \" troff and (daisy-wheel) nroff accents |
| .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| .ds ae a\h'-(\w'a'u*4/10)'e |
| .ds Ae A\h'-(\w'A'u*4/10)'E |
| . \" corrections for vroff |
| .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| . \" for low resolution devices (crt and lpr) |
| .if \n(.H>23 .if \n(.V>19 \ |
| \{\ |
| . ds : e |
| . ds 8 ss |
| . ds o a |
| . ds d- d\h'-1'\(ga |
| . ds D- D\h'-1'\(hy |
| . ds th \o'bp' |
| . ds Th \o'LP' |
| . ds ae ae |
| . ds Ae AE |
| .\} |
| .rm #[ #] #H #V #F C |
| .\" ======================================================================== |
| .\" |
| .IX Title "LLVMC 1" |
| .TH LLVMC 1 "2007-02-11" "CVS" "LLVM Command Guide" |
| .SH "NAME" |
| llvmc \- The LLVM Compiler Driver (experimental) |
| .SH "SYNOPSIS" |
| .IX Header "SYNOPSIS" |
| \&\fBllvmc\fR [\fIoptions\fR] [\fIfilenames\fR...] |
| .SH "DESCRIPTION" |
| .IX Header "DESCRIPTION" |
| \&\fBllvmc\fR is a configurable driver for invoking other \s-1LLVM\s0 (and non\-LLVM) tools |
| in order to compile, optimize and link software for multiple languages. For |
| those familiar with \s-1FSF\s0's \fBgcc\fR tool, it is very similar. Please note that |
| \&\fBllvmc\fR is considered an experimental tool. \fBllvmc\fR has the following goals: |
| .IP "* provide a single point of access to the \s-1LLVM\s0 tool set," 4 |
| .IX Item "provide a single point of access to the LLVM tool set," |
| .PD 0 |
| .IP "* hide the complexities of the \s-1LLVM\s0 tools through a single interface," 4 |
| .IX Item "hide the complexities of the LLVM tools through a single interface," |
| .IP "* make integration of existing non-LLVM tools simple," 4 |
| .IX Item "make integration of existing non-LLVM tools simple," |
| .IP "* extend the capabilities of minimal front ends, and" 4 |
| .IX Item "extend the capabilities of minimal front ends, and" |
| .IP "* make the interface for compiling consistent for all languages." 4 |
| .IX Item "make the interface for compiling consistent for all languages." |
| .PD |
| .PP |
| The tool itself does nothing with a user's program. It merely invokes other |
| tools to get the compilation tasks done. |
| .PP |
| The options supported by \fBllvmc\fR 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 \s-1LLVM\s0. |
| Without \fBllvmc\fR, developers would need to understand how to invoke the |
| front-end compiler, optimizer, assembler, and linker in order to compile their |
| programs. \fBllvmc\fR's sole mission is to trivialize that process. |
| .Sh "Basic Operation" |
| .IX Subsection "Basic Operation" |
| \&\fBllvmc\fR always takes the following basic actions: |
| .IP "* Command line options and filenames are collected." 4 |
| .IX Item "Command line options and filenames are collected." |
| The command line options provide the marching orders to \fBllvmc\fR on what actions |
| it should perform. This is the \fIrequest\fR the user is making of \fBllvmc\fR and it |
| is interpreted first. |
| .IP "* Configuration files are read." 4 |
| .IX Item "Configuration files are read." |
| Based on the options and the suffixes of the filenames presented, a set of |
| configuration files are read to configure the actions \fBllvmc\fR will take. |
| Configuration files are provided by either \s-1LLVM\s0 or the front end compiler tools |
| that \fBllvmc\fR invokes. Users generally don't need to be concerned with the |
| contents of the configuration files. |
| .IP "* Determine actions to take." 4 |
| .IX Item "Determine actions to take." |
| The tool chain needed to complete the task is determined. This is the primary |
| work of \fBllvmc\fR. It breaks the request specified by the command line options |
| into a set of basic actions to be done: |
| .RS 4 |
| .IP "* Pre\-processing: gathering/filtering compiler input (optional)." 4 |
| .IX Item "Pre-processing: gathering/filtering compiler input (optional)." |
| .PD 0 |
| .IP "* Translation: source language to bytecode conversion." 4 |
| .IX Item "Translation: source language to bytecode conversion." |
| .IP "* Assembly: bytecode to native code conversion." 4 |
| .IX Item "Assembly: bytecode to native code conversion." |
| .IP "* Optimization: conversion of bytecode to something that runs faster." 4 |
| .IX Item "Optimization: conversion of bytecode to something that runs faster." |
| .IP "* Linking: combining multiple bytecodes to produce executable program." 4 |
| .IX Item "Linking: combining multiple bytecodes to produce executable program." |
| .RE |
| .RS 4 |
| .RE |
| .IP "* Execute actions." 4 |
| .IX Item "Execute actions." |
| .PD |
| The actions determined previously are executed sequentially and then |
| \&\fBllvmc\fR terminates. |
| .SH "OPTIONS" |
| .IX Header "OPTIONS" |
| .Sh "Control Options" |
| .IX Subsection "Control Options" |
| Control options tell \fBllvmc\fR what to do at a high level. The |
| following control options are defined: |
| .IP "\fB\-c\fR or \fB\-\-compile\fR" 4 |
| .IX Item "-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. |
| .IP "\fB\-k\fR or \fB\-\-link\fR or default" 4 |
| .IX Item "-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. |
| .IP "\fB\-S\fR" 4 |
| .IX Item "-S" |
| This option specifies that compilation should end in the creation of |
| an \s-1LLVM\s0 assembly file that can be later converted to an \s-1LLVM\s0 object |
| file. |
| .IP "\fB\-E\fR" 4 |
| .IX Item "-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. |
| .Sh "Optimization Options" |
| .IX Subsection "Optimization Options" |
| Optimization with \fBllvmc\fR 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. |
| .IP "\fB\-O1\fR or \fB\-O0\fR (default, fast compilation)" 4 |
| .IX Item "-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. |
| .IP "\fB\-O2\fR (basic optimization)" 4 |
| .IX Item "-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. |
| .IP "\fB\-O3\fR (aggressive optimization)" 4 |
| .IX Item "-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 \fB\-O1\fR and \fB\-O2\fR 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 \s-1IPO\s0. |
| .IP "\fB\-O4\fR (link time optimization)" 4 |
| .IX Item "-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. |
| .IP "\fB\-O5\fR (aggressive link time optimization)" 4 |
| .IX Item "-O5 (aggressive link time optimization)" |
| This is the same as \fB\-O4\fR except it employs aggressive analyses and |
| aggressive inter-procedural optimization. |
| .IP "\fB\-O6\fR (profile guided optimization: not implemented)" 4 |
| .IX Item "-O6 (profile guided optimization: not implemented)" |
| This is the same as \fB\-O5\fR 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. |
| .IP "\fB\-O7\fR (lifelong optimization: not implemented)" 4 |
| .IX Item "-O7 (lifelong optimization: not implemented)" |
| This is the same as \fB\-O5\fR and similar to \fB\-O6\fR 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. |
| .Sh "Input Options" |
| .IX Subsection "Input Options" |
| .IP "\fB\-l\fR \fI\s-1LIBRARY\s0\fR" 4 |
| .IX Item "-l LIBRARY" |
| This option instructs \fBllvmc\fR to locate a library named \fI\s-1LIBRARY\s0\fR and search |
| it for unresolved symbols when linking the program. |
| .IP "\fB\-L\fR \fIpath\fR" 4 |
| .IX Item "-L path" |
| This option instructs \fBllvmc\fR to add \fIpath\fR to the list of places in which |
| the linker will |
| .IP "\fB\-x\fR \fI\s-1LANGUAGE\s0\fR" 4 |
| .IX Item "-x LANGUAGE" |
| This option instructs \fBllvmc\fR to regard the following input files as |
| containing programs in the language \fI\s-1LANGUAGE\s0\fR. Normally, input file languages |
| are identified by their suffix but this option will override that default |
| behavior. The \fB\-x\fR option stays in effect until the end of the options or |
| a new \fB\-x\fR option is encountered. |
| .Sh "Output Options" |
| .IX Subsection "Output Options" |
| .IP "\fB\-m\fR\fIarch\fR" 4 |
| .IX Item "-march" |
| This option selects the back end code generator to use. The \fIarch\fR portion |
| of the option names the back end to use. |
| .IP "\fB\-\-native\fR" 4 |
| .IX Item "--native" |
| Normally, \fBllvmc\fR produces bytecode files at most stages of compilation. |
| With this option, \fBllvmc\fR will arrange for native object files to be |
| generated with the \fB\-c\fR option, native assembly files to be generated |
| with the \fB\-S\fR option, and native executables to be generated with the |
| \&\fB\-\-link\fR option. In the case of the \fB\-E\fR option, the output will not |
| differ as there is no \fInative\fR version of pre-processed output. |
| .IP "\fB\-o\fR \fIfilename\fR" 4 |
| .IX Item "-o filename" |
| Specify the output file name. The contents of the file depend on other |
| options. |
| .Sh "Information Options" |
| .IX Subsection "Information Options" |
| .IP "\fB\-n\fR or \fB\-\-no\-op\fR" 4 |
| .IX Item "-n or --no-op" |
| This option tells \fBllvmc\fR to do everything but actually execute the |
| resulting tools. In combination with the \fB\-v\fR option, this causes \fBllvmc\fR |
| to merely print out what it would have done. |
| .IP "\fB\-v\fR or \fB\-\-verbose\fR" 4 |
| .IX Item "-v or --verbose" |
| This option will cause \fBllvmc\fR 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. |
| .IP "\fB\-\-stats\fR" 4 |
| .IX Item "--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. |
| .IP "\fB\-\-time\-passes\fR" 4 |
| .IX Item "--time-passes" |
| Record the amount of time needed for each optimization pass and print it |
| to standard error. Like \fB\-\-stats\fR this option is just passed through to |
| the sub-tools to do with as they please. |
| .IP "\fB\-\-time\-programs\fR" 4 |
| .IX Item "--time-programs" |
| Record the amount of time each program (compilation tool) takes and print |
| it to the standard error. |
| .Sh "Language Specific Options" |
| .IX Subsection "Language Specific Options" |
| .IP "\fB\-T,pre\fR=\fIoptions\fR" 4 |
| .IX Item "-T,pre=options" |
| Pass an arbitrary option to the pre\-processor. |
| .IP "\fB\-T,opt\fR=\fIoptions\fR" 4 |
| .IX Item "-T,opt=options" |
| Pass an arbitrary option to the optimizer. |
| .IP "\fB\-T,lnk\fR=\fIoptions\fR" 4 |
| .IX Item "-T,lnk=options" |
| Pass an arbitrary option to the linker. |
| .IP "\fB\-T,asm\fR=\fIoptions\fR" 4 |
| .IX Item "-T,asm=options" |
| Pass an arbitrary option to the code generator. |
| .Sh "C/\*(C+ Specific Options" |
| .IX Subsection "C/ Specific Options" |
| .IP "\fB\-I\fR\fIpath\fR" 4 |
| .IX Item "-Ipath" |
| This option is just passed through to a C or \*(C+ front end compiler to tell it |
| where include files can be found. |
| .IP "\fB\-D\fR\fIsymbol\fR" 4 |
| .IX Item "-Dsymbol" |
| This option is just passed through to a C or \*(C+ front end compiler to tell it |
| to define a symbol. |
| .Sh "Miscellaneous Options" |
| .IX Subsection "Miscellaneous Options" |
| .IP "\fB\-\-help\fR" 4 |
| .IX Item "--help" |
| Print a summary of command line options. |
| .IP "\fB\-\-version\fR" 4 |
| .IX Item "--version" |
| This option will cause \fBllvmc\fR to print out its version number and terminate. |
| .Sh "Advanced Options" |
| .IX Subsection "Advanced Options" |
| You better know what you're doing if you use these options. Improper use |
| of these options can produce drastically wrong results. |
| .IP "\fB\-\-config\-dir\fR \fIdirname\fR" 4 |
| .IX Item "--config-dir dirname" |
| This option tells \fBllvmc\fR to read configuration data from the \fIdirectory\fR |
| named \fIdirname\fR. 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. |
| .Sh "Unimplemented Options" |
| .IX Subsection "Unimplemented Options" |
| The options below are not currently implemented in \fBllvmc\fR but will be |
| eventually. They are documented here as \*(L"future design\*(R". |
| .IP "\fB\-\-show\-config\fR \fI[suffixes...]\fR" 4 |
| .IX Item "--show-config [suffixes...]" |
| When this option is given, the only action taken by \fBllvmc\fR 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 \fBllvmc\fR. |
| .IP "\fB\-\-config\fR :\fIsection\fR:\fIname\fR=\fIvalue\fR" 4 |
| .IX Item "--config :section:name=value" |
| This option instructs \fBllvmc\fR to accept \fIvalue\fR as the value for configuration |
| item \fIname\fR in the section named \fIsection\fR. This is a quick way to override |
| a configuration item on the command line without resorting to changing the |
| configuration files. |
| .IP "\fB\-\-config\-only\-from\fR \fIdirname\fR" 4 |
| .IX Item "--config-only-from dirname" |
| This option tells \fBllvmc\fR to skip the normal processing of configuration |
| files and only configure from the contents of the \fIdirname\fR directory. Multiple |
| \&\fB\-\-config\-only\-from\fR options may be given in which case the directories are |
| read in the order given on the command line. |
| .IP "\fB\-\-emit\-raw\-code\fR" 4 |
| .IX Item "--emit-raw-code" |
| No optimization is done whatsoever. The compilers invoked by \fBllvmc\fR 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 \fB\-O\fR options. This is distinctly different from |
| the \fB\-O0\fR option (a synonym for \fB\-O1\fR) because those optimizations will |
| reduce code size to make compilation faster. With \fB\-\-emit\-raw\-code\fR, only |
| the full raw code produced by the compiler will be generated. |
| .SH "EXIT STATUS" |
| .IX Header "EXIT STATUS" |
| If \fBllvmc\fR 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 \fBllvmc\fR will return the |
| same result code as the failing compilation tool. |
| .SH "DEFICIENCIES" |
| .IX Header "DEFICIENCIES" |
| \&\fBllvmc\fR is considered an experimental \s-1LLVM\s0 tool because it has these |
| deficiencies: |
| .IP "Insufficient support for native linking" 4 |
| .IX Item "Insufficient support for native linking" |
| Because \fBllvm-ld\fR doesn't handle native linking, neither can \fBllvmc\fR |
| .IP "Poor configuration support" 4 |
| .IX Item "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. |
| .IP "Does not handle target specific configurations" 4 |
| .IX Item "Does not handle target specific configurations" |
| This is one of the major deficiencies, also addressed in |
| <http://llvm.org/PR686> |
| .SH "SEE ALSO" |
| .IX Header "SEE ALSO" |
| llvm-as, llvm-dis, llc, llvm-link |
| .SH "AUTHORS" |
| .IX Header "AUTHORS" |
| Maintained by the \s-1LLVM\s0 Team (<http://llvm.org>). |