diff options
Diffstat (limited to 'docs/main/CommandGuide')
24 files changed, 4057 insertions, 0 deletions
diff --git a/docs/main/CommandGuide/FileCheck.pod b/docs/main/CommandGuide/FileCheck.pod new file mode 100644 index 0000000..433979a --- /dev/null +++ b/docs/main/CommandGuide/FileCheck.pod @@ -0,0 +1,245 @@ + +=pod + +=head1 NAME + +FileCheck - Flexible pattern matching file verifier + +=head1 SYNOPSIS + +B<FileCheck> I<match-filename> [I<--check-prefix=XXX>] [I<--strict-whitespace>] + +=head1 DESCRIPTION + +B<FileCheck> reads two files (one from standard input, and one specified on the +command line) and uses one to verify the other. This behavior is particularly +useful for the testsuite, which wants to verify that the output of some tool +(e.g. llc) contains the expected information (for example, a movsd from esp or +whatever is interesting). This is similar to using grep, but it is optimized +for matching multiple different inputs in one file in a specific order. + +The I<match-filename> file specifies the file that contains the patterns to +match. The file to verify is always read from standard input. + +=head1 OPTIONS + +=over + +=item B<-help> + +Print a summary of command line options. + +=item B<--check-prefix> I<prefix> + +FileCheck searches the contents of I<match-filename> for patterns to match. By +default, these patterns are prefixed with "CHECK:". If you'd like to use a +different prefix (e.g. because the same input file is checking multiple +different tool or options), the B<--check-prefix> argument allows you to specify +a specific prefix to match. + +=item B<--strict-whitespace> + +By default, FileCheck canonicalizes input horizontal whitespace (spaces and +tabs) which causes it to ignore these differences (a space will match a tab). +The --strict-whitespace argument disables this behavior. + +=item B<-version> + +Show the version number of this program. + +=back + +=head1 EXIT STATUS + +If B<FileCheck> verifies that the file matches the expected contents, it exits +with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero +value. + +=head1 TUTORIAL + +FileCheck is typically used from LLVM regression tests, being invoked on the RUN +line of the test. A simple example of using FileCheck from a RUN line looks +like this: + + ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s + +This syntax says to pipe the current file ("%s") into llvm-as, pipe that into +llc, then pipe the output of llc into FileCheck. This means that FileCheck will +be verifying its standard input (the llc output) against the filename argument +specified (the original .ll file specified by "%s"). To see how this works, +lets look at the rest of the .ll file (after the RUN line): + + define void @sub1(i32* %p, i32 %v) { + entry: + ; <b>CHECK: sub1:</b> + ; <b>CHECK: subl</b> + %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) + ret void + } + + define void @inc4(i64* %p) { + entry: + ; <b>CHECK: inc4:</b> + ; <b>CHECK: incq</b> + %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1) + ret void + } + +Here you can see some "CHECK:" lines specified in comments. Now you can see +how the file is piped into llvm-as, then llc, and the machine code output is +what we are verifying. FileCheck checks the machine code output to verify that +it matches what the "CHECK:" lines specify. + +The syntax of the CHECK: lines is very simple: they are fixed strings that +must occur in order. FileCheck defaults to ignoring horizontal whitespace +differences (e.g. a space is allowed to match a tab) but otherwise, the contents +of the CHECK: line is required to match some thing in the test file exactly. + +One nice thing about FileCheck (compared to grep) is that it allows merging +test cases together into logical groups. For example, because the test above +is checking for the "sub1:" and "inc4:" labels, it will not match unless there +is a "subl" in between those labels. If it existed somewhere else in the file, +that would not count: "grep subl" matches if subl exists anywhere in the +file. + + + +=head2 The FileCheck -check-prefix option + +The FileCheck -check-prefix option allows multiple test configurations to be +driven from one .ll file. This is useful in many circumstances, for example, +testing different architectural variants with llc. Here's a simple example: + + ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \ + ; RUN: | <b>FileCheck %s -check-prefix=X32</b> + ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ + ; RUN: | <b>FileCheck %s -check-prefix=X64</b> + + define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind { + %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1 + ret <4 x i32> %tmp1 + ; <b>X32:</b> pinsrd_1: + ; <b>X32:</b> pinsrd $1, 4(%esp), %xmm0 + + ; <b>X64:</b> pinsrd_1: + ; <b>X64:</b> pinsrd $1, %edi, %xmm0 + } + +In this case, we're testing that we get the expected code generation with +both 32-bit and 64-bit code generation. + + + +=head2 The "CHECK-NEXT:" directive + +Sometimes you want to match lines and would like to verify that matches +happen on exactly consequtive lines with no other lines in between them. In +this case, you can use CHECK: and CHECK-NEXT: directives to specify this. If +you specified a custom check prefix, just use "<PREFIX>-NEXT:". For +example, something like this works as you'd expect: + + define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) { + %tmp3 = load <2 x double>* %A, align 16 + %tmp7 = insertelement <2 x double> undef, double %B, i32 0 + %tmp9 = shufflevector <2 x double> %tmp3, + <2 x double> %tmp7, + <2 x i32> < i32 0, i32 2 > + store <2 x double> %tmp9, <2 x double>* %r, align 16 + ret void + + ; <b>CHECK:</b> t2: + ; <b>CHECK:</b> movl 8(%esp), %eax + ; <b>CHECK-NEXT:</b> movapd (%eax), %xmm0 + ; <b>CHECK-NEXT:</b> movhpd 12(%esp), %xmm0 + ; <b>CHECK-NEXT:</b> movl 4(%esp), %eax + ; <b>CHECK-NEXT:</b> movapd %xmm0, (%eax) + ; <b>CHECK-NEXT:</b> ret + } + +CHECK-NEXT: directives reject the input unless there is exactly one newline +between it an the previous directive. A CHECK-NEXT cannot be the first +directive in a file. + + + +=head2 The "CHECK-NOT:" directive + +The CHECK-NOT: directive is used to verify that a string doesn't occur +between two matches (or the first match and the beginning of the file). For +example, to verify that a load is removed by a transformation, a test like this +can be used: + + define i8 @coerce_offset0(i32 %V, i32* %P) { + store i32 %V, i32* %P + + %P2 = bitcast i32* %P to i8* + %P3 = getelementptr i8* %P2, i32 2 + + %A = load i8* %P3 + ret i8 %A + ; <b>CHECK:</b> @coerce_offset0 + ; <b>CHECK-NOT:</b> load + ; <b>CHECK:</b> ret i8 + } + + + +=head2 FileCheck Pattern Matching Syntax + +The CHECK: and CHECK-NOT: directives both take a pattern to match. For most +uses of FileCheck, fixed string matching is perfectly sufficient. For some +things, a more flexible form of matching is desired. To support this, FileCheck +allows you to specify regular expressions in matching strings, surrounded by +double braces: B<{{yourregex}}>. Because we want to use fixed string +matching for a majority of what we do, FileCheck has been designed to support +mixing and matching fixed string matching with regular expressions. This allows +you to write things like this: + + ; CHECK: movhpd <b>{{[0-9]+}}</b>(%esp), <b>{{%xmm[0-7]}}</b> + +In this case, any offset from the ESP register will be allowed, and any xmm +register will be allowed. + +Because regular expressions are enclosed with double braces, they are +visually distinct, and you don't need to use escape characters within the double +braces like you would in C. In the rare case that you want to match double +braces explicitly from the input, you can use something ugly like +B<{{[{][{]}}> as your pattern. + + + +=head2 FileCheck Variables + +It is often useful to match a pattern and then verify that it occurs again +later in the file. For codegen tests, this can be useful to allow any register, +but verify that that register is used consistently later. To do this, FileCheck +allows named variables to be defined and substituted into patterns. Here is a +simple example: + + ; CHECK: test5: + ; CHECK: notw <b>[[REGISTER:%[a-z]+]]</b> + ; CHECK: andw {{.*}}<b>[[REGISTER]]</b> + +The first check line matches a regex (<tt>%[a-z]+</tt>) and captures it into +the variables "REGISTER". The second line verifies that whatever is in REGISTER +occurs later in the file after an "andw". FileCheck variable references are +always contained in <tt>[[ ]]</tt> pairs, are named, and their names can be +formed with the regex "<tt>[a-zA-Z_][a-zA-Z0-9_]*</tt>". If a colon follows the +name, then it is a definition of the variable, if not, it is a use. + +FileCheck variables can be defined multiple times, and uses always get the +latest value. Note that variables are all read at the start of a "CHECK" line +and are all defined at the end. This means that if you have something like +"<tt>CHECK: [[XYZ:.*]]x[[XYZ]]<tt>" that the check line will read the previous +value of the XYZ variable and define a new one after the match is performed. If +you need to do something like this you can probably take advantage of the fact +that FileCheck is not actually line-oriented when it matches, this allows you to +define two separate CHECK lines that match on the same line. + + + +=head1 AUTHORS + +Maintained by The LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/bugpoint.pod b/docs/main/CommandGuide/bugpoint.pod new file mode 100644 index 0000000..7afeea1 --- /dev/null +++ b/docs/main/CommandGuide/bugpoint.pod @@ -0,0 +1,167 @@ +=pod + +=head1 NAME + +bugpoint - automatic test case reduction tool + +=head1 SYNOPSIS + +B<bugpoint> [I<options>] [I<input LLVM ll/bc files>] [I<LLVM passes>] B<--args> +I<program arguments> + +=head1 DESCRIPTION + +B<bugpoint> narrows down the source of problems in LLVM tools and passes. It +can be used to debug three types of failures: optimizer crashes, miscompilations +by optimizers, or bad native code generation (including problems in the static +and JIT compilers). It aims to reduce large test cases to small, useful ones. +For more information on the design and inner workings of B<bugpoint>, as well as +advice for using bugpoint, see F<llvm/docs/Bugpoint.html> in the LLVM +distribution. + +=head1 OPTIONS + +=over + +=item B<--additional-so> F<library> + +Load the dynamic shared object F<library> into the test program whenever it is +run. This is useful if you are debugging programs which depend on non-LLVM +libraries (such as the X or curses libraries) to run. + +=item B<--append-exit-code>=I<{true,false}> + +Append the test programs exit code to the output file so that a change in exit +code is considered a test failure. Defaults to false. + +=item B<--args> I<program args> + +Pass all arguments specified after -args to the test program whenever it runs. +Note that if any of the I<program args> start with a '-', you should use: + + bugpoint [bugpoint args] --args -- [program args] + +The "--" right after the B<--args> option tells B<bugpoint> to consider any +options starting with C<-> to be part of the B<--args> option, not as options to +B<bugpoint> itself. + +=item B<--tool-args> I<tool args> + +Pass all arguments specified after --tool-args to the LLVM tool under test +(B<llc>, B<lli>, etc.) whenever it runs. You should use this option in the +following way: + + bugpoint [bugpoint args] --tool-args -- [tool args] + +The "--" right after the B<--tool-args> option tells B<bugpoint> to consider any +options starting with C<-> to be part of the B<--tool-args> option, not as +options to B<bugpoint> itself. (See B<--args>, above.) + +=item B<--safe-tool-args> I<tool args> + +Pass all arguments specified after B<--safe-tool-args> to the "safe" execution +tool. + +=item B<--gcc-tool-args> I<gcc tool args> + +Pass all arguments specified after B<--gcc-tool-args> to the invocation of +B<gcc>. + +=item B<--disable-{dce,simplifycfg}> + +Do not run the specified passes to clean up and reduce the size of the test +program. By default, B<bugpoint> uses these passes internally when attempting to +reduce test programs. If you're trying to find a bug in one of these passes, +B<bugpoint> may crash. + +=item B<--enable-valgrind> + +Use valgrind to find faults in the optimization phase. This will allow +bugpoint to find otherwise asymptomatic problems caused by memory +mis-management. + +=item B<-find-bugs> + +Continually randomize the specified passes and run them on the test program +until a bug is found or the user kills B<bugpoint>. + +=item B<-help> + +Print a summary of command line options. + +=item B<--input> F<filename> + +Open F<filename> and redirect the standard input of the test program, whenever +it runs, to come from that file. + +=item B<--load> F<plugin> + +Load the dynamic object F<plugin> into B<bugpoint> itself. This object should +register new optimization passes. Once loaded, the object will add new command +line options to enable various optimizations. To see the new complete list of +optimizations, use the B<-help> and B<--load> options together; for example: + + bugpoint --load myNewPass.so -help + +=item B<--mlimit> F<megabytes> + +Specifies an upper limit on memory usage of the optimization and codegen. Set +to zero to disable the limit. + +=item B<--output> F<filename> + +Whenever the test program produces output on its standard output stream, it +should match the contents of F<filename> (the "reference output"). If you +do not use this option, B<bugpoint> will attempt to generate a reference output +by compiling the program with the "safe" backend and running it. + +=item B<--profile-info-file> F<filename> + +Profile file loaded by B<--profile-loader>. + +=item B<--run-{int,jit,llc,cbe,custom}> + +Whenever the test program is compiled, B<bugpoint> should generate code for it +using the specified code generator. These options allow you to choose the +interpreter, the JIT compiler, the static native code compiler, the C +backend, or a custom command (see B<--exec-command>) respectively. + +=item B<--safe-{llc,cbe,custom}> + +When debugging a code generator, B<bugpoint> should use the specified code +generator as the "safe" code generator. This is a known-good code generator +used to generate the "reference output" if it has not been provided, and to +compile portions of the program that as they are excluded from the testcase. +These options allow you to choose the +static native code compiler, the C backend, or a custom command, +(see B<--exec-command>) respectively. The interpreter and the JIT backends +cannot currently be used as the "safe" backends. + +=item B<--exec-command> I<command> + +This option defines the command to use with the B<--run-custom> and +B<--safe-custom> options to execute the bitcode testcase. This can +be useful for cross-compilation. + +=item B<--safe-path> I<path> + +This option defines the path to the command to execute with the +B<--safe-{int,jit,llc,cbe,custom}> +option. + +=back + +=head1 EXIT STATUS + +If B<bugpoint> succeeds in finding a problem, it will exit with 0. Otherwise, +if an error occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<opt|opt> + +=head1 AUTHOR + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/html/manpage.css b/docs/main/CommandGuide/html/manpage.css new file mode 100644 index 0000000..b200343 --- /dev/null +++ b/docs/main/CommandGuide/html/manpage.css @@ -0,0 +1,256 @@ +/* Based on http://www.perldoc.com/css/perldoc.css */ + +@import url("../llvm.css"); + +body { font-family: Arial,Helvetica; } + +blockquote { margin: 10pt; } + +h1, a { color: #336699; } + + +/*** Top menu style ****/ +.mmenuon { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ff6600; font-size: 10pt; + } +.mmenuoff { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: 10pt; +} +.cpyright { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: xx-small; +} +.cpyrightText { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: xx-small; +} +.sections { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 11pt; +} +.dsections { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 12pt; +} +.slink { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #000000; font-size: 9pt; +} + +.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; } + +.maintitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 18pt; +} +.dblArrow { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: small; +} +.menuSec { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: small; +} + +.newstext { + font-family: Arial,Helvetica; font-size: small; +} + +.linkmenu { + font-family: Arial,Helvetica; color: #000000; font-weight: bold; + text-decoration: none; +} + +P { + font-family: Arial,Helvetica; +} + +PRE { + font-size: 10pt; +} +.quote { + font-family: Times; text-decoration: none; + color: #000000; font-size: 9pt; font-style: italic; +} +.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; } +.std { font-family: Arial,Helvetica; color: #000000; } +.meerkatTitle { + font-family: sans-serif; font-size: x-small; color: black; } + +.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black } +.meerkatCategory { + font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic; + color: brown; } +.meerkatChannel { + font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; } +.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; } + +.tocTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 10pt; +} + +.toc-item { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; text-decoration: underline; +} + +.perlVersion { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; text-decoration: none; +} + +.podTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #000000; +} + +.docTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #000000; font-size: 10pt; +} +.dotDot { + font-family: Arial,Helvetica; font-weight: bold; + color: #000000; font-size: 9pt; +} + +.docSec { + font-family: Arial,Helvetica; font-weight: normal; + color: #333333; font-size: 9pt; +} +.docVersion { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 10pt; +} + +.docSecs-on { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #ff0000; font-size: 10pt; +} +.docSecs-off { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #333333; font-size: 10pt; +} + +h2 { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: medium; +} +h1 { + font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: large; +} + +DL { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #333333; font-size: 10pt; +} + +UL > LI > A { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; +} + +.moduleInfo { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 11pt; +} + +.moduleInfoSec { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 10pt; +} + +.moduleInfoVal { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline; + color: #000000; font-size: 10pt; +} + +.cpanNavTitle { + font-family: Arial,Helvetica; font-weight: bold; + color: #ffffff; font-size: 10pt; +} +.cpanNavLetter { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 9pt; +} +.cpanCat { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 9pt; +} + +.bttndrkblue-bkgd-top { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif); +} +.bttndrkblue-bkgd-left { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif); +} +.bttndrkblue-bkgd { + padding-top: 0px; + padding-bottom: 0px; + margin-bottom: 0px; + margin-top: 0px; + background-repeat: no-repeat; + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif); + vertical-align: top; +} +.bttndrkblue-bkgd-right { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif); +} +.bttndrkblue-bkgd-bottom { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif); +} +.bttndrkblue-text a { + color: #ffffff; + text-decoration: none; +} +a.bttndrkblue-text:hover { + color: #ffDD3C; + text-decoration: none; +} +.bg-ltblue { + background-color: #f0f5fa; +} + +.border-left-b { + background: #f0f5fa url(/i/corner-leftline.gif) repeat-y; +} + +.border-right-b { + background: #f0f5fa url(/i/corner-rightline.gif) repeat-y; +} + +.border-top-b { + background: #f0f5fa url(/i/corner-topline.gif) repeat-x; +} + +.border-bottom-b { + background: #f0f5fa url(/i/corner-botline.gif) repeat-x; +} + +.border-right-w { + background: #ffffff url(/i/corner-rightline.gif) repeat-y; +} + +.border-top-w { + background: #ffffff url(/i/corner-topline.gif) repeat-x; +} + +.border-bottom-w { + background: #ffffff url(/i/corner-botline.gif) repeat-x; +} + +.bg-white { + background-color: #ffffff; +} + +.border-left-w { + background: #ffffff url(/i/corner-leftline.gif) repeat-y; +} diff --git a/docs/main/CommandGuide/index.html b/docs/main/CommandGuide/index.html new file mode 100644 index 0000000..7179675 --- /dev/null +++ b/docs/main/CommandGuide/index.html @@ -0,0 +1,155 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>LLVM Command Guide</title> + <link rel="stylesheet" href="../llvm.css" type="text/css"> +</head> +<body> + +<div class="doc_title"> + LLVM Command Guide +</div> + +<div class="doc_text"> + +<p>These documents are HTML versions of the <a href="man/man1/">man pages</a> +for all of the LLVM tools. These pages describe how to use the LLVM commands +and what their options are. Note that these pages do not describe all of the +options available for all tools. To get a complete listing, pass the +<tt>-help</tt> (general options) or <tt>-help-hidden</tt> (general+debugging +options) arguments to the tool you are interested in.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="basic">Basic Commands</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<ul> + +<li><a href="llvm-as.html"><b>llvm-as</b></a> - + assemble a human-readable .ll file into bytecode</li> + +<li><a href="llvm-dis.html"><b>llvm-dis</b></a> - + disassemble a bytecode file into a human-readable .ll file</li> + +<li><a href="opt.html"><b>opt</b></a> - + run a series of LLVM-to-LLVM optimizations on a bytecode file</li> + +<li><a href="llc.html"><b>llc</b></a> - + generate native machine code for a bytecode file</li> + +<li><a href="lli.html"><b>lli</b></a> - + directly run a program compiled to bytecode using a JIT compiler or + interpreter</li> + +<li><a href="llvm-link.html"><b>llvm-link</b></a> - + link several bytecode files into one</li> + +<li><a href="llvm-ar.html"><b>llvm-ar</b></a> - + archive bytecode files</li> + +<li><a href="llvm-ranlib.html"><b>llvm-ranlib</b></a> - + create an index for archives made with llvm-ar</li> + +<li><a href="llvm-nm.html"><b>llvm-nm</b></a> - + print out the names and types of symbols in a bytecode file</li> + +<li><a href="llvm-prof.html"><b>llvm-prof</b></a> - + format raw `<tt>llvmprof.out</tt>' data into a human-readable report</li> + +<li><a href="llvm-ld.html"><b>llvm-ld</b></a> - + general purpose linker with loadable runtime optimization support</li> + +<li><a href="llvm-config.html"><b>llvm-config</b></a> - + print out LLVM compilation options, libraries, etc. as configured</li> + +<li><a href="llvmc.html"><b>llvmc</b></a> - + a generic customizable compiler driver</li> + +</ul> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="frontend">C and C++ Front-end Commands</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> +<ul> + +<li><a href="llvmgcc.html"><b>llvm-gcc</b></a> - + GCC-based C front-end for LLVM + +<li><a href="llvmgxx.html"><b>llvm-g++</b></a> - + GCC-based C++ front-end for LLVM</li> + +</ul> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="debug">Debugging Tools</a> +</div> +<!-- *********************************************************************** --> + + +<div class="doc_text"> + +<ul> + +<li><a href="bugpoint.html"><b>bugpoint</b></a> - + automatic test-case reducer</li> + +<li><a href="llvm-extract.html"><b>llvm-extract</b></a> - + extract a function from an LLVM bytecode file</li> + +<li><a href="llvm-bcanalyzer.html"><b>llvm-bcanalyzer</b></a> - + bytecode analyzer (analyzes the binary encoding itself, not the program it + represents)</li> + +</ul> +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="internal">Internal Tools</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> +<ul> + +<li><a href="FileCheck.html"><b>FileCheck</b></a> - + Flexible file verifier used extensively by the testing harness</li> +<li><a href="tblgen.html"><b>tblgen</b></a> - + target description reader and generator</li> +<li><a href="lit.html"><b>lit</b></a> - + LLVM Integrated Tester, for running tests</li> + +</ul> +</div> + +<!-- *********************************************************************** --> + +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> + + <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ +</address> + +</body> +</html> diff --git a/docs/main/CommandGuide/lit.pod b/docs/main/CommandGuide/lit.pod new file mode 100644 index 0000000..72d9d2b --- /dev/null +++ b/docs/main/CommandGuide/lit.pod @@ -0,0 +1,354 @@ +=pod + +=head1 NAME + +lit - LLVM Integrated Tester + +=head1 SYNOPSIS + +B<lit> [I<options>] [I<tests>] + +=head1 DESCRIPTION + +B<lit> is a portable tool for executing LLVM and Clang style test suites, +summarizing their results, and providing indication of failures. B<lit> is +designed to be a lightweight testing tool with as simple a user interface as +possible. + +B<lit> should be run with one or more I<tests> to run specified on the command +line. Tests can be either individual test files or directories to search for +tests (see L<"TEST DISCOVERY">). + +Each specified test will be executed (potentially in parallel) and once all +tests have been run B<lit> will print summary information on the number of tests +which passed or failed (see L<"TEST STATUS RESULTS">). The B<lit> program will +execute with a non-zero exit code if any tests fail. + +By default B<lit> will use a succinct progress display and will only print +summary information for test failures. See L<"OUTPUT OPTIONS"> for options +controlling the B<lit> progress display and output. + +B<lit> also includes a number of options for controlling how tests are exected +(specific features may depend on the particular test format). See L<"EXECUTION +OPTIONS"> for more information. + +Finally, B<lit> also supports additional options for only running a subset of +the options specified on the command line, see L<"SELECTION OPTIONS"> for +more information. + +Users interested in the B<lit> architecture or designing a B<lit> testing +implementation should see L<"LIT ARCHITECTURE"> + +=head1 GENERAL OPTIONS + +=over + +=item B<-h>, B<--help> + +Show the B<lit> help message. + +=item B<-j> I<N>, B<--threads>=I<N> + +Run I<N> tests in parallel. By default, this is automatically chosen to match +the number of detected available CPUs. + +=item B<--config-prefix>=I<NAME> + +Search for I<NAME.cfg> and I<NAME.site.cfg> when searching for test suites, +instead of I<lit.cfg> and I<lit.site.cfg>. + +=item B<--param> I<NAME>, B<--param> I<NAME>=I<VALUE> + +Add a user defined parameter I<NAME> with the given I<VALUE> (or the empty +string if not given). The meaning and use of these parameters is test suite +dependent. + +=back + +=head1 OUTPUT OPTIONS + +=over + +=item B<-q>, B<--quiet> + +Suppress any output except for test failures. + +=item B<-s>, B<--succinct> + +Show less output, for example don't show information on tests that pass. + +=item B<-v>, B<--verbose> + +Show more information on test failures, for example the entire test output +instead of just the test result. + +=item B<--no-progress-bar> + +Do not use curses based progress bar. + +=back + +=head1 EXECUTION OPTIONS + +=over + +=item B<--path>=I<PATH> + +Specify an addition I<PATH> to use when searching for executables in tests. + +=item B<--vg> + +Run individual tests under valgrind (using the memcheck tool). The +I<--error-exitcode> argument for valgrind is used so that valgrind failures will +cause the program to exit with a non-zero status. + +=item B<--vg-arg>=I<ARG> + +When I<--vg> is used, specify an additional argument to pass to valgrind itself. + +=item B<--time-tests> + +Track the wall time individual tests take to execute and includes the results in +the summary output. This is useful for determining which tests in a test suite +take the most time to execute. Note that this option is most useful with I<-j +1>. + +=back + +=head1 SELECTION OPTIONS + +=over + +=item B<--max-tests>=I<N> + +Run at most I<N> tests and then terminate. + +=item B<--max-time>=I<N> + +Spend at most I<N> seconds (approximately) running tests and then terminate. + +=item B<--shuffle> + +Run the tests in a random order. + +=back + +=head1 ADDITIONAL OPTIONS + +=over + +=item B<--debug> + +Run B<lit> in debug mode, for debugging configuration issues and B<lit> itself. + +=item B<--show-suites> + +List the discovered test suites as part of the standard output. + +=item B<--no-tcl-as-sh> + +Run Tcl scripts internally (instead of converting to shell scripts). + +=item B<--repeat>=I<N> + +Run each test I<N> times. Currently this is primarily useful for timing tests, +other results are not collated in any reasonable fashion. + +=back + +=head1 EXIT STATUS + +B<lit> will exit with an exit code of 1 if there are any FAIL or XPASS +results. Otherwise, it will exit with the status 0. Other exit codes used for +non-test related failures (for example a user error or an internal program +error). + +=head1 TEST DISCOVERY + +The inputs passed to B<lit> can be either individual tests, or entire +directories or hierarchies of tests to run. When B<lit> starts up, the first +thing it does is convert the inputs into a complete list of tests to run as part +of I<test discovery>. + +In the B<lit> model, every test must exist inside some I<test suite>. B<lit> +resolves the inputs specified on the command line to test suites by searching +upwards from the input path until it finds a I<lit.cfg> or I<lit.site.cfg> +file. These files serve as both a marker of test suites and as configuration +files which B<lit> loads in order to understand how to find and run the tests +inside the test suite. + +Once B<lit> has mapped the inputs into test suites it traverses the list of +inputs adding tests for individual files and recursively searching for tests in +directories. + +This behavior makes it easy to specify a subset of tests to run, while still +allowing the test suite configuration to control exactly how tests are +interpreted. In addition, B<lit> always identifies tests by the test suite they +are in, and their relative path inside the test suite. For appropriately +configured projects, this allows B<lit> to provide convenient and flexible +support for out-of-tree builds. + +=head1 TEST STATUS RESULTS + +Each test ultimately produces one of the following six results: + +=over + +=item B<PASS> + +The test succeeded. + +=item B<XFAIL> + +The test failed, but that is expected. This is used for test formats which allow +specifying that a test does not currently work, but wish to leave it in the test +suite. + +=item B<XPASS> + +The test succeeded, but it was expected to fail. This is used for tests which +were specified as expected to fail, but are now succeeding (generally because +the feautre they test was broken and has been fixed). + +=item B<FAIL> + +The test failed. + +=item B<UNRESOLVED> + +The test result could not be determined. For example, this occurs when the test +could not be run, the test itself is invalid, or the test was interrupted. + +=item B<UNSUPPORTED> + +The test is not supported in this environment. This is used by test formats +which can report unsupported tests. + +=back + +Depending on the test format tests may produce additional information about +their status (generally only for failures). See the L<Output|"LIT OUTPUT"> +section for more information. + +=head1 LIT INFRASTRUCTURE + +This section describes the B<lit> testing architecture for users interested in +creating a new B<lit> testing implementation, or extending an existing one. + +B<lit> proper is primarily an infrastructure for discovering and running +arbitrary tests, and to expose a single convenient interface to these +tests. B<lit> itself doesn't know how to run tests, rather this logic is +defined by I<test suites>. + +=head2 TEST SUITES + +As described in L<"TEST DISCOVERY">, tests are always located inside a I<test +suite>. Test suites serve to define the format of the tests they contain, the +logic for finding those tests, and any additional information to run the tests. + +B<lit> identifies test suites as directories containing I<lit.cfg> or +I<lit.site.cfg> files (see also B<--config-prefix>. Test suites are initially +discovered by recursively searching up the directory hierarchy for all the input +files passed on the command line. You can use B<--show-suites> to display the +discovered test suites at startup. + +Once a test suite is discovered, its config file is loaded. Config files +themselves are just Python modules which will be executed. When the config file +is executed, two important global variables are predefined: + +=over + +=item B<lit> + +The global B<lit> configuration object (a I<LitConfig> instance), which defines +the builtin test formats, global configuration parameters, and other helper +routines for implementing test configurations. + +=item B<config> + +This is the config object (a I<TestingConfig> instance) for the test suite, +which the config file is expected to populate. The following variables are also +available on the I<config> object, some of which must be set by the config and +others are optional or predefined: + +B<name> I<[required]> The name of the test suite, for use in reports and +diagnostics. + +B<test_format> I<[required]> The test format object which will be used to +discover and run tests in the test suite. Generally this will be a builtin test +format available from the I<lit.formats> module. + +B<test_src_root> The filesystem path to the test suite root. For out-of-dir +builds this is the directory that will be scanned for tests. + +B<test_exec_root> For out-of-dir builds, the path to the test suite root inside +the object directory. This is where tests will be run and temporary output files +places. + +B<environment> A dictionary representing the environment to use when executing +tests in the suite. + +B<suffixes> For B<lit> test formats which scan directories for tests, this +variable as a list of suffixes to identify test files. Used by: I<ShTest>, +I<TclTest>. + +B<substitutions> For B<lit> test formats which substitute variables into a test +script, the list of substitutions to perform. Used by: I<ShTest>, I<TclTest>. + +B<unsupported> Mark an unsupported directory, all tests within it will be +reported as unsupported. Used by: I<ShTest>, I<TclTest>. + +B<parent> The parent configuration, this is the config object for the directory +containing the test suite, or None. + +B<on_clone> The config is actually cloned for every subdirectory inside a test +suite, to allow local configuration on a per-directory basis. The I<on_clone> +variable can be set to a Python function which will be called whenever a +configuration is cloned (for a subdirectory). The function should takes three +arguments: (1) the parent configuration, (2) the new configuration (which the +I<on_clone> function will generally modify), and (3) the test path to the new +directory being scanned. + +=back + +=head2 TEST DISCOVERY + +Once test suites are located, B<lit> recursively traverses the source directory +(following I<test_src_root>) looking for tests. When B<lit> enters a +sub-directory, it first checks to see if a nest test suite is defined in that +directory. If so, it loads that test suite recursively, otherwise it +instantiates a local test config for the directory (see L<"LOCAL CONFIGURATION +FILES">). + +Tests are identified by the test suite they are contained within, and the +relative path inside that suite. Note that the relative path may not refer to an +actual file on disk; some test formats (such as I<GoogleTest>) define "virtual +tests" which have a path that contains both the path to the actual test file and +a subpath to identify the virtual test. + +=head2 LOCAL CONFIGURATION FILES + +When B<lit> loads a subdirectory in a test suite, it instantiates a local test +configuration by cloning the configuration for the parent direction -- the root +of this configuration chain will always be a test suite. Once the test +configuration is cloned B<lit> checks for a I<lit.local.cfg> file in the +subdirectory. If present, this file will be loaded and can be used to specialize +the configuration for each individual directory. This facility can be used to +define subdirectories of optional tests, or to change other configuration +parameters -- for example, to change the test format, or the suffixes which +identify test files. + +=head2 LIT EXAMPLE TESTS + +The B<lit> distribution contains several example implementations of test suites +in the I<ExampleTests> directory. + +=head1 SEE ALSO + +L<valgrind(1)> + +=head1 AUTHOR + +Written by Daniel Dunbar and maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llc.pod b/docs/main/CommandGuide/llc.pod new file mode 100644 index 0000000..ac24aab --- /dev/null +++ b/docs/main/CommandGuide/llc.pod @@ -0,0 +1,193 @@ +=pod + +=head1 NAME + +llc - LLVM static compiler + +=head1 SYNOPSIS + +B<llc> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +The B<llc> command compiles LLVM source inputs into assembly language for a +specified architecture. The assembly language output can then be passed through +a native assembler and linker to generate a native executable. + +The choice of architecture for the output assembly code is automatically +determined from the input file, unless the B<-march> option is used to override +the default. + +=head1 OPTIONS + +If I<filename> is - or omitted, B<llc> reads from standard input. Otherwise, it +will from I<filename>. Inputs can be in either the LLVM assembly language +format (.ll) or the LLVM bitcode format (.bc). + +If the B<-o> option is omitted, then B<llc> will send its output to standard +output if the input is from standard input. If the B<-o> option specifies -, +then the output will also be sent to standard output. + +If no B<-o> option is specified and an input file other than - is specified, +then B<llc> creates the output filename by taking the input filename, +removing any existing F<.bc> extension, and adding a F<.s> suffix. + +Other B<llc> options are as follows: + +=head2 End-user Options + +=over + +=item B<-help> + +Print a summary of command line options. + +=item B<-O>=I<uint> + +Generate code at different optimization levels. These correspond to the I<-O0>, +I<-O1>, I<-O2>, I<-O3>, and I<-O4> optimization levels used by B<llvm-gcc> and +B<clang>. + +=item B<-mtriple>=I<target triple> + +Override the target triple specified in the input file with the specified +string. + +=item B<-march>=I<arch> + +Specify the architecture for which to generate assembly, overriding the target +encoded in the input file. See the output of B<llc -help> for a list of +valid architectures. By default this is inferred from the target triple or +autodetected to the current architecture. + +=item B<-mcpu>=I<cpuname> + +Specify a specific chip in the current architecture to generate code for. +By default this is inferred from the target triple and autodetected to +the current architecture. For a list of available CPUs, use: +B<llvm-as E<lt> /dev/null | llc -march=xyz -mcpu=help> + +=item B<-mattr>=I<a1,+a2,-a3,...> + +Override or control specific attributes of the target, such as whether SIMD +operations are enabled or not. The default set of attributes is set by the +current CPU. For a list of available attributes, use: +B<llvm-as E<lt> /dev/null | llc -march=xyz -mattr=help> + +=item B<--disable-fp-elim> + +Disable frame pointer elimination optimization. + +=item B<--disable-excess-fp-precision> + +Disable optimizations that may produce excess precision for floating point. +Note that this option can dramatically slow down code on some systems +(e.g. X86). + +=item B<--enable-unsafe-fp-math> + +Enable optimizations that make unsafe assumptions about IEEE math (e.g. that +addition is associative) or may not work for all input ranges. These +optimizations allow the code generator to make use of some instructions which +would otherwise not be usable (such as fsin on X86). + +=item B<--enable-correct-eh-support> + +Instruct the B<lowerinvoke> pass to insert code for correct exception handling +support. This is expensive and is by default omitted for efficiency. + +=item B<--stats> + +Print statistics recorded by code-generation passes. + +=item B<--time-passes> + +Record the amount of time needed for each pass and print a report to standard +error. + +=item B<--load>=F<dso_path> + +Dynamically load F<dso_path> (a path to a dynamically shared object) that +implements an LLVM target. This will permit the target name to be used with the +B<-march> option so that code can be generated for that target. + +=back + +=head2 Tuning/Configuration Options + +=over + +=item B<--print-machineinstrs> + +Print generated machine code between compilation phases (useful for debugging). + +=item B<--regalloc>=I<allocator> + +Specify the register allocator to use. The default I<allocator> is I<local>. +Valid register allocators are: + +=over + +=item I<simple> + +Very simple "always spill" register allocator + +=item I<local> + +Local register allocator + +=item I<linearscan> + +Linear scan global register allocator + +=item I<iterativescan> + +Iterative scan global register allocator + +=back + +=item B<--spiller>=I<spiller> + +Specify the spiller to use for register allocators that support it. Currently +this option is used only by the linear scan register allocator. The default +I<spiller> is I<local>. Valid spillers are: + +=over + +=item I<simple> + +Simple spiller + +=item I<local> + +Local spiller + +=back + +=back + +=head2 Intel IA-32-specific Options + +=over + +=item B<--x86-asm-syntax=att|intel> + +Specify whether to emit assembly code in AT&T syntax (the default) or intel +syntax. + +=back + +=head1 EXIT STATUS + +If B<llc> succeeds, it will exit with 0. Otherwise, if an error occurs, +it will exit with a non-zero value. + +=head1 SEE ALSO + +L<lli|lli> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/lli.pod b/docs/main/CommandGuide/lli.pod new file mode 100644 index 0000000..d368bec --- /dev/null +++ b/docs/main/CommandGuide/lli.pod @@ -0,0 +1,216 @@ +=pod + +=head1 NAME + +lli - directly execute programs from LLVM bitcode + +=head1 SYNOPSIS + +B<lli> [I<options>] [I<filename>] [I<program args>] + +=head1 DESCRIPTION + +B<lli> directly executes programs in LLVM bitcode format. It takes a program +in LLVM bitcode format and executes it using a just-in-time compiler, if one is +available for the current architecture, or an interpreter. B<lli> takes all of +the same code generator options as L<llc|llc>, but they are only effective when +B<lli> is using the just-in-time compiler. + +If I<filename> is not specified, then B<lli> reads the LLVM bitcode for the +program from standard input. + +The optional I<args> specified on the command line are passed to the program as +arguments. + +=head1 GENERAL OPTIONS + +=over + +=item B<-fake-argv0>=I<executable> + +Override the C<argv[0]> value passed into the executing program. + +=item B<-force-interpreter>=I<{false,true}> + +If set to true, use the interpreter even if a just-in-time compiler is available +for this architecture. Defaults to false. + +=item B<-help> + +Print a summary of command line options. + +=item B<-load>=I<puginfilename> + +Causes B<lli> to load the plugin (shared object) named I<pluginfilename> and use +it for optimization. + +=item B<-stats> + +Print statistics from the code-generation passes. This is only meaningful for +the just-in-time compiler, at present. + +=item B<-time-passes> + +Record the amount of time needed for each code-generation pass and print it to +standard error. + +=item B<-version> + +Print out the version of B<lli> and exit without doing anything else. + +=back + +=head1 TARGET OPTIONS + +=over + +=item B<-mtriple>=I<target triple> + +Override the target triple specified in the input bitcode file with the +specified string. This may result in a crash if you pick an +architecture which is not compatible with the current system. + +=item B<-march>=I<arch> + +Specify the architecture for which to generate assembly, overriding the target +encoded in the bitcode file. See the output of B<llc -help> for a list of +valid architectures. By default this is inferred from the target triple or +autodetected to the current architecture. + +=item B<-mcpu>=I<cpuname> + +Specify a specific chip in the current architecture to generate code for. +By default this is inferred from the target triple and autodetected to +the current architecture. For a list of available CPUs, use: +B<llvm-as E<lt> /dev/null | llc -march=xyz -mcpu=help> + +=item B<-mattr>=I<a1,+a2,-a3,...> + +Override or control specific attributes of the target, such as whether SIMD +operations are enabled or not. The default set of attributes is set by the +current CPU. For a list of available attributes, use: +B<llvm-as E<lt> /dev/null | llc -march=xyz -mattr=help> + +=back + + +=head1 FLOATING POINT OPTIONS + +=over + +=item B<-disable-excess-fp-precision> + +Disable optimizations that may increase floating point precision. + +=item B<-enable-finite-only-fp-math> + +Enable optimizations that assumes only finite floating point math. That is, +there is no NAN or Inf values. + +=item B<-enable-unsafe-fp-math> + +Causes B<lli> to enable optimizations that may decrease floating point +precision. + +=item B<-soft-float> + +Causes B<lli> to generate software floating point library calls instead of +equivalent hardware instructions. + +=back + +=head1 CODE GENERATION OPTIONS + +=over + +=item B<-code-model>=I<model> + +Choose the code model from: + + default: Target default code model + small: Small code model + kernel: Kernel code model + medium: Medium code model + large: Large code model + +=item B<-disable-post-RA-scheduler> + +Disable scheduling after register allocation. + +=item B<-disable-spill-fusing> + +Disable fusing of spill code into instructions. + +=item B<-enable-correct-eh-support> + +Make the -lowerinvoke pass insert expensive, but correct, EH code. + +=item B<-jit-enable-eh> + +Exception handling should be enabled in the just-in-time compiler. + +=item B<-join-liveintervals> + +Coalesce copies (default=true). + +=item B<-nozero-initialized-in-bss> +Don't place zero-initialized symbols into the BSS section. + +=item B<-pre-RA-sched>=I<scheduler> + +Instruction schedulers available (before register allocation): + + =default: Best scheduler for the target + =none: No scheduling: breadth first sequencing + =simple: Simple two pass scheduling: minimize critical path and maximize processor utilization + =simple-noitin: Simple two pass scheduling: Same as simple except using generic latency + =list-burr: Bottom-up register reduction list scheduling + =list-tdrr: Top-down register reduction list scheduling + =list-td: Top-down list scheduler -print-machineinstrs - Print generated machine code + +=item B<-regalloc>=I<allocator> + +Register allocator to use (default=linearscan) + + =bigblock: Big-block register allocator + =linearscan: linear scan register allocator =local - local register allocator + =simple: simple register allocator + +=item B<-relocation-model>=I<model> + +Choose relocation model from: + + =default: Target default relocation model + =static: Non-relocatable code =pic - Fully relocatable, position independent code + =dynamic-no-pic: Relocatable external references, non-relocatable code + +=item B<-spiller> + +Spiller to use (default=local) + + =simple: simple spiller + =local: local spiller + +=item B<-x86-asm-syntax>=I<syntax> + +Choose style of code to emit from X86 backend: + + =att: Emit AT&T-style assembly + =intel: Emit Intel-style assembly + +=back + +=head1 EXIT STATUS + +If B<lli> fails to load the program, it will exit with an exit code of 1. +Otherwise, it will return the exit code of the program it executes. + +=head1 SEE ALSO + +L<llc|llc> + +=head1 AUTHOR + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-ar.pod b/docs/main/CommandGuide/llvm-ar.pod new file mode 100644 index 0000000..63ba43f --- /dev/null +++ b/docs/main/CommandGuide/llvm-ar.pod @@ -0,0 +1,406 @@ +=pod + +=head1 NAME + +llvm-ar - LLVM archiver + +=head1 SYNOPSIS + +B<llvm-ar> [-]{dmpqrtx}[Rabfikouz] [relpos] [count] <archive> [files...] + + +=head1 DESCRIPTION + +The B<llvm-ar> command is similar to the common Unix utility, C<ar>. It +archives several files together into a single file. The intent for this is +to produce archive libraries by LLVM bitcode that can be linked into an +LLVM program. However, the archive can contain any kind of file. By default, +B<llvm-ar> generates a symbol table that makes linking faster because +only the symbol table needs to be consulted, not each individual file member +of the archive. + +The B<llvm-ar> command can be used to I<read> both SVR4 and BSD style archive +files. However, it cannot be used to write them. While the B<llvm-ar> command +produces files that are I<almost> identical to the format used by other C<ar> +implementations, it has two significant departures in order to make the +archive appropriate for LLVM. The first departure is that B<llvm-ar> only +uses BSD4.4 style long path names (stored immediately after the header) and +never contains a string table for long names. The second departure is that the +symbol table is formated for efficient construction of an in-memory data +structure that permits rapid (red-black tree) lookups. Consequently, archives +produced with B<llvm-ar> usually won't be readable or editable with any +C<ar> implementation or useful for linking. Using the C<f> modifier to flatten +file names will make the archive readable by other C<ar> implementations +but not for linking because the symbol table format for LLVM is unique. If an +SVR4 or BSD style archive is used with the C<r> (replace) or C<q> (quick +update) operations, the archive will be reconstructed in LLVM format. This +means that the string table will be dropped (in deference to BSD 4.4 long names) +and an LLVM symbol table will be added (by default). The system symbol table +will be retained. + +Here's where B<llvm-ar> departs from previous C<ar> implementations: + +=over + +=item I<Symbol Table> + +Since B<llvm-ar> is intended to archive bitcode files, the symbol table +won't make much sense to anything but LLVM. Consequently, the symbol table's +format has been simplified. It consists simply of a sequence of pairs +of a file member index number as an LSB 4byte integer and a null-terminated +string. + +=item I<Long Paths> + +Some C<ar> implementations (SVR4) use a separate file member to record long +path names (> 15 characters). B<llvm-ar> takes the BSD 4.4 and Mac OS X +approach which is to simply store the full path name immediately preceding +the data for the file. The path name is null terminated and may contain the +slash (/) character. + +=item I<Compression> + +B<llvm-ar> can compress the members of an archive to save space. The +compression used depends on what's available on the platform and what choices +the LLVM Compressor utility makes. It generally favors bzip2 but will select +between "no compression" or bzip2 depending on what makes sense for the +file's content. + +=item I<Directory Recursion> + +Most C<ar> implementations do not recurse through directories but simply +ignore directories if they are presented to the program in the F<files> +option. B<llvm-ar>, however, can recurse through directory structures and +add all the files under a directory, if requested. + +=item I<TOC Verbose Output> + +When B<llvm-ar> prints out the verbose table of contents (C<tv> option), it +precedes the usual output with a character indicating the basic kind of +content in the file. A blank means the file is a regular file. A 'Z' means +the file is compressed. A 'B' means the file is an LLVM bitcode file. An +'S' means the file is the symbol table. + +=back + +=head1 OPTIONS + +The options to B<llvm-ar> are compatible with other C<ar> implementations. +However, there are a few modifiers (F<zR>) that are not found in other +C<ar>s. The options to B<llvm-ar> specify a single basic operation to +perform on the archive, a variety of modifiers for that operation, the +name of the archive file, and an optional list of file names. These options +are used to determine how B<llvm-ar> should process the archive file. + +The Operations and Modifiers are explained in the sections below. The minimal +set of options is at least one operator and the name of the archive. Typically +archive files end with a C<.a> suffix, but this is not required. Following +the F<archive-name> comes a list of F<files> that indicate the specific members +of the archive to operate on. If the F<files> option is not specified, it +generally means either "none" or "all" members, depending on the operation. + +=head2 Operations + +=over + +=item d + +Delete files from the archive. No modifiers are applicable to this operation. +The F<files> options specify which members should be removed from the +archive. It is not an error if a specified file does not appear in the archive. +If no F<files> are specified, the archive is not modified. + +=item m[abi] + +Move files from one location in the archive to another. The F<a>, F<b>, and +F<i> modifiers apply to this operation. The F<files> will all be moved +to the location given by the modifiers. If no modifiers are used, the files +will be moved to the end of the archive. If no F<files> are specified, the +archive is not modified. + +=item p[k] + +Print files to the standard output. The F<k> modifier applies to this +operation. This operation simply prints the F<files> indicated to the +standard output. If no F<files> are specified, the entire archive is printed. +Printing bitcode files is ill-advised as they might confuse your terminal +settings. The F<p> operation never modifies the archive. + +=item q[Rfz] + +Quickly append files to the end of the archive. The F<R>, F<f>, and F<z> +modifiers apply to this operation. This operation quickly adds the +F<files> to the archive without checking for duplicates that should be +removed first. If no F<files> are specified, the archive is not modified. +Because of the way that B<llvm-ar> constructs the archive file, its dubious +whether the F<q> operation is any faster than the F<r> operation. + +=item r[Rabfuz] + +Replace or insert file members. The F<R>, F<a>, F<b>, F<f>, F<u>, and F<z> +modifiers apply to this operation. This operation will replace existing +F<files> or insert them at the end of the archive if they do not exist. If no +F<files> are specified, the archive is not modified. + +=item t[v] + +Print the table of contents. Without any modifiers, this operation just prints +the names of the members to the standard output. With the F<v> modifier, +B<llvm-ar> also prints out the file type (B=bitcode, Z=compressed, S=symbol +table, blank=regular file), the permission mode, the owner and group, the +size, and the date. If any F<files> are specified, the listing is only for +those files. If no F<files> are specified, the table of contents for the +whole archive is printed. + +=item x[oP] + +Extract archive members back to files. The F<o> modifier applies to this +operation. This operation retrieves the indicated F<files> from the archive +and writes them back to the operating system's file system. If no +F<files> are specified, the entire archive is extract. + +=back + +=head2 Modifiers (operation specific) + +The modifiers below are specific to certain operations. See the Operations +section (above) to determine which modifiers are applicable to which operations. + +=over + +=item [a] + +When inserting or moving member files, this option specifies the destination of +the new files as being C<a>fter the F<relpos> member. If F<relpos> is not found, +the files are placed at the end of the archive. + +=item [b] + +When inserting or moving member files, this option specifies the destination of +the new files as being C<b>efore the F<relpos> member. If F<relpos> is not +found, the files are placed at the end of the archive. This modifier is +identical to the the F<i> modifier. + +=item [f] + +Normally, B<llvm-ar> stores the full path name to a file as presented to it on +the command line. With this option, truncated (15 characters max) names are +used. This ensures name compatibility with older versions of C<ar> but may also +thwart correct extraction of the files (duplicates may overwrite). If used with +the F<R> option, the directory recursion will be performed but the file names +will all be C<f>lattened to simple file names. + +=item [i] + +A synonym for the F<b> option. + +=item [k] + +Normally, B<llvm-ar> will not print the contents of bitcode files when the +F<p> operation is used. This modifier defeats the default and allows the +bitcode members to be printed. + +=item [N] + +This option is ignored by B<llvm-ar> but provided for compatibility. + +=item [o] + +When extracting files, this option will cause B<llvm-ar> to preserve the +original modification times of the files it writes. + +=item [P] + +use full path names when matching + +=item [R] + +This modifier instructions the F<r> option to recursively process directories. +Without F<R>, directories are ignored and only those F<files> that refer to +files will be added to the archive. When F<R> is used, any directories specified +with F<files> will be scanned (recursively) to find files to be added to the +archive. Any file whose name begins with a dot will not be added. + +=item [u] + +When replacing existing files in the archive, only replace those files that have +a time stamp than the time stamp of the member in the archive. + +=item [z] + +When inserting or replacing any file in the archive, compress the file first. +This +modifier is safe to use when (previously) compressed bitcode files are added to +the archive; the compressed bitcode files will not be doubly compressed. + +=back + +=head2 Modifiers (generic) + +The modifiers below may be applied to any operation. + +=over + +=item [c] + +For all operations, B<llvm-ar> will always create the archive if it doesn't +exist. Normally, B<llvm-ar> will print a warning message indicating that the +archive is being created. Using this modifier turns off that warning. + +=item [s] + +This modifier requests that an archive index (or symbol table) be added to the +archive. This is the default mode of operation. The symbol table will contain +all the externally visible functions and global variables defined by all the +bitcode files in the archive. Using this modifier is more efficient that using +L<llvm-ranlib|llvm-ranlib> which also creates the symbol table. + +=item [S] + +This modifier is the opposite of the F<s> modifier. It instructs B<llvm-ar> to +not build the symbol table. If both F<s> and F<S> are used, the last modifier to +occur in the options will prevail. + +=item [v] + +This modifier instructs B<llvm-ar> to be verbose about what it is doing. Each +editing operation taken against the archive will produce a line of output saying +what is being done. + +=back + +=head1 STANDARDS + +The B<llvm-ar> utility is intended to provide a superset of the IEEE Std 1003.2 +(POSIX.2) functionality for C<ar>. B<llvm-ar> can read both SVR4 and BSD4.4 (or +Mac OS X) archives. If the C<f> modifier is given to the C<x> or C<r> operations +then B<llvm-ar> will write SVR4 compatible archives. Without this modifier, +B<llvm-ar> will write BSD4.4 compatible archives that have long names +immediately after the header and indicated using the "#1/ddd" notation for the +name in the header. + +=head1 FILE FORMAT + +The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX +archive files. In fact, except for the symbol table, the C<ar> commands on those +operating systems should be able to read LLVM archive files. The details of the +file format follow. + +Each archive begins with the archive magic number which is the eight printable +characters "!<arch>\n" where \n represents the newline character (0x0A). +Following the magic number, the file is composed of even length members that +begin with an archive header and end with a \n padding character if necessary +(to make the length even). Each file member is composed of a header (defined +below), an optional newline-terminated "long file name" and the contents of +the file. + +The fields of the header are described in the items below. All fields of the +header contain only ASCII characters, are left justified and are right padded +with space characters. + +=over + +=item name - char[16] + +This field of the header provides the name of the archive member. If the name is +longer than 15 characters or contains a slash (/) character, then this field +contains C<#1/nnn> where C<nnn> provides the length of the name and the C<#1/> +is literal. In this case, the actual name of the file is provided in the C<nnn> +bytes immediately following the header. If the name is 15 characters or less, it +is contained directly in this field and terminated with a slash (/) character. + +=item date - char[12] + +This field provides the date of modification of the file in the form of a +decimal encoded number that provides the number of seconds since the epoch +(since 00:00:00 Jan 1, 1970) per Posix specifications. + +=item uid - char[6] + +This field provides the user id of the file encoded as a decimal ASCII string. +This field might not make much sense on non-Unix systems. On Unix, it is the +same value as the st_uid field of the stat structure returned by the stat(2) +operating system call. + +=item gid - char[6] + +This field provides the group id of the file encoded as a decimal ASCII string. +This field might not make much sense on non-Unix systems. On Unix, it is the +same value as the st_gid field of the stat structure returned by the stat(2) +operating system call. + +=item mode - char[8] + +This field provides the access mode of the file encoded as an octal ASCII +string. This field might not make much sense on non-Unix systems. On Unix, it +is the same value as the st_mode field of the stat structure returned by the +stat(2) operating system call. + +=item size - char[10] + +This field provides the size of the file, in bytes, encoded as a decimal ASCII +string. If the size field is negative (starts with a minus sign, 0x02D), then +the archive member is stored in compressed form. The first byte of the archive +member's data indicates the compression type used. A value of 0 (0x30) indicates +that no compression was used. A value of 2 (0x32) indicates that bzip2 +compression was used. + +=item fmag - char[2] + +This field is the archive file member magic number. Its content is always the +two characters back tick (0x60) and newline (0x0A). This provides some measure +utility in identifying archive files that have been corrupted. + +=back + +The LLVM symbol table has the special name "#_LLVM_SYM_TAB_#". It is presumed +that no regular archive member file will want this name. The LLVM symbol table +is simply composed of a sequence of triplets: byte offset, length of symbol, +and the symbol itself. Symbols are not null or newline terminated. Here are +the details on each of these items: + +=over + +=item offset - vbr encoded 32-bit integer + +The offset item provides the offset into the archive file where the bitcode +member is stored that is associated with the symbol. The offset value is 0 +based at the start of the first "normal" file member. To derive the actual +file offset of the member, you must add the number of bytes occupied by the file +signature (8 bytes) and the symbol tables. The value of this item is encoded +using variable bit rate encoding to reduce the size of the symbol table. +Variable bit rate encoding uses the high bit (0x80) of each byte to indicate +if there are more bytes to follow. The remaining 7 bits in each byte carry bits +from the value. The final byte does not have the high bit set. + +=item length - vbr encoded 32-bit integer + +The length item provides the length of the symbol that follows. Like this +I<offset> item, the length is variable bit rate encoded. + +=item symbol - character array + +The symbol item provides the text of the symbol that is associated with the +I<offset>. The symbol is not terminated by any character. Its length is provided +by the I<length> field. Note that is allowed (but unwise) to use non-printing +characters (even 0x00) in the symbol. This allows for multiple encodings of +symbol names. + +=back + +=head1 EXIT STATUS + +If B<llvm-ar> succeeds, it will exit with 0. A usage error, results +in an exit code of 1. A hard (file system typically) error results in an +exit code of 2. Miscellaneous or unknown errors result in an +exit code of 3. + +=head1 SEE ALSO + +L<llvm-ranlib|llvm-ranlib>, ar(1) + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-as.pod b/docs/main/CommandGuide/llvm-as.pod new file mode 100644 index 0000000..185c009 --- /dev/null +++ b/docs/main/CommandGuide/llvm-as.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +llvm-as - LLVM assembler + +=head1 SYNOPSIS + +B<llvm-as> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +B<llvm-as> is the LLVM assembler. It reads a file containing human-readable +LLVM assembly language, translates it to LLVM bitcode, and writes the result +into a file or to standard output. + +If F<filename> is omitted or is C<->, then B<llvm-as> reads its input from +standard input. + +If an output file is not specified with the B<-o> option, then +B<llvm-as> sends its output to a file or standard output by following +these rules: + +=over + +=item * + +If the input is standard input, then the output is standard output. + +=item * + +If the input is a file that ends with C<.ll>, then the output file is of +the same name, except that the suffix is changed to C<.bc>. + +=item * + +If the input is a file that does not end with the C<.ll> suffix, then the +output file has the same name as the input file, except that the C<.bc> +suffix is appended. + +=back + +=head1 OPTIONS + +=over + +=item B<-f> + +Enable binary output on terminals. Normally, B<llvm-as> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<llvm-as> will write raw bitcode regardless of the output device. + +=item B<-help> + +Print a summary of command line options. + +=item B<-o> F<filename> + +Specify the output file name. If F<filename> is C<->, then B<llvm-as> +sends its output to standard output. + +=back + +=head1 EXIT STATUS + +If B<llvm-as> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<llvm-dis|llvm-dis>, L<gccas|gccas> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-bcanalyzer.pod b/docs/main/CommandGuide/llvm-bcanalyzer.pod new file mode 100644 index 0000000..b0bc0cd --- /dev/null +++ b/docs/main/CommandGuide/llvm-bcanalyzer.pod @@ -0,0 +1,315 @@ +=pod + +=head1 NAME + +llvm-bcanalyzer - LLVM bitcode analyzer + +=head1 SYNOPSIS + +B<llvm-bcanalyzer> [I<options>] [F<filename>] + +=head1 DESCRIPTION + +The B<llvm-bcanalyzer> command is a small utility for analyzing bitcode files. +The tool reads a bitcode file (such as generated with the B<llvm-as> tool) and +produces a statistical report on the contents of the bitcode file. The tool +can also dump a low level but human readable version of the bitcode file. +This tool is probably not of much interest or utility except for those working +directly with the bitcode file format. Most LLVM users can just ignore +this tool. + +If F<filename> is omitted or is C<->, then B<llvm-bcanalyzer> reads its input +from standard input. This is useful for combining the tool into a pipeline. +Output is written to the standard output. + +=head1 OPTIONS + +=over + +=item B<-nodetails> + +Causes B<llvm-bcanalyzer> to abbreviate its output by writing out only a module +level summary. The details for individual functions are not displayed. + +=item B<-dump> + +Causes B<llvm-bcanalyzer> to dump the bitcode in a human readable format. This +format is significantly different from LLVM assembly and provides details about +the encoding of the bitcode file. + +=item B<-verify> + +Causes B<llvm-bcanalyzer> to verify the module produced by reading the +bitcode. This ensures that the statistics generated are based on a consistent +module. + +=item B<-help> + +Print a summary of command line options. + +=back + +=head1 EXIT STATUS + +If B<llvm-bcanalyzer> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value, usually 1. + +=head1 SUMMARY OUTPUT DEFINITIONS + +The following items are always printed by llvm-bcanalyzer. They comprize the +summary output. + +=over + +=item B<Bitcode Analysis Of Module> + +This just provides the name of the module for which bitcode analysis is being +generated. + +=item B<Bitcode Version Number> + +The bitcode version (not LLVM version) of the file read by the analyzer. + +=item B<File Size> + +The size, in bytes, of the entire bitcode file. + +=item B<Module Bytes> + +The size, in bytes, of the module block. Percentage is relative to File Size. + +=item B<Function Bytes> + +The size, in bytes, of all the function blocks. Percentage is relative to File +Size. + +=item B<Global Types Bytes> + +The size, in bytes, of the Global Types Pool. Percentage is relative to File +Size. This is the size of the definitions of all types in the bitcode file. + +=item B<Constant Pool Bytes> + +The size, in bytes, of the Constant Pool Blocks Percentage is relative to File +Size. + +=item B<Module Globals Bytes> + +Ths size, in bytes, of the Global Variable Definitions and their initializers. +Percentage is relative to File Size. + +=item B<Instruction List Bytes> + +The size, in bytes, of all the instruction lists in all the functions. +Percentage is relative to File Size. Note that this value is also included in +the Function Bytes. + +=item B<Compaction Table Bytes> + +The size, in bytes, of all the compaction tables in all the functions. +Percentage is relative to File Size. Note that this value is also included in +the Function Bytes. + +=item B<Symbol Table Bytes> + +The size, in bytes, of all the symbol tables in all the functions. Percentage is +relative to File Size. Note that this value is also included in the Function +Bytes. + +=item B<Dependent Libraries Bytes> + +The size, in bytes, of the list of dependent libraries in the module. Percentage +is relative to File Size. Note that this value is also included in the Module +Global Bytes. + +=item B<Number Of Bitcode Blocks> + +The total number of blocks of any kind in the bitcode file. + +=item B<Number Of Functions> + +The total number of function definitions in the bitcode file. + +=item B<Number Of Types> + +The total number of types defined in the Global Types Pool. + +=item B<Number Of Constants> + +The total number of constants (of any type) defined in the Constant Pool. + +=item B<Number Of Basic Blocks> + +The total number of basic blocks defined in all functions in the bitcode file. + +=item B<Number Of Instructions> + +The total number of instructions defined in all functions in the bitcode file. + +=item B<Number Of Long Instructions> + +The total number of long instructions defined in all functions in the bitcode +file. Long instructions are those taking greater than 4 bytes. Typically long +instructions are GetElementPtr with several indices, PHI nodes, and calls to +functions with large numbers of arguments. + +=item B<Number Of Operands> + +The total number of operands used in all instructions in the bitcode file. + +=item B<Number Of Compaction Tables> + +The total number of compaction tables in all functions in the bitcode file. + +=item B<Number Of Symbol Tables> + +The total number of symbol tables in all functions in the bitcode file. + +=item B<Number Of Dependent Libs> + +The total number of dependent libraries found in the bitcode file. + +=item B<Total Instruction Size> + +The total size of the instructions in all functions in the bitcode file. + +=item B<Average Instruction Size> + +The average number of bytes per instruction across all functions in the bitcode +file. This value is computed by dividing Total Instruction Size by Number Of +Instructions. + +=item B<Maximum Type Slot Number> + +The maximum value used for a type's slot number. Larger slot number values take +more bytes to encode. + +=item B<Maximum Value Slot Number> + +The maximum value used for a value's slot number. Larger slot number values take +more bytes to encode. + +=item B<Bytes Per Value> + +The average size of a Value definition (of any type). This is computed by +dividing File Size by the total number of values of any type. + +=item B<Bytes Per Global> + +The average size of a global definition (constants and global variables). + +=item B<Bytes Per Function> + +The average number of bytes per function definition. This is computed by +dividing Function Bytes by Number Of Functions. + +=item B<# of VBR 32-bit Integers> + +The total number of 32-bit integers encoded using the Variable Bit Rate +encoding scheme. + +=item B<# of VBR 64-bit Integers> + +The total number of 64-bit integers encoded using the Variable Bit Rate encoding +scheme. + +=item B<# of VBR Compressed Bytes> + +The total number of bytes consumed by the 32-bit and 64-bit integers that use +the Variable Bit Rate encoding scheme. + +=item B<# of VBR Expanded Bytes> + +The total number of bytes that would have been consumed by the 32-bit and 64-bit +integers had they not been compressed with the Variable Bit Rage encoding +scheme. + +=item B<Bytes Saved With VBR> + +The total number of bytes saved by using the Variable Bit Rate encoding scheme. +The percentage is relative to # of VBR Expanded Bytes. + +=back + +=head1 DETAILED OUTPUT DEFINITIONS + +The following definitions occur only if the -nodetails option was not given. +The detailed output provides additional information on a per-function basis. + +=over + +=item B<Type> + +The type signature of the function. + +=item B<Byte Size> + +The total number of bytes in the function's block. + +=item B<Basic Blocks> + +The number of basic blocks defined by the function. + +=item B<Instructions> + +The number of instructions defined by the function. + +=item B<Long Instructions> + +The number of instructions using the long instruction format in the function. + +=item B<Operands> + +The number of operands used by all instructions in the function. + +=item B<Instruction Size> + +The number of bytes consumed by instructions in the function. + +=item B<Average Instruction Size> + +The average number of bytes consumed by the instructions in the funtion. This +value is computed by dividing Instruction Size by Instructions. + +=item B<Bytes Per Instruction> + +The average number of bytes used by the function per instruction. This value is +computed by dividing Byte Size by Instructions. Note that this is not the same +as Average Instruction Size. It computes a number relative to the total function +size not just the size of the instruction list. + +=item B<Number of VBR 32-bit Integers> + +The total number of 32-bit integers found in this function (for any use). + +=item B<Number of VBR 64-bit Integers> + +The total number of 64-bit integers found in this function (for any use). + +=item B<Number of VBR Compressed Bytes> + +The total number of bytes in this function consumed by the 32-bit and 64-bit +integers that use the Variable Bit Rate encoding scheme. + +=item B<Number of VBR Expanded Bytes> + +The total number of bytes in this function that would have been consumed by +the 32-bit and 64-bit integers had they not been compressed with the Variable +Bit Rate encoding scheme. + +=item B<Bytes Saved With VBR> + +The total number of bytes saved in this function by using the Variable Bit +Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes. + +=back + +=head1 SEE ALSO + +L<llvm-dis|llvm-dis>, L<http://llvm.org/docs/BitCodeFormat.html> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-config.pod b/docs/main/CommandGuide/llvm-config.pod new file mode 100644 index 0000000..4e38dae --- /dev/null +++ b/docs/main/CommandGuide/llvm-config.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +llvm-config - Print LLVM compilation options + +=head1 SYNOPSIS + +B<llvm-config> I<option> [I<components>...] + +=head1 DESCRIPTION + +B<llvm-config> makes it easier to build applications that use LLVM. It can +print the compiler flags, linker flags and object libraries needed to link +against LLVM. + +=head1 EXAMPLES + +To link against the JIT: + + g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp + g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \ + `llvm-config --libs engine bcreader scalaropts` + +=head1 OPTIONS + +=over + +=item B<--version> + +Print the version number of LLVM. + +=item B<-help> + +Print a summary of B<llvm-config> arguments. + +=item B<--prefix> + +Print the installation prefix for LLVM. + +=item B<--src-root> + +Print the source root from which LLVM was built. + +=item B<--obj-root> + +Print the object root used to build LLVM. + +=item B<--bindir> + +Print the installation directory for LLVM binaries. + +=item B<--includedir> + +Print the installation directory for LLVM headers. + +=item B<--libdir> + +Print the installation directory for LLVM libraries. + +=item B<--cxxflags> + +Print the C++ compiler flags needed to use LLVM headers. + +=item B<--ldflags> + +Print the flags needed to link against LLVM libraries. + +=item B<--libs> + +Print all the libraries needed to link against the specified LLVM +I<components>, including any dependencies. + +=item B<--libnames> + +Similar to B<--libs>, but prints the bare filenames of the libraries +without B<-l> or pathnames. Useful for linking against a not-yet-installed +copy of LLVM. + +=item B<--libfiles> + +Similar to B<--libs>, but print the full path to each library file. This is +useful when creating makefile dependencies, to ensure that a tool is relinked if +any library it uses changes. + +=item B<--components> + +Print all valid component names. + +=item B<--targets-built> + +Print the component names for all targets supported by this copy of LLVM. + +=item B<--build-mode> + +Print the build mode used when LLVM was built (e.g. Debug or Release) + +=back + +=head1 COMPONENTS + +To print a list of all available components, run B<llvm-config +--components>. In most cases, components correspond directly to LLVM +libraries. Useful "virtual" components include: + +=over + +=item B<all> + +Includes all LLVM libaries. The default if no components are specified. + +=item B<backend> + +Includes either a native backend or the C backend. + +=item B<engine> + +Includes either a native JIT or the bitcode interpreter. + +=back + +=head1 EXIT STATUS + +If B<llvm-config> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-dis.pod b/docs/main/CommandGuide/llvm-dis.pod new file mode 100644 index 0000000..5b2f4ef --- /dev/null +++ b/docs/main/CommandGuide/llvm-dis.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + +llvm-dis - LLVM disassembler + +=head1 SYNOPSIS + +B<llvm-dis> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +The B<llvm-dis> command is the LLVM disassembler. It takes an LLVM +bitcode file and converts it into human-readable LLVM assembly language. + +If filename is omitted or specified as C<->, B<llvm-dis> reads its +input from standard input. + +If the input is being read from standard input, then B<llvm-dis> +will send its output to standard output by default. Otherwise, the +output will be written to a file named after the input file, with +a C<.ll> suffix added (any existing C<.bc> suffix will first be +removed). You can override the choice of output file using the +B<-o> option. + +=head1 OPTIONS + +=over + +=item B<-f> + +Enable binary output on terminals. Normally, B<llvm-dis> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<llvm-dis> will write raw bitcode regardless of the output device. + +=item B<-help> + +Print a summary of command line options. + +=item B<-o> F<filename> + +Specify the output file name. If F<filename> is -, then the output is sent +to standard output. + +=back + +=head1 EXIT STATUS + +If B<llvm-dis> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<llvm-as|llvm-as> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-extract.pod b/docs/main/CommandGuide/llvm-extract.pod new file mode 100644 index 0000000..d4baab7 --- /dev/null +++ b/docs/main/CommandGuide/llvm-extract.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +llvm-extract - extract a function from an LLVM module + +=head1 SYNOPSIS + +B<llvm-extract> [I<options>] B<--func> I<function-name> [I<filename>] + +=head1 DESCRIPTION + +The B<llvm-extract> command takes the name of a function and extracts it from +the specified LLVM bitcode file. It is primarily used as a debugging tool to +reduce test cases from larger programs that are triggering a bug. + +In addition to extracting the bitcode of the specified function, +B<llvm-extract> will also remove unreachable global variables, prototypes, and +unused types. + +The B<llvm-extract> command reads its input from standard input if filename is +omitted or if filename is -. The output is always written to standard output, +unless the B<-o> option is specified (see below). + +=head1 OPTIONS + +=over + +=item B<-f> + +Enable binary output on terminals. Normally, B<llvm-extract> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<llvm-extract> will write raw bitcode regardless of the output device. + +=item B<--func> I<function-name> + +Extract the function named I<function-name> from the LLVM bitcode. May be +specified multiple times to extract multiple functions at once. + +=item B<--glob> I<global-name> + +Extract the global variable named I<global-name> from the LLVM bitcode. May be +specified multiple times to extract multiple global variables at once. + +=item B<-help> + +Print a summary of command line options. + +=item B<-o> I<filename> + +Specify the output filename. If filename is "-" (the default), then +B<llvm-extract> sends its output to standard output. + +=item B<-S> + +Write output in LLVM intermediate language (instead of bitcode). + +=back + +=head1 EXIT STATUS + +If B<llvm-extract> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<bugpoint|bugpoint> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-ld.pod b/docs/main/CommandGuide/llvm-ld.pod new file mode 100644 index 0000000..536ab0f --- /dev/null +++ b/docs/main/CommandGuide/llvm-ld.pod @@ -0,0 +1,234 @@ +=pod + +=head1 NAME + +llvm-ld - LLVM linker + +=head1 SYNOPSIS + +B<llvm-ld> <options> <files> + +=head1 DESCRIPTION + +The B<llvm-ld> tool takes a set of LLVM bitcode files and links them +together into a single LLVM bitcode file. The output bitcode file can be +another bitcode file or an executable bitcode program. Using additional +options, B<llvm-ld> is able to produce native code executables. + +The B<llvm-ld> tool is the main linker for LLVM. It is used to link together +the output of LLVM front-end compilers and run "link time" optimizations (mostly +the inter-procedural kind). + +The B<llvm-ld> tools attempts to mimic the interface provided by the default +system linker so that it can act as a I<drop-in> replacement. + +=head2 Search Order + +When looking for objects specified on the command line, B<llvm-ld> will search +for the object first in the current directory and then in the directory +specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it cannot +find the object, it fails. + +When looking for a library specified with the B<-l> option, B<llvm-ld> first +attempts to load a file with that name from the current directory. If that +fails, it looks for libI<library>.bc, libI<library>.a, or libI<library>.I<shared +library extension>, in that order, in each directory added to the library search +path with the B<-L> option. These directories are searched in the order they +are specified. If the library cannot be located, then B<llvm-ld> looks in the +directory specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it +does not find a library there, it fails. + +The I<shared library extension> may be I<.so>, I<.dyld>, I<.dll>, or something +different, depending upon the system. + +The B<-L> option is global. It does not matter where it is specified in the +list of command line arguments; the directory is simply added to the search path +and is applied to all libraries, preceding or succeeding, in the command line. + +=head2 Link order + +All object and bitcode files are linked first in the order they were +specified on the command line. All library files are linked next. +Some libraries may not be linked into the object program; see below. + +=head2 Library Linkage + +Object files and static bitcode objects are always linked into the output +file. Library archives (.a files) load only the objects within the archive +that define symbols needed by the output file. Hence, libraries should be +listed after the object files and libraries which need them; otherwise, the +library may not be linked in, and the dependent library will not have its +undefined symbols defined. + +=head2 Native code generation + +The B<llvm-ld> program has limited support for native code generation, when +using the B<-native> or B<-native-cbe> options. Native code generation is +performed by converting the linked bitcode into native assembly (.s) or C code +and running the system compiler (typically gcc) on the result. + +=head1 OPTIONS + +=head2 General Options + +=over + +=item B<-help> + +Print a summary of command line options. + +=item B<-v> + +Specifies verbose mode. In this mode the linker will print additional +information about the actions it takes, programs it executes, etc. + +=item B<-stats> + +Print statistics. + +=item B<-time-passes> + +Record the amount of time needed for each pass and print it to standard +error. + +=back + +=head2 Input/Output Options + +=over + +=item B<-o> F<filename> + +This overrides the default output file and specifies the name of the file that +should be generated by the linker. By default, B<llvm-ld> generates a file named +F<a.out> for compatibility with B<ld>. The output will be written to +F<filename>. + +=item B<-b> F<filename> + +This option can be used to override the output bitcode file name. By default, +the name of the bitcode output file is one more ".bc" suffix added to the name +specified by B<-o filename> option. + +=item B<-l>F<name> + +This option specifies the F<name> of a library to search when resolving symbols +for the program. Only the base name should be specified as F<name>, without a +F<lib> prefix or any suffix. + +=item B<-L>F<Path> + +This option tells B<llvm-ld> to look in F<Path> to find any library subsequently +specified with the B<-l> option. The paths will be searched in the order in +which they are specified on the command line. If the library is still not found, +a small set of system specific directories will also be searched. Note that +libraries specified with the B<-l> option that occur I<before> any B<-L> options +will not search the paths given by the B<-L> options following it. + +=item B<-link-as-library> + +Link the bitcode files together as a library, not an executable. In this mode, +undefined symbols will be permitted. + +=item B<-r> + +An alias for -link-as-library. + +=item B<-native> + +Generate a native machine code executable. + +When generating native executables, B<llvm-ld> first checks for a bitcode +version of the library and links it in, if necessary. If the library is +missing, B<llvm-ld> skips it. Then, B<llvm-ld> links in the same +libraries as native code. + +In this way, B<llvm-ld> should be able to link in optimized bitcode +subsets of common libraries and then link in any part of the library that +hasn't been converted to bitcode. + +=item B<-native-cbe> + +Generate a native machine code executable with the LLVM C backend. + +This option is identical to the B<-native> option, but uses the +C backend to generate code for the program instead of an LLVM native +code generator. + +=back + +=head2 Optimization Options + +=over + +=item B<-disable-inlining> + +Do not run the inlining pass. Functions will not be inlined into other +functions. + +=item B<-disable-opt> + +Completely disable optimization. + +=item B<-disable-internalize> + +Do not mark all symbols as internal. + +=item B<-verify-each> + +Run the verification pass after each of the passes to verify intermediate +results. + +=item B<-strip-all> + +Strip all debug and symbol information from the executable to make it smaller. + +=item B<-strip-debug> + +Strip all debug information from the executable to make it smaller. + +=item B<-s> + +An alias for B<-strip-all>. + +=item B<-S> + +An alias for B<-strip-debug>. + +=item B<-export-dynamic> + +An alias for B<-disable-internalize> + +=item B<-post-link-opt>F<Path> + +Run post-link optimization program. After linking is completed a bitcode file +will be generated. It will be passed to the program specified by F<Path> as the +first argument. The second argument to the program will be the name of a +temporary file into which the program should place its optimized output. For +example, the "no-op optimization" would be a simple shell script: + + #!/bin/bash + cp $1 $2 + +=back + +=head1 EXIT STATUS + +If B<llvm-ld> succeeds, it will exit with 0 return code. If an error occurs, +it will exit with a non-zero return code. + +=head1 ENVIRONMENT + +The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bitcode +libraries. Any paths specified in this variable will be searched after the C<-L> +options. + +=head1 SEE ALSO + +L<llvm-link|llvm-link> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-link.pod b/docs/main/CommandGuide/llvm-link.pod new file mode 100644 index 0000000..8d06cc9 --- /dev/null +++ b/docs/main/CommandGuide/llvm-link.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +llvm-link - LLVM linker + +=head1 SYNOPSIS + +B<llvm-link> [I<options>] I<filename ...> + +=head1 DESCRIPTION + +B<llvm-link> takes several LLVM bitcode files and links them together into a +single LLVM bitcode file. It writes the output file to standard output, unless +the B<-o> option is used to specify a filename. + +B<llvm-link> attempts to load the input files from the current directory. If +that fails, it looks for each file in each of the directories specified by the +B<-L> options on the command line. The library search paths are global; each +one is searched for every input file if necessary. The directories are searched +in the order they were specified on the command line. + +=head1 OPTIONS + +=over + +=item B<-L> F<directory> + +Add the specified F<directory> to the library search path. When looking for +libraries, B<llvm-link> will look in path name for libraries. This option can be +specified multiple times; B<llvm-link> will search inside these directories in +the order in which they were specified on the command line. + +=item B<-f> + +Enable binary output on terminals. Normally, B<llvm-link> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<llvm-link> will write raw bitcode regardless of the output device. + +=item B<-o> F<filename> + +Specify the output file name. If F<filename> is C<->, then B<llvm-link> will +write its output to standard output. + +=item B<-S> + +Write output in LLVM intermediate language (instead of bitcode). + +=item B<-d> + +If specified, B<llvm-link> prints a human-readable version of the output +bitcode file to standard error. + +=item B<-help> + +Print a summary of command line options. + +=item B<-v> + +Verbose mode. Print information about what B<llvm-link> is doing. This +typically includes a message for each bitcode file linked in and for each +library found. + +=back + +=head1 EXIT STATUS + +If B<llvm-link> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<gccld|gccld> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-nm.pod b/docs/main/CommandGuide/llvm-nm.pod new file mode 100644 index 0000000..a580d3f --- /dev/null +++ b/docs/main/CommandGuide/llvm-nm.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +llvm-nm - list LLVM bitcode file's symbol table + +=head1 SYNOPSIS + +B<llvm-nm> [I<options>] [I<filenames...>] + +=head1 DESCRIPTION + +The B<llvm-nm> utility lists the names of symbols from the LLVM bitcode files, +or B<ar> archives containing LLVM bitcode files, named on the command line. +Each symbol is listed along with some simple information about its provenance. +If no file name is specified, or I<-> is used as a file name, B<llvm-nm> will +process a bitcode file on its standard input stream. + +B<llvm-nm>'s default output format is the traditional BSD B<nm> output format. +Each such output record consists of an (optional) 8-digit hexadecimal address, +followed by a type code character, followed by a name, for each symbol. One +record is printed per line; fields are separated by spaces. When the address is +omitted, it is replaced by 8 spaces. + +Type code characters currently supported, and their meanings, are as follows: + +=over + +=item U + +Named object is referenced but undefined in this bitcode file + +=item C + +Common (multiple definitions link together into one def) + +=item W + +Weak reference (multiple definitions link together into zero or one definitions) + +=item t + +Local function (text) object + +=item T + +Global function (text) object + +=item d + +Local data object + +=item D + +Global data object + +=item ? + +Something unrecognizable + +=back + +Because LLVM bitcode files typically contain objects that are not considered to +have addresses until they are linked into an executable image or dynamically +compiled "just-in-time", B<llvm-nm> does not print an address for any symbol, +even symbols which are defined in the bitcode file. + +=head1 OPTIONS + +=over + +=item B<-P> + +Use POSIX.2 output format. Alias for B<--format=posix>. + +=item B<-B> (default) + +Use BSD output format. Alias for B<--format=bsd>. + +=item B<-help> + +Print a summary of command-line options and their meanings. + +=item B<--defined-only> + +Print only symbols defined in this bitcode file (as opposed to +symbols which may be referenced by objects in this file, but not +defined in this file.) + +=item B<--extern-only>, B<-g> + +Print only symbols whose definitions are external; that is, accessible +from other bitcode files. + +=item B<--undefined-only>, B<-u> + +Print only symbols referenced but not defined in this bitcode file. + +=item B<--format=>I<fmt>, B<-f> + +Select an output format; I<fmt> may be I<sysv>, I<posix>, or I<bsd>. The +default is I<bsd>. + +=back + +=head1 BUGS + +B<llvm-nm> cannot demangle C++ mangled names, like GNU B<nm> can. + +=head1 EXIT STATUS + +B<llvm-nm> exits with an exit code of zero. + +=head1 SEE ALSO + +L<llvm-dis|llvm-dis>, ar(1), nm(1) + +=head1 AUTHOR + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-prof.pod b/docs/main/CommandGuide/llvm-prof.pod new file mode 100644 index 0000000..9541b05 --- /dev/null +++ b/docs/main/CommandGuide/llvm-prof.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +llvm-prof - print execution profile of LLVM program + +=head1 SYNOPSIS + +B<llvm-prof> [I<options>] [I<bitcode file>] [I<llvmprof.out>] + +=head1 DESCRIPTION + +The B<llvm-prof> tool reads in an F<llvmprof.out> file (which can +optionally use a specific file with the third program argument), a bitcode file +for the program, and produces a human readable report, suitable for determining +where the program hotspots are. + +This program is often used in conjunction with the F<utils/profile.pl> +script. This script automatically instruments a program, runs it with the JIT, +then runs B<llvm-prof> to format a report. To get more information about +F<utils/profile.pl>, execute it with the B<-help> option. + +=head1 OPTIONS + +=over + +=item B<--annotated-llvm> or B<-A> + +In addition to the normal report printed, print out the code for the +program, annotated with execution frequency information. This can be +particularly useful when trying to visualize how frequently basic blocks +are executed. This is most useful with basic block profiling +information or better. + +=item B<--print-all-code> + +Using this option enables the B<--annotated-llvm> option, but it +prints the entire module, instead of just the most commonly executed +functions. + +=item B<--time-passes> + +Record the amount of time needed for each pass and print it to standard +error. + +=back + +=head1 EXIT STATUS + +B<llvm-prof> returns 1 if it cannot load the bitcode file or the profile +information. Otherwise, it exits with zero. + +=head1 AUTHOR + +B<llvm-prof> is maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvm-ranlib.pod b/docs/main/CommandGuide/llvm-ranlib.pod new file mode 100644 index 0000000..53cd34b --- /dev/null +++ b/docs/main/CommandGuide/llvm-ranlib.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +llvm-ranlib - Generate index for LLVM archive + +=head1 SYNOPSIS + +B<llvm-ranlib> [--version] [-help] <archive-file> + +=head1 DESCRIPTION + +The B<llvm-ranlib> command is similar to the common Unix utility, C<ranlib>. It +adds or updates the symbol table in an LLVM archive file. Note that using the +B<llvm-ar> modifier F<s> is usually more efficient than running B<llvm-ranlib> +which is only provided only for completness and compatibility. Unlike other +implementations of C<ranlib>, B<llvm-ranlib> indexes LLVM bitcode files, not +native object modules. You can list the contents of the symbol table with the +C<llvm-nm -s> command. + +=head1 OPTIONS + +=over + +=item F<archive-file> + +Specifies the archive-file to which the symbol table is added or updated. + +=item F<--version> + +Print the version of B<llvm-ranlib> and exit without building a symbol table. + +=item F<-help> + +Print usage help for B<llvm-ranlib> and exit without building a symbol table. + +=back + +=head1 EXIT STATUS + +If B<llvm-ranlib> succeeds, it will exit with 0. If an error occurs, a non-zero +exit code will be returned. + +=head1 SEE ALSO + +L<llvm-ar|llvm-ar>, ranlib(1) + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvmc.pod b/docs/main/CommandGuide/llvmc.pod new file mode 100644 index 0000000..d237ca4 --- /dev/null +++ b/docs/main/CommandGuide/llvmc.pod @@ -0,0 +1,190 @@ +=pod + +=head1 NAME + +llvmc - The LLVM Compiler Driver (WIP) + +=head1 SYNOPSIS + +B<llvmc> [I<options>] I<filenames...> + +=head1 DESCRIPTION + +B<llvmc> is a configurable driver for invoking other LLVM (and non-LLVM) tools +in order to compile, optimize and link software for multiple languages. For +those familiar with FSF's B<gcc> tool, it is very similar. Please note that +B<llvmc> is considered an experimental tool. + +=head1 OPTIONS + +=head2 Built-in Options + +LLVMC has some built-in options that can't be overridden in the +configuration libraries. + +=over + +=item B<-o> I<filename> + +Output file name. + +=item B<-x> I<language> + +Specify the language of the following input files until the next B<-x> +option. + +=item B<-load> I<plugin_name> + +Load the specified plugin DLL. Example: +S<-load $LLVM_DIR/Release/lib/LLVMCSimple.so>. + +=item B<-v> or B<--verbose> + +Enable verbose mode, i.e. print out all executed commands. + +=item B<--check-graph> + +Check the compilation for common errors like mismatched output/input language +names, multiple default edges and cycles. Because of plugins, these checks can't +be performed at compile-time. Exit with code zero if no errors were found, and +return the number of found errors otherwise. Hidden option, useful for debugging +LLVMC plugins. + +=item B<--view-graph> + +Show a graphical representation of the compilation graph and exit. Requires that +you have I<dot> and I<gv> programs installed. Hidden option, useful for +debugging LLVMC plugins. + +=item B<--write-graph> + +Write a I<compilation-graph.dot> file in the current directory with the +compilation graph description in Graphviz format (identical to the file used by +the B<--view-graph> option). The B<-o> option can be used to set the output file +name. Hidden option, useful for debugging LLVMC plugins. + +=item B<--save-temps> + +Write temporary files to the current directory and do not delete them on +exit. This option can also take an argument: the I<--save-temps=obj> switch will +write files into the directory specified with the I<-o> option. The +I<--save-temps=cwd> and I<--save-temps> switches are both synonyms for the +default behaviour. + +=item B<--temp-dir> I<directory> + +Store temporary files in the given directory. This directory is deleted on exit +unless I<--save-temps> is specified. If I<--save-temps=obj> is also specified, +I<--temp-dir> is given the precedence. + +=item B<-help> + +Print a summary of command-line options and exit. + +=item B<-help-hidden> + +Print a summary of command-line options and exit. Print help even for +options intended for developers. + +=item B<--version> + +Print version information and exit. + +=item B<@>I<file> + +Read command-line options from I<file>. The options read are inserted +in place of the original @I<file> option. If I<file> does not exist, or +cannot be read, then the option will be treated literally, and not +removed. + +Options in I<file> are separated by whitespace. A whitespace character +may be included in an option by surrounding the entire option in +either single or double quotes. Any character (including a backslash) +may be included by prefixing the character to be included with a +backslash. The file may itself contain additional @I<file> options; +any such options will be processed recursively. + + +=back + + +=head2 Control Options + +By default, LLVMC is built with some standard configuration libraries +that define the following options: + +=over + +=item B<-clang> + +Use Clang instead of llvm-gcc. + +=item B<-opt> + +Enable optimization passes with B<opt>. To pass options to the B<opt> program +use the B<-Wo,> option. + +=item B<-I> I<directory> + +Add a directory to the header file search path. + +=item B<-L> I<directory> + +Add I<directory> to the library search path. + +=item B<-F> I<directory> + +Add I<directory> to the framework search path. + +=item B<-l>I<name> + +Link in the library libI<name>.[bc | a | so]. This library should +be a bitcode library. + +=item B<-framework> I<name> + +Link in the library libI<name>.[bc | a | so]. This library should +be a bitcode library. + +=item B<-emit-llvm> + +Output LLVM bitcode (with B<-c>) or assembly (with B<-S>) instead of native +object (or assembly). If B<-emit-llvm> is given without either B<-c> or B<-S> +it has no effect. + +=item B<-Wa> + +Pass options to assembler. + +=item B<-Wl> + +Pass options to linker. + +=item B<-Wo> + +Pass options to opt. + +=item B<-Wllc> + +Pass options to llc (code generator). + +=back + +=head1 EXIT STATUS + +If B<llvmc> succeeds, it will exit with code 0. Otherwise, if an +error occurs, it will exit with a non-zero value. If one of the +compilation tools returns a non-zero status, pending actions will be +discarded and B<llvmc> will return the same result code as the failing +compilation tool. + +=head1 SEE ALSO + +L<llvm-gcc|llvmgcc>, L<llvm-g++|llvmgxx>, L<llvm-as|llvm-as>, +L<llvm-dis|llvm-dis>, L<llc|llc>, L<llvm-link|llvm-link> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/llvmgcc.pod b/docs/main/CommandGuide/llvmgcc.pod new file mode 100644 index 0000000..9892ca7 --- /dev/null +++ b/docs/main/CommandGuide/llvmgcc.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +llvm-gcc - LLVM C front-end + +=head1 SYNOPSIS + +B<llvm-gcc> [I<options>] I<filename> + +=head1 DESCRIPTION + +The B<llvm-gcc> command is the LLVM C front end. It is a modified +version of gcc that compiles C/ObjC programs into native objects, LLVM +bitcode or LLVM assembly language, depending upon the options. + +By default, B<llvm-gcc> compiles to native objects just like GCC does. If the +B<-emit-llvm> and B<-c> options are given then it will generate LLVM bitcode files +instead. If B<-emit-llvm> and B<-S> are given, then it will generate LLVM +assembly. + +Being derived from the GNU Compiler Collection, B<llvm-gcc> has many +of gcc's features and accepts most of gcc's options. It handles a +number of gcc's extensions to the C programming language. See the gcc +documentation for details. + +=head1 OPTIONS + +=over + +=item B<--help> + +Print a summary of command line options. + +=item B<-o> I<filename> + +Specify the output file to be I<filename>. + +=item B<-I> I<directory> + +Add a directory to the header file search path. This option can be +repeated. + +=item B<-L> I<directory> + +Add I<directory> to the library search path. This option can be +repeated. + +=item B<-l>I<name> + +Link in the library libI<name>.[bc | a | so]. This library should +be a bitcode library. + +=item B<-emit-llvm> + +Make the output be LLVM bitcode (with B<-c>) or assembly (with B<-s>) instead +of native object (or assembly). If B<-emit-llvm> is given without either B<-c> +or B<-S> it has no effect. + +=back + +=head1 EXIT STATUS + +If B<llvm-gcc> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<llvm-g++|llvmgxx> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut + diff --git a/docs/main/CommandGuide/llvmgxx.pod b/docs/main/CommandGuide/llvmgxx.pod new file mode 100644 index 0000000..64b670e --- /dev/null +++ b/docs/main/CommandGuide/llvmgxx.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +llvm-g++ - LLVM C++ front-end + +=head1 SYNOPSIS + +B<llvm-g++> [I<options>] I<filename> + +=head1 DESCRIPTION + +The B<llvm-g++> command is the LLVM C++ front end. It is a modified +version of g++ that compiles C++/ObjC++ programs into native code, +LLVM bitcode or assembly language, depending upon the options. + +By default, B<llvm-g++> compiles to native objects just like GCC does. If the +B<-emit-llvm> option is given then it will generate LLVM bitcode files instead. +If B<-S> (assembly) is also given, then it will generate LLVM assembly. + +Being derived from the GNU Compiler Collection, B<llvm-g++> has many +of g++'s features and accepts most of g++'s options. It handles a +number of g++'s extensions to the C++ programming language. + +=head1 OPTIONS + +=over + +=item B<--help> + +Print a summary of command line options. + +=item B<-S> + +Do not generate an LLVM bitcode file. Rather, compile the source +file into an LLVM assembly language file. + +=item B<-c> + +Do not generate a linked executable. Rather, compile the source +file into an LLVM bitcode file. This bitcode file can then be +linked with other bitcode files later on to generate a full LLVM +executable. + +=item B<-o> I<filename> + +Specify the output file to be I<filename>. + +=item B<-I> I<directory> + +Add a directory to the header file search path. This option can be +repeated. + +=item B<-L> I<directory> + +Add I<directory> to the library search path. This option can be +repeated. + +=item B<-l>I<name> + +Link in the library libI<name>.[bc | a | so]. This library should +be a bitcode library. + +=item B<-emit-llvm> + +Make the output be LLVM bitcode (or assembly) instead of native object (or +assembly). + +=back + +=head1 EXIT STATUS + +If B<llvm-g++> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<llvm-gcc|llvmgcc> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut + diff --git a/docs/main/CommandGuide/manpage.css b/docs/main/CommandGuide/manpage.css new file mode 100644 index 0000000..c922564 --- /dev/null +++ b/docs/main/CommandGuide/manpage.css @@ -0,0 +1,256 @@ +/* Based on http://www.perldoc.com/css/perldoc.css */ + +@import url("../llvm.css"); + +body { font-family: Arial,Helvetica; } + +blockquote { margin: 10pt; } + +h1, a { color: #336699; } + + +/*** Top menu style ****/ +.mmenuon { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ff6600; font-size: 10pt; +} +.mmenuoff { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: 10pt; +} +.cpyright { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: xx-small; +} +.cpyrightText { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: xx-small; +} +.sections { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 11pt; +} +.dsections { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 12pt; +} +.slink { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #000000; font-size: 9pt; +} + +.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; } + +.maintitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 18pt; +} +.dblArrow { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: small; +} +.menuSec { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: small; +} + +.newstext { + font-family: Arial,Helvetica; font-size: small; +} + +.linkmenu { + font-family: Arial,Helvetica; color: #000000; font-weight: bold; + text-decoration: none; +} + +P { + font-family: Arial,Helvetica; +} + +PRE { + font-size: 10pt; +} +.quote { + font-family: Times; text-decoration: none; + color: #000000; font-size: 9pt; font-style: italic; +} +.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; } +.std { font-family: Arial,Helvetica; color: #000000; } +.meerkatTitle { + font-family: sans-serif; font-size: x-small; color: black; } + +.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black } +.meerkatCategory { + font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic; + color: brown; } +.meerkatChannel { + font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; } +.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; } + +.tocTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 10pt; +} + +.toc-item { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; text-decoration: underline; +} + +.perlVersion { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; text-decoration: none; +} + +.podTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #000000; +} + +.docTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #000000; font-size: 10pt; +} +.dotDot { + font-family: Arial,Helvetica; font-weight: bold; + color: #000000; font-size: 9pt; +} + +.docSec { + font-family: Arial,Helvetica; font-weight: normal; + color: #333333; font-size: 9pt; +} +.docVersion { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 10pt; +} + +.docSecs-on { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #ff0000; font-size: 10pt; +} +.docSecs-off { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #333333; font-size: 10pt; +} + +h2 { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: medium; +} +h1 { + font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: large; +} + +DL { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #333333; font-size: 10pt; +} + +UL > LI > A { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; +} + +.moduleInfo { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 11pt; +} + +.moduleInfoSec { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 10pt; +} + +.moduleInfoVal { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline; + color: #000000; font-size: 10pt; +} + +.cpanNavTitle { + font-family: Arial,Helvetica; font-weight: bold; + color: #ffffff; font-size: 10pt; +} +.cpanNavLetter { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 9pt; +} +.cpanCat { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 9pt; +} + +.bttndrkblue-bkgd-top { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif); +} +.bttndrkblue-bkgd-left { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif); +} +.bttndrkblue-bkgd { + padding-top: 0px; + padding-bottom: 0px; + margin-bottom: 0px; + margin-top: 0px; + background-repeat: no-repeat; + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif); + vertical-align: top; +} +.bttndrkblue-bkgd-right { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif); +} +.bttndrkblue-bkgd-bottom { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif); +} +.bttndrkblue-text a { + color: #ffffff; + text-decoration: none; +} +a.bttndrkblue-text:hover { + color: #ffDD3C; + text-decoration: none; +} +.bg-ltblue { + background-color: #f0f5fa; +} + +.border-left-b { + background: #f0f5fa url(/i/corner-leftline.gif) repeat-y; +} + +.border-right-b { + background: #f0f5fa url(/i/corner-rightline.gif) repeat-y; +} + +.border-top-b { + background: #f0f5fa url(/i/corner-topline.gif) repeat-x; +} + +.border-bottom-b { + background: #f0f5fa url(/i/corner-botline.gif) repeat-x; +} + +.border-right-w { + background: #ffffff url(/i/corner-rightline.gif) repeat-y; +} + +.border-top-w { + background: #ffffff url(/i/corner-topline.gif) repeat-x; +} + +.border-bottom-w { + background: #ffffff url(/i/corner-botline.gif) repeat-x; +} + +.bg-white { + background-color: #ffffff; +} + +.border-left-w { + background: #ffffff url(/i/corner-leftline.gif) repeat-y; +} diff --git a/docs/main/CommandGuide/opt.pod b/docs/main/CommandGuide/opt.pod new file mode 100644 index 0000000..d1d1db5 --- /dev/null +++ b/docs/main/CommandGuide/opt.pod @@ -0,0 +1,143 @@ +=pod + +=head1 NAME + +opt - LLVM optimizer + +=head1 SYNOPSIS + +B<opt> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +The B<opt> command is the modular LLVM optimizer and analyzer. It takes LLVM +source files as input, runs the specified optimizations or analyses on it, and then +outputs the optimized file or the analysis results. The function of +B<opt> depends on whether the B<-analyze> option is given. + +When B<-analyze> is specified, B<opt> performs various analyses of the input +source. It will usually print the results on standard output, but in a few +cases, it will print output to standard error or generate a file with the +analysis output, which is usually done when the output is meant for another +program. + +While B<-analyze> is I<not> given, B<opt> attempts to produce an optimized +output file. The optimizations available via B<opt> depend upon what +libraries were linked into it as well as any additional libraries that have +been loaded with the B<-load> option. Use the B<-help> option to determine +what optimizations you can use. + +If I<filename> is omitted from the command line or is I<->, B<opt> reads its +input from standard input. Inputs can be in either the LLVM assembly language +format (.ll) or the LLVM bitcode format (.bc). + +If an output filename is not specified with the B<-o> option, B<opt> +writes its output to the standard output. + +=head1 OPTIONS + +=over + +=item B<-f> + +Enable binary output on terminals. Normally, B<opt> will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B<opt> will write raw bitcode regardless of the output device. + +=item B<-help> + +Print a summary of command line options. + +=item B<-o> I<filename> + +Specify the output filename. + +=item B<-S> + +Write output in LLVM intermediate language (instead of bitcode). + +=item B<-{passname}> + +B<opt> provides the ability to run any of LLVM's optimization or analysis passes +in any order. The B<-help> option lists all the passes available. The order in +which the options occur on the command line are the order in which they are +executed (within pass constraints). + +=item B<-std-compile-opts> + +This is short hand for a standard list of I<compile time optimization> passes. +This is typically used to optimize the output from the llvm-gcc front end. It +might be useful for other front end compilers as well. To discover the full set +of options available, use the following command: + + llvm-as < /dev/null | opt -std-compile-opts -disable-output -debug-pass=Arguments + +=item B<-disable-inlining> + +This option is only meaningful when B<-std-compile-opts> is given. It simply +removes the inlining pass from the standard list. + +=item B<-disable-opt> + +This option is only meaningful when B<-std-compile-opts> is given. It disables +most, but not all, of the B<-std-compile-opts>. The ones that remain are +B<-verify>, B<-lower-setjmp>, and B<-funcresolve>. + +=item B<-strip-debug> + +This option causes opt to strip debug information from the module before +applying other optimizations. It is essentially the same as B<-strip> but it +ensures that stripping of debug information is done first. + +=item B<-verify-each> + +This option causes opt to add a verify pass after every pass otherwise specified +on the command line (including B<-verify>). This is useful for cases where it +is suspected that a pass is creating an invalid module but it is not clear which +pass is doing it. The combination of B<-std-compile-opts> and B<-verify-each> +can quickly track down this kind of problem. + +=item B<-profile-info-file> I<filename> + +Specify the name of the file loaded by the -profile-loader option. + +=item B<-stats> + +Print statistics. + +=item B<-time-passes> + +Record the amount of time needed for each pass and print it to standard +error. + +=item B<-debug> + +If this is a debug build, this option will enable debug printouts +from passes which use the I<DEBUG()> macro. See the B<LLVM Programmer's +Manual>, section I<#DEBUG> for more information. + +=item B<-load>=I<plugin> + +Load the dynamic object I<plugin>. This object should register new optimization +or analysis passes. Once loaded, the object will add new command line options to +enable various optimizations or analyses. To see the new complete list of +optimizations, use the B<-help> and B<-load> options together. For example: + + opt -load=plugin.so -help + +=item B<-p> + +Print module after each transformation. + +=back + +=head1 EXIT STATUS + +If B<opt> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/main/CommandGuide/tblgen.pod b/docs/main/CommandGuide/tblgen.pod new file mode 100644 index 0000000..d127492 --- /dev/null +++ b/docs/main/CommandGuide/tblgen.pod @@ -0,0 +1,115 @@ + +=pod + +=head1 NAME + +tblgen - Target Description To C++ Code Generator + +=head1 SYNOPSIS + +B<tblgen> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +B<tblgen> translates from target description (.td) files into C++ code that can +be included in the definition of an LLVM target library. Most users of LLVM will +not need to use this program. It is only for assisting with writing an LLVM +target backend. + +The input and output of B<tblgen> is beyond the scope of this short +introduction. Please see the I<CodeGeneration> page in the LLVM documentation. + +The F<filename> argument specifies the name of a Target Description (.td) file +to read as input. + +=head1 OPTIONS + +=over + +=item B<-help> + +Print a summary of command line options. + +=item B<-o> F<filename> + +Specify the output file name. If F<filename> is C<->, then B<tblgen> +sends its output to standard output. + +=item B<-I> F<directory> + +Specify where to find other target description files for inclusion. The +F<directory> value should be a full or partial path to a directory that contains +target description files. + +=item B<-asmwriternum> F<N> + +Make -gen-asm-writer emit assembly writer number F<N>. + +=item B<-class> F<class Name> + +Print the enumeration list for this class. + +=item B<-print-records> + +Print all records to standard output (default). + +=item B<-print-enums> + +Print enumeration values for a class + +=item B<-gen-emitter> + +Generate machine code emitter. + +=item B<-gen-register-enums> + +Generate the enumeration values for all registers. + +=item B<-gen-register-desc> + +Generate a register info description for each register. + +=item B<-gen-register-desc-header> + +Generate a register info description header for each register. + +=item B<-gen-instr-enums> + +Generate enumeration values for instructions. + +=item B<-gen-instr-desc> + +Generate instruction descriptions. + +=item B<-gen-asm-writer> + +Generate the assembly writer. + +=item B<-gen-dag-isel> + +Generate a DAG (Directed Acycle Graph) instruction selector. + +=item B<-gen-subtarget> + +Generate subtarget enumerations. + +=item B<-gen-intrinsic> + +Generate intrinsic information. + +=item B<-version> + +Show the version number of this program. + +=back + +=head1 EXIT STATUS + +If B<tblgen> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 AUTHORS + +Maintained by The LLVM Team (L<http://llvm.org>). + +=cut |