docs/CommandGuide/man/man1/llvmc.1

.\" 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>).