2.0 Release docsrelease_20

git-svn-id: https://llvm.org/svn/llvm-project/llvm/branches/release_20@37312 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 455 insertions, 0 deletions

diff --git a/docs/CommandGuide/man/man1/llvmc.1 b/docs/CommandGuide/man/man1/llvmc.1
new file mode 100644
index 0000000000..9506c5e495
--- /dev/null
+++ b/docs/CommandGuide/man/man1/llvmc.1
@@ -0,0 +1,455 @@
+.\" 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>).