diff options
Diffstat (limited to 'docs/CommandGuide/man/man1/llvmc.1')
| -rw-r--r-- | docs/CommandGuide/man/man1/llvmc.1 | 455 |
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>). |