diff options
Diffstat (limited to 'docs/CommandGuide')
46 files changed, 3761 insertions, 3968 deletions
diff --git a/docs/CommandGuide/FileCheck.pod b/docs/CommandGuide/FileCheck.rst index 2662cc012889..51a9bf6293b3 100644 --- a/docs/CommandGuide/FileCheck.pod +++ b/docs/CommandGuide/FileCheck.rst @@ -1,67 +1,87 @@ +FileCheck - Flexible pattern matching file verifier +=================================================== -=pod -=head1 NAME +SYNOPSIS +-------- -FileCheck - Flexible pattern matching file verifier -=head1 SYNOPSIS +**FileCheck** *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] + -B<FileCheck> I<match-filename> [I<--check-prefix=XXX>] [I<--strict-whitespace>] +DESCRIPTION +----------- -=head1 DESCRIPTION -B<FileCheck> reads two files (one from standard input, and one specified on the +**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 +The *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 +OPTIONS +------- + + + +**-help** + + Print a summary of command line options. + + + +**--check-prefix** *prefix* + + FileCheck searches the contents of *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 **--check-prefix** argument allows you to specify + a specific prefix to match. + -=item B<-help> -Print a summary of command line options. +**--strict-whitespace** -=item B<--check-prefix> I<prefix> + 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. -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. +**-version** -=item B<-version> + Show the version number of this program. -Show the version number of this program. -=back -=head1 EXIT STATUS -If B<FileCheck> verifies that the file matches the expected contents, it exits +EXIT STATUS +----------- + + +If **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 + +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 + +.. code-block:: llvm + + ; 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 @@ -69,21 +89,25 @@ 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, let's look at the rest of the .ll file (after the RUN line): - define void @sub1(i32* %p, i32 %v) { - entry: - ; CHECK: sub1: - ; CHECK: subl - %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) - ret void - } - - define void @inc4(i64* %p) { - entry: - ; CHECK: inc4: - ; CHECK: incq - %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1) - ret void - } + +.. code-block:: llvm + + define void @sub1(i32* %p, i32 %v) { + entry: + ; CHECK: sub1: + ; CHECK: subl + %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) + ret void + } + + define void @inc4(i64* %p) { + entry: + ; CHECK: inc4: + ; CHECK: incq + %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 @@ -102,35 +126,40 @@ 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. +The FileCheck -check-prefix option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -=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: | FileCheck %s -check-prefix=X32> - ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ - ; RUN: | FileCheck %s -check-prefix=X64> - - 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 - ; X32: pinsrd_1: - ; X32: pinsrd $1, 4(%esp), %xmm0 - - ; X64: pinsrd_1: - ; X64: pinsrd $1, %edi, %xmm0 - } + +.. code-block:: llvm + + ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \ + ; RUN: | FileCheck %s -check-prefix=X32 + ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ + ; RUN: | FileCheck %s -check-prefix=X64 + + 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 + ; X32: pinsrd_1: + ; X32: pinsrd $1, 4(%esp), %xmm0 + + ; X64: pinsrd_1: + ; X64: 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. +The "CHECK-NEXT:" directive +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -=head2 The "CHECK-NEXT:" directive Sometimes you want to match lines and would like to verify that matches happen on exactly consecutive lines with no other lines in between them. In @@ -138,64 +167,78 @@ 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 - - ; CHECK: t2: - ; CHECK: movl 8(%esp), %eax - ; CHECK-NEXT: movapd (%eax), %xmm0 - ; CHECK-NEXT: movhpd 12(%esp), %xmm0 - ; CHECK-NEXT: movl 4(%esp), %eax - ; CHECK-NEXT: movapd %xmm0, (%eax) - ; CHECK-NEXT: ret - } + +.. code-block:: llvm + + 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 + + ; CHECK: t2: + ; CHECK: movl 8(%esp), %eax + ; CHECK-NEXT: movapd (%eax), %xmm0 + ; CHECK-NEXT: movhpd 12(%esp), %xmm0 + ; CHECK-NEXT: movl 4(%esp), %eax + ; CHECK-NEXT: movapd %xmm0, (%eax) + ; CHECK-NEXT: 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. +The "CHECK-NOT:" directive +~~~~~~~~~~~~~~~~~~~~~~~~~~ -=head2 The "CHECK-NOT:" directive The CHECK-NOT: directive is used to verify that a string doesn't occur between two matches (or before the first match, or after the last match). 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 - ; CHECK: @coerce_offset0 - ; CHECK-NOT: load - ; CHECK: ret i8 - } +.. code-block:: llvm + + 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 + ; CHECK: @coerce_offset0 + ; CHECK-NOT: load + ; CHECK: ret i8 + } -=head2 FileCheck Pattern Matching Syntax +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 +double braces: **{{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 {{[0-9]+}}(%esp), {{%xmm[0-7]}} + +.. code-block:: llvm + + ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}} + In this case, any offset from the ESP register will be allowed, and any xmm register will be allowed. @@ -204,11 +247,12 @@ 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. +**{{[{][{]}}** as your pattern. +FileCheck Variables +~~~~~~~~~~~~~~~~~~~ -=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, @@ -216,30 +260,25 @@ 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 [[REGISTER:%[a-z]+]] - ; CHECK: andw {{.*}}[REGISTER]] -The first check line matches a regex (B<%[a-z]+>) and captures it into +.. code-block:: llvm + + ; CHECK: test5: + ; CHECK: notw [[REGISTER:%[a-z]+]] + ; CHECK: andw {{.*}}[[REGISTER]] + + +The first check line matches a regex (**%[a-z]+**) and captures it into the variable "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 B<[[ ]]> pairs, are named, and their names can be -formed with the regex "B<[a-zA-Z_][a-zA-Z0-9_]*>". If a colon follows the +always contained in **[[ ]]** pairs, are named, and their names can be 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 -"B<CHECK: [[XYZ:.*]]x[[XYZ]]>", the check line will read the previous +"**CHECK: [[XYZ:.\\*]]x[[XYZ]]**", 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/CommandGuide/Makefile b/docs/CommandGuide/Makefile deleted file mode 100644 index 3f9f60b8e7fb..000000000000 --- a/docs/CommandGuide/Makefile +++ /dev/null @@ -1,103 +0,0 @@ -##===- docs/CommandGuide/Makefile --------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -ifdef BUILD_FOR_WEBSITE -# This special case is for keeping the CommandGuide on the LLVM web site -# up to date automatically as the documents are checked in. It must build -# the POD files to HTML only and keep them in the src directories. It must also -# build in an unconfigured tree, hence the ifdef. To use this, run -# make -s BUILD_FOR_WEBSITE=1 inside the cvs commit script. -SRC_DOC_DIR= -DST_HTML_DIR=html/ -DST_MAN_DIR=man/man1/ -DST_PS_DIR=ps/ - -# If we are in BUILD_FOR_WEBSITE mode, default to the all target. -all:: html man ps - -clean: - rm -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -# To create other directories, as needed, and timestamp their creation -%/.dir: - -mkdir $* > /dev/null - date > $@ - -else - -# Otherwise, if not in BUILD_FOR_WEBSITE mode, use the project info. -LEVEL := ../.. -include $(LEVEL)/Makefile.common - -SRC_DOC_DIR=$(PROJ_SRC_DIR)/ -DST_HTML_DIR=$(PROJ_OBJ_DIR)/ -DST_MAN_DIR=$(PROJ_OBJ_DIR)/ -DST_PS_DIR=$(PROJ_OBJ_DIR)/ - -endif - - -POD := $(wildcard $(SRC_DOC_DIR)*.pod) -HTML := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_HTML_DIR)%.html, $(POD)) -MAN := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_MAN_DIR)%.1, $(POD)) -PS := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_PS_DIR)%.ps, $(POD)) - -# The set of man pages we will not install -NO_INSTALL_MANS = $(DST_MAN_DIR)FileCheck.1 $(DST_MAN_DIR)llvm-build.1 - -# The set of man pages that we will install -INSTALL_MANS = $(filter-out $(NO_INSTALL_MANS), $(MAN)) - -.SUFFIXES: -.SUFFIXES: .html .pod .1 .ps - -$(DST_HTML_DIR)%.html: %.pod $(DST_HTML_DIR)/.dir - pod2html --css=manpage.css --htmlroot=. \ - --podpath=. --noindex --infile=$< --outfile=$@ --title=$* - -$(DST_MAN_DIR)%.1: %.pod $(DST_MAN_DIR)/.dir - pod2man --release=CVS --center="LLVM Command Guide" $< $@ - -$(DST_PS_DIR)%.ps: $(DST_MAN_DIR)%.1 $(DST_PS_DIR)/.dir - groff -Tps -man $< > $@ - - -html: $(HTML) -man: $(MAN) -ps: $(PS) - -EXTRA_DIST := $(POD) index.html - -clean-local:: - $(Verb) $(RM) -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/CommandGuide -MAN_DIR := $(DESTDIR)$(PROJ_mandir)/man1 -PS_DIR := $(DESTDIR)$(PROJ_docsdir)/ps - -install-local:: $(HTML) $(INSTALL_MANS) $(PS) - $(Echo) Installing HTML CommandGuide Documentation - $(Verb) $(MKDIR) $(HTML_DIR) - $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) - $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/index.html $(HTML_DIR) - $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR) - $(Echo) Installing MAN CommandGuide Documentation - $(Verb) $(MKDIR) $(MAN_DIR) - $(Verb) $(DataInstall) $(INSTALL_MANS) $(MAN_DIR) - $(Echo) Installing PS CommandGuide Documentation - $(Verb) $(MKDIR) $(PS_DIR) - $(Verb) $(DataInstall) $(PS) $(PS_DIR) - -uninstall-local:: - $(Echo) Uninstalling CommandGuide Documentation - $(Verb) $(RM) -rf $(HTML_DIR) $(MAN_DIR) $(PS_DIR) - -printvars:: - $(Echo) "POD : " '$(POD)' - $(Echo) "HTML : " '$(HTML)' diff --git a/docs/CommandGuide/bugpoint.pod b/docs/CommandGuide/bugpoint.pod deleted file mode 100644 index 31db62fe2d6b..000000000000 --- a/docs/CommandGuide/bugpoint.pod +++ /dev/null @@ -1,186 +0,0 @@ -=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<--opt-args> I<opt args> - -Pass all arguments specified after B<--opt-args> to the invocation of B<opt>. - -=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<--compile-command> I<command> - -This option defines the command to use with the B<--compile-custom> -option to compile the bitcode testcase. This can be useful for -testing compiler output without running any link or execute stages. To -generate a reduced unit test, you may add CHECK directives to the -testcase and pass the name of an executable compile-command script in this form: - - #!/bin/sh - llc "$@" - not FileCheck [bugpoint input file].ll < bugpoint-test-program.s - -This script will "fail" as long as FileCheck passes. So the result -will be the minimum bitcode that passes FileCheck. - -=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/CommandGuide/bugpoint.rst b/docs/CommandGuide/bugpoint.rst new file mode 100644 index 000000000000..c1b3b6eca627 --- /dev/null +++ b/docs/CommandGuide/bugpoint.rst @@ -0,0 +1,247 @@ +bugpoint - automatic test case reduction tool +============================================= + + +SYNOPSIS +-------- + + +**bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args** +*program arguments* + + +DESCRIPTION +----------- + + +**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 **bugpoint**, as well as +advice for using bugpoint, see *llvm/docs/Bugpoint.html* in the LLVM +distribution. + + +OPTIONS +------- + + + +**--additional-so** *library* + + Load the dynamic shared object *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. + + + +**--append-exit-code**\ =\ *{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. + + + +**--args** *program args* + + Pass all arguments specified after -args to the test program whenever it runs. + Note that if any of the *program args* start with a '-', you should use: + + + .. code-block:: perl + + bugpoint [bugpoint args] --args -- [program args] + + + The "--" right after the **--args** option tells **bugpoint** to consider any + options starting with ``-`` to be part of the **--args** option, not as options to + **bugpoint** itself. + + + +**--tool-args** *tool args* + + Pass all arguments specified after --tool-args to the LLVM tool under test + (**llc**, **lli**, etc.) whenever it runs. You should use this option in the + following way: + + + .. code-block:: perl + + bugpoint [bugpoint args] --tool-args -- [tool args] + + + The "--" right after the **--tool-args** option tells **bugpoint** to consider any + options starting with ``-`` to be part of the **--tool-args** option, not as + options to **bugpoint** itself. (See **--args**, above.) + + + +**--safe-tool-args** *tool args* + + Pass all arguments specified after **--safe-tool-args** to the "safe" execution + tool. + + + +**--gcc-tool-args** *gcc tool args* + + Pass all arguments specified after **--gcc-tool-args** to the invocation of + **gcc**. + + + +**--opt-args** *opt args* + + Pass all arguments specified after **--opt-args** to the invocation of **opt**. + + + +**--disable-{dce,simplifycfg}** + + Do not run the specified passes to clean up and reduce the size of the test + program. By default, **bugpoint** uses these passes internally when attempting to + reduce test programs. If you're trying to find a bug in one of these passes, + **bugpoint** may crash. + + + +**--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. + + + +**-find-bugs** + + Continually randomize the specified passes and run them on the test program + until a bug is found or the user kills **bugpoint**. + + + +**-help** + + Print a summary of command line options. + + + +**--input** *filename* + + Open *filename* and redirect the standard input of the test program, whenever + it runs, to come from that file. + + + +**--load** *plugin* + + Load the dynamic object *plugin* into **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 **-help** and **--load** options together; for example: + + + .. code-block:: perl + + bugpoint --load myNewPass.so -help + + + + +**--mlimit** *megabytes* + + Specifies an upper limit on memory usage of the optimization and codegen. Set + to zero to disable the limit. + + + +**--output** *filename* + + Whenever the test program produces output on its standard output stream, it + should match the contents of *filename* (the "reference output"). If you + do not use this option, **bugpoint** will attempt to generate a reference output + by compiling the program with the "safe" backend and running it. + + + +**--profile-info-file** *filename* + + Profile file loaded by **--profile-loader**. + + + +**--run-{int,jit,llc,custom}** + + Whenever the test program is compiled, **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, or a + custom command (see **--exec-command**) respectively. + + + +**--safe-{llc,custom}** + + When debugging a code generator, **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, or a custom command, (see **--exec-command**) + respectively. The interpreter and the JIT backends cannot currently + be used as the "safe" backends. + + + +**--exec-command** *command* + + This option defines the command to use with the **--run-custom** and + **--safe-custom** options to execute the bitcode testcase. This can + be useful for cross-compilation. + + + +**--compile-command** *command* + + This option defines the command to use with the **--compile-custom** + option to compile the bitcode testcase. This can be useful for + testing compiler output without running any link or execute stages. To + generate a reduced unit test, you may add CHECK directives to the + testcase and pass the name of an executable compile-command script in this form: + + + .. code-block:: sh + + #!/bin/sh + llc "$@" + not FileCheck [bugpoint input file].ll < bugpoint-test-program.s + + + This script will "fail" as long as FileCheck passes. So the result + will be the minimum bitcode that passes FileCheck. + + + +**--safe-path** *path* + + This option defines the path to the command to execute with the + **--safe-{int,jit,llc,custom}** + option. + + + + +EXIT STATUS +----------- + + +If **bugpoint** succeeds in finding a problem, it will exit with 0. Otherwise, +if an error occurs, it will exit with a non-zero value. + + +SEE ALSO +-------- + + +opt|opt diff --git a/docs/CommandGuide/html/manpage.css b/docs/CommandGuide/html/manpage.css deleted file mode 100644 index b2003434901d..000000000000 --- a/docs/CommandGuide/html/manpage.css +++ /dev/null @@ -1,256 +0,0 @@ -/* 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/CommandGuide/index.html b/docs/CommandGuide/index.html deleted file mode 100644 index 74ac0048d3f5..000000000000 --- a/docs/CommandGuide/index.html +++ /dev/null @@ -1,142 +0,0 @@ -<!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> - -<h1> - LLVM Command Guide -</h1> - -<div> - -<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> - -<!-- *********************************************************************** --> -<h2> - <a name="basic">Basic Commands</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<ul> - -<li><a href="/cmds/llvm-as.html"><b>llvm-as</b></a> - - assemble a human-readable .ll file into bytecode</li> - -<li><a href="/cmds/llvm-dis.html"><b>llvm-dis</b></a> - - disassemble a bytecode file into a human-readable .ll file</li> - -<li><a href="/cmds/opt.html"><b>opt</b></a> - - run a series of LLVM-to-LLVM optimizations on a bytecode file</li> - -<li><a href="/cmds/llc.html"><b>llc</b></a> - - generate native machine code for a bytecode file</li> - -<li><a href="/cmds/lli.html"><b>lli</b></a> - - directly run a program compiled to bytecode using a JIT compiler or - interpreter</li> - -<li><a href="/cmds/llvm-link.html"><b>llvm-link</b></a> - - link several bytecode files into one</li> - -<li><a href="/cmds/llvm-ar.html"><b>llvm-ar</b></a> - - archive bytecode files</li> - -<li><a href="/cmds/llvm-ranlib.html"><b>llvm-ranlib</b></a> - - create an index for archives made with llvm-ar</li> - -<li><a href="/cmds/llvm-nm.html"><b>llvm-nm</b></a> - - print out the names and types of symbols in a bytecode file</li> - -<li><a href="/cmds/llvm-prof.html"><b>llvm-prof</b></a> - - format raw `<tt>llvmprof.out</tt>' data into a human-readable report</li> - -<li><a href="/cmds/llvm-ld.html"><b>llvm-ld</b></a> - - general purpose linker with loadable runtime optimization support</li> - -<li><a href="/cmds/llvm-config.html"><b>llvm-config</b></a> - - print out LLVM compilation options, libraries, etc. as configured</li> - -<li><a href="/cmds/llvm-diff.html"><b>llvm-diff</b></a> - - structurally compare two modules</li> - -<li><a href="/cmds/llvm-cov.html"><b>llvm-cov</b></a> - - emit coverage information</li> - -<li><a href="/cmds/llvm-stress.html"><b>llvm-stress</b></a> - - generate random .ll files to fuzz different llvm components</li> - -</ul> - -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="debug">Debugging Tools</a> -</h2> -<!-- *********************************************************************** --> - - -<div> - -<ul> - -<li><a href="/cmds/bugpoint.html"><b>bugpoint</b></a> - - automatic test-case reducer</li> - -<li><a href="/cmds/llvm-extract.html"><b>llvm-extract</b></a> - - extract a function from an LLVM bytecode file</li> - -<li><a href="/cmds/llvm-bcanalyzer.html"><b>llvm-bcanalyzer</b></a> - - bytecode analyzer (analyzes the binary encoding itself, not the program it - represents)</li> - -</ul> -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="internal">Internal Tools</a> -</h2> -<!-- *********************************************************************** --> - -<div> -<ul> - -<li><a href="/cmds/FileCheck.html"><b>FileCheck</b></a> - - Flexible file verifier used extensively by the testing harness</li> -<li><a href="/cmds/tblgen.html"><b>tblgen</b></a> - - target description reader and generator</li> -<li><a href="/cmds/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: 2012-02-26 09:35:53 +0100 (Sun, 26 Feb 2012) $ -</address> - -</body> -</html> diff --git a/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst new file mode 100644 index 000000000000..73a4835dd7a1 --- /dev/null +++ b/docs/CommandGuide/index.rst @@ -0,0 +1,53 @@ +.. _commands: + +LLVM Command Guide +------------------ + +The following documents are command descriptions 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 ``--help`` (general options) or +``--help-hidden`` (general and debugging options) arguments to the tool you are +interested in. + +Basic Commands +~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + llvm-as + llvm-dis + opt + llc + lli + llvm-link + llvm-ar + llvm-ranlib + llvm-nm + llvm-prof + llvm-config + llvm-diff + llvm-cov + llvm-stress + +Debugging Tools +~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + bugpoint + llvm-extract + llvm-bcanalyzer + +Developer Tools +~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + FileCheck + tblgen + lit + llvm-build diff --git a/docs/CommandGuide/lit.pod b/docs/CommandGuide/lit.pod deleted file mode 100644 index 81fc2c918046..000000000000 --- a/docs/CommandGuide/lit.pod +++ /dev/null @@ -1,404 +0,0 @@ -=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 executed -(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 INFRASTRUCTURE"> - -=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 are 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 feature 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|"OUTPUT OPTIONS"> -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 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 -placed. - -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 is 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<root> The root configuration. This is the top-most B<lit> configuration in -the project. - -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 nested 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 TEST RUN OUTPUT FORMAT - -The b<lit> output for a test run conforms to the following schema, in both short -and verbose modes (although in short mode no PASS lines will be shown). This -schema has been chosen to be relatively easy to reliably parse by a machine (for -example in buildbot log scraping), and for other tools to generate. - -Each test result is expected to appear on a line that matches: - -<result code>: <test name> (<progress info>) - -where <result-code> is a standard test result such as PASS, FAIL, XFAIL, XPASS, -UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and -REGRESSED are also allowed. - -The <test name> field can consist of an arbitrary string containing no newline. - -The <progress info> field can be used to report progress information such as -(1/300) or can be empty, but even when empty the parentheses are required. - -Each test result may include additional (multiline) log information in the -following format. - -<log delineator> TEST '(<test name>)' <trailing delineator> -... log message ... -<log delineator> - -where <test name> should be the name of a preceeding reported test, <log -delineator> is a string of '*' characters I<at least> four characters long (the -recommended length is 20), and <trailing delineator> is an arbitrary (unparsed) -string. - -The following is an example of a test run output which consists of four tests A, -B, C, and D, and a log message for the failing test C. - -=head3 Example Test Run Output Listing - -PASS: A (1 of 4) -PASS: B (2 of 4) -FAIL: C (3 of 4) -******************** TEST 'C' FAILED ******************** -Test 'C' failed as a result of exit code 1. -******************** -PASS: D (4 of 4) - -=back - -=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/CommandGuide/lit.rst b/docs/CommandGuide/lit.rst new file mode 100644 index 000000000000..3eb0be91f137 --- /dev/null +++ b/docs/CommandGuide/lit.rst @@ -0,0 +1,474 @@ +lit - LLVM Integrated Tester +============================ + + +SYNOPSIS +-------- + + +**lit** [*options*] [*tests*] + + +DESCRIPTION +----------- + + +**lit** is a portable tool for executing LLVM and Clang style test suites, +summarizing their results, and providing indication of failures. **lit** is +designed to be a lightweight testing tool with as simple a user interface as +possible. + +**lit** should be run with one or more *tests* to run specified on the command +line. Tests can be either individual test files or directories to search for +tests (see "TEST DISCOVERY"). + +Each specified test will be executed (potentially in parallel) and once all +tests have been run **lit** will print summary information on the number of tests +which passed or failed (see "TEST STATUS RESULTS"). The **lit** program will +execute with a non-zero exit code if any tests fail. + +By default **lit** will use a succinct progress display and will only print +summary information for test failures. See "OUTPUT OPTIONS" for options +controlling the **lit** progress display and output. + +**lit** also includes a number of options for controlling how tests are executed +(specific features may depend on the particular test format). See "EXECUTION +OPTIONS" for more information. + +Finally, **lit** also supports additional options for only running a subset of +the options specified on the command line, see "SELECTION OPTIONS" for +more information. + +Users interested in the **lit** architecture or designing a **lit** testing +implementation should see "LIT INFRASTRUCTURE" + + +GENERAL OPTIONS +--------------- + + + +**-h**, **--help** + + Show the **lit** help message. + + + +**-j** *N*, **--threads**\ =\ *N* + + Run *N* tests in parallel. By default, this is automatically chosen to match + the number of detected available CPUs. + + + +**--config-prefix**\ =\ *NAME* + + Search for *NAME.cfg* and *NAME.site.cfg* when searching for test suites, + instead of *lit.cfg* and *lit.site.cfg*. + + + +**--param** *NAME*, **--param** *NAME*\ =\ *VALUE* + + Add a user defined parameter *NAME* with the given *VALUE* (or the empty + string if not given). The meaning and use of these parameters is test suite + dependent. + + + + +OUTPUT OPTIONS +-------------- + + + +**-q**, **--quiet** + + Suppress any output except for test failures. + + + +**-s**, **--succinct** + + Show less output, for example don't show information on tests that pass. + + + +**-v**, **--verbose** + + Show more information on test failures, for example the entire test output + instead of just the test result. + + + +**--no-progress-bar** + + Do not use curses based progress bar. + + + + +EXECUTION OPTIONS +----------------- + + + +**--path**\ =\ *PATH* + + Specify an addition *PATH* to use when searching for executables in tests. + + + +**--vg** + + Run individual tests under valgrind (using the memcheck tool). The + *--error-exitcode* argument for valgrind is used so that valgrind failures will + cause the program to exit with a non-zero status. + + + +**--vg-arg**\ =\ *ARG* + + When *--vg* is used, specify an additional argument to pass to valgrind itself. + + + +**--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 *-j + 1*. + + + + +SELECTION OPTIONS +----------------- + + + +**--max-tests**\ =\ *N* + + Run at most *N* tests and then terminate. + + + +**--max-time**\ =\ *N* + + Spend at most *N* seconds (approximately) running tests and then terminate. + + + +**--shuffle** + + Run the tests in a random order. + + + + +ADDITIONAL OPTIONS +------------------ + + + +**--debug** + + Run **lit** in debug mode, for debugging configuration issues and **lit** itself. + + + +**--show-suites** + + List the discovered test suites as part of the standard output. + + + +**--no-tcl-as-sh** + + Run Tcl scripts internally (instead of converting to shell scripts). + + + +**--repeat**\ =\ *N* + + Run each test *N* times. Currently this is primarily useful for timing tests, + other results are not collated in any reasonable fashion. + + + + +EXIT STATUS +----------- + + +**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 are used +for non-test related failures (for example a user error or an internal program +error). + + +TEST DISCOVERY +-------------- + + +The inputs passed to **lit** can be either individual tests, or entire +directories or hierarchies of tests to run. When **lit** starts up, the first +thing it does is convert the inputs into a complete list of tests to run as part +of *test discovery*. + +In the **lit** model, every test must exist inside some *test suite*. **lit** +resolves the inputs specified on the command line to test suites by searching +upwards from the input path until it finds a *lit.cfg* or *lit.site.cfg* +file. These files serve as both a marker of test suites and as configuration +files which **lit** loads in order to understand how to find and run the tests +inside the test suite. + +Once **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, **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 **lit** to provide convenient and flexible +support for out-of-tree builds. + + +TEST STATUS RESULTS +------------------- + + +Each test ultimately produces one of the following six results: + + +**PASS** + + The test succeeded. + + + +**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. + + + +**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 feature they test was broken and has been fixed). + + + +**FAIL** + + The test failed. + + + +**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. + + + +**UNSUPPORTED** + + The test is not supported in this environment. This is used by test formats + which can report unsupported tests. + + + +Depending on the test format tests may produce additional information about +their status (generally only for failures). See the Output|"OUTPUT OPTIONS" +section for more information. + + +LIT INFRASTRUCTURE +------------------ + + +This section describes the **lit** testing architecture for users interested in +creating a new **lit** testing implementation, or extending an existing one. + +**lit** proper is primarily an infrastructure for discovering and running +arbitrary tests, and to expose a single convenient interface to these +tests. **lit** itself doesn't know how to run tests, rather this logic is +defined by *test suites*. + +TEST SUITES +~~~~~~~~~~~ + + +As described in "TEST DISCOVERY", tests are always located inside a *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. + +**lit** identifies test suites as directories containing *lit.cfg* or +*lit.site.cfg* files (see also **--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 **--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 Python modules which will be executed. When the config file is +executed, two important global variables are predefined: + + +**lit** + + The global **lit** configuration object (a *LitConfig* instance), which defines + the builtin test formats, global configuration parameters, and other helper + routines for implementing test configurations. + + + +**config** + + This is the config object (a *TestingConfig* instance) for the test suite, + which the config file is expected to populate. The following variables are also + available on the *config* object, some of which must be set by the config and + others are optional or predefined: + + **name** *[required]* The name of the test suite, for use in reports and + diagnostics. + + **test_format** *[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 *lit.formats* module. + + **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. + + **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 + placed. + + **environment** A dictionary representing the environment to use when executing + tests in the suite. + + **suffixes** For **lit** test formats which scan directories for tests, this + variable is a list of suffixes to identify test files. Used by: *ShTest*, + *TclTest*. + + **substitutions** For **lit** test formats which substitute variables into a test + script, the list of substitutions to perform. Used by: *ShTest*, *TclTest*. + + **unsupported** Mark an unsupported directory, all tests within it will be + reported as unsupported. Used by: *ShTest*, *TclTest*. + + **parent** The parent configuration, this is the config object for the directory + containing the test suite, or None. + + **root** The root configuration. This is the top-most **lit** configuration in + the project. + + **on_clone** The config is actually cloned for every subdirectory inside a test + suite, to allow local configuration on a per-directory basis. The *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 + *on_clone* function will generally modify), and (3) the test path to the new + directory being scanned. + + + + +TEST DISCOVERY +~~~~~~~~~~~~~~ + + +Once test suites are located, **lit** recursively traverses the source directory +(following *test_src_root*) looking for tests. When **lit** enters a +sub-directory, it first checks to see if a nested 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 "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 *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. + + +LOCAL CONFIGURATION FILES +~~~~~~~~~~~~~~~~~~~~~~~~~ + + +When **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 **lit** checks for a *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. + + +TEST RUN OUTPUT FORMAT +~~~~~~~~~~~~~~~~~~~~~~ + + +The b<lit> output for a test run conforms to the following schema, in both short +and verbose modes (although in short mode no PASS lines will be shown). This +schema has been chosen to be relatively easy to reliably parse by a machine (for +example in buildbot log scraping), and for other tools to generate. + +Each test result is expected to appear on a line that matches: + +<result code>: <test name> (<progress info>) + +where <result-code> is a standard test result such as PASS, FAIL, XFAIL, XPASS, +UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and +REGRESSED are also allowed. + +The <test name> field can consist of an arbitrary string containing no newline. + +The <progress info> field can be used to report progress information such as +(1/300) or can be empty, but even when empty the parentheses are required. + +Each test result may include additional (multiline) log information in the +following format. + +<log delineator> TEST '(<test name>)' <trailing delineator> +... log message ... +<log delineator> + +where <test name> should be the name of a preceding reported test, <log +delineator> is a string of '\*' characters *at least* four characters long (the +recommended length is 20), and <trailing delineator> is an arbitrary (unparsed) +string. + +The following is an example of a test run output which consists of four tests A, +B, C, and D, and a log message for the failing test C:: + + PASS: A (1 of 4) + PASS: B (2 of 4) + FAIL: C (3 of 4) + \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* TEST 'C' FAILED \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* + Test 'C' failed as a result of exit code 1. + \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* + PASS: D (4 of 4) + + +LIT EXAMPLE TESTS +~~~~~~~~~~~~~~~~~ + + +The **lit** distribution contains several example implementations of test suites +in the *ExampleTests* directory. + + +SEE ALSO +-------- + + +valgrind(1) diff --git a/docs/CommandGuide/llc.pod b/docs/CommandGuide/llc.pod deleted file mode 100644 index 35abdaeb2b15..000000000000 --- a/docs/CommandGuide/llc.pod +++ /dev/null @@ -1,201 +0,0 @@ -=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>, and I<-O3> 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-no-infs-fp-math> - -Enable optimizations that assume no Inf values. - -=item B<--enable-no-nans-fp-math> - -Enable optimizations that assume no NAN values. - -=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/CommandGuide/llc.rst b/docs/CommandGuide/llc.rst new file mode 100644 index 000000000000..6f1c486c3f42 --- /dev/null +++ b/docs/CommandGuide/llc.rst @@ -0,0 +1,251 @@ +llc - LLVM static compiler +========================== + + +SYNOPSIS +-------- + + +**llc** [*options*] [*filename*] + + +DESCRIPTION +----------- + + +The **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 **-march** option is used to override +the default. + + +OPTIONS +------- + + +If *filename* is - or omitted, **llc** reads from standard input. Otherwise, it +will from *filename*. Inputs can be in either the LLVM assembly language +format (.ll) or the LLVM bitcode format (.bc). + +If the **-o** option is omitted, then **llc** will send its output to standard +output if the input is from standard input. If the **-o** option specifies -, +then the output will also be sent to standard output. + +If no **-o** option is specified and an input file other than - is specified, +then **llc** creates the output filename by taking the input filename, +removing any existing *.bc* extension, and adding a *.s* suffix. + +Other **llc** options are as follows: + +End-user Options +~~~~~~~~~~~~~~~~ + + + +**-help** + + Print a summary of command line options. + + + +**-O**\ =\ *uint* + + Generate code at different optimization levels. These correspond to the *-O0*, + *-O1*, *-O2*, and *-O3* optimization levels used by **llvm-gcc** and + **clang**. + + + +**-mtriple**\ =\ *target triple* + + Override the target triple specified in the input file with the specified + string. + + + +**-march**\ =\ *arch* + + Specify the architecture for which to generate assembly, overriding the target + encoded in the input file. See the output of **llc -help** for a list of + valid architectures. By default this is inferred from the target triple or + autodetected to the current architecture. + + + +**-mcpu**\ =\ *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: + **llvm-as < /dev/null | llc -march=xyz -mcpu=help** + + + +**-mattr**\ =\ *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: + **llvm-as < /dev/null | llc -march=xyz -mattr=help** + + + +**--disable-fp-elim** + + Disable frame pointer elimination optimization. + + + +**--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). + + + +**--enable-no-infs-fp-math** + + Enable optimizations that assume no Inf values. + + + +**--enable-no-nans-fp-math** + + Enable optimizations that assume no NAN values. + + + +**--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). + + + +**--enable-correct-eh-support** + + Instruct the **lowerinvoke** pass to insert code for correct exception handling + support. This is expensive and is by default omitted for efficiency. + + + +**--stats** + + Print statistics recorded by code-generation passes. + + + +**--time-passes** + + Record the amount of time needed for each pass and print a report to standard + error. + + + +**--load**\ =\ *dso_path* + + Dynamically load *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 + **-march** option so that code can be generated for that target. + + + + +Tuning/Configuration Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + +**--print-machineinstrs** + + Print generated machine code between compilation phases (useful for debugging). + + + +**--regalloc**\ =\ *allocator* + + Specify the register allocator to use. The default *allocator* is *local*. + Valid register allocators are: + + + *simple* + + Very simple "always spill" register allocator + + + + *local* + + Local register allocator + + + + *linearscan* + + Linear scan global register allocator + + + + *iterativescan* + + Iterative scan global register allocator + + + + + +**--spiller**\ =\ *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 + *spiller* is *local*. Valid spillers are: + + + *simple* + + Simple spiller + + + + *local* + + Local spiller + + + + + + +Intel IA-32-specific Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + +**--x86-asm-syntax=att|intel** + + Specify whether to emit assembly code in AT&T syntax (the default) or intel + syntax. + + + + + +EXIT STATUS +----------- + + +If **llc** succeeds, it will exit with 0. Otherwise, if an error occurs, +it will exit with a non-zero value. + + +SEE ALSO +-------- + + +lli|lli diff --git a/docs/CommandGuide/lli.pod b/docs/CommandGuide/lli.pod deleted file mode 100644 index a313a31718c4..000000000000 --- a/docs/CommandGuide/lli.pod +++ /dev/null @@ -1,219 +0,0 @@ -=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-no-infs-fp-math> - -Enable optimizations that assume no Inf values. - -=item B<-enable-no-nans-fp-math> - -Enable optimizations that assume no NAN 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/CommandGuide/lli.rst b/docs/CommandGuide/lli.rst new file mode 100644 index 000000000000..7cc128444dac --- /dev/null +++ b/docs/CommandGuide/lli.rst @@ -0,0 +1,300 @@ +lli - directly execute programs from LLVM bitcode +================================================= + + +SYNOPSIS +-------- + + +**lli** [*options*] [*filename*] [*program args*] + + +DESCRIPTION +----------- + + +**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. **lli** takes all of +the same code generator options as llc|llc, but they are only effective when +**lli** is using the just-in-time compiler. + +If *filename* is not specified, then **lli** reads the LLVM bitcode for the +program from standard input. + +The optional *args* specified on the command line are passed to the program as +arguments. + + +GENERAL OPTIONS +--------------- + + + +**-fake-argv0**\ =\ *executable* + + Override the ``argv[0]`` value passed into the executing program. + + + +**-force-interpreter**\ =\ *{false,true}* + + If set to true, use the interpreter even if a just-in-time compiler is available + for this architecture. Defaults to false. + + + +**-help** + + Print a summary of command line options. + + + +**-load**\ =\ *puginfilename* + + Causes **lli** to load the plugin (shared object) named *pluginfilename* and use + it for optimization. + + + +**-stats** + + Print statistics from the code-generation passes. This is only meaningful for + the just-in-time compiler, at present. + + + +**-time-passes** + + Record the amount of time needed for each code-generation pass and print it to + standard error. + + + +**-version** + + Print out the version of **lli** and exit without doing anything else. + + + + +TARGET OPTIONS +-------------- + + + +**-mtriple**\ =\ *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. + + + +**-march**\ =\ *arch* + + Specify the architecture for which to generate assembly, overriding the target + encoded in the bitcode file. See the output of **llc -help** for a list of + valid architectures. By default this is inferred from the target triple or + autodetected to the current architecture. + + + +**-mcpu**\ =\ *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: + **llvm-as < /dev/null | llc -march=xyz -mcpu=help** + + + +**-mattr**\ =\ *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: + **llvm-as < /dev/null | llc -march=xyz -mattr=help** + + + + +FLOATING POINT OPTIONS +---------------------- + + + +**-disable-excess-fp-precision** + + Disable optimizations that may increase floating point precision. + + + +**-enable-no-infs-fp-math** + + Enable optimizations that assume no Inf values. + + + +**-enable-no-nans-fp-math** + + Enable optimizations that assume no NAN values. + + + +**-enable-unsafe-fp-math** + + Causes **lli** to enable optimizations that may decrease floating point + precision. + + + +**-soft-float** + + Causes **lli** to generate software floating point library calls instead of + equivalent hardware instructions. + + + + +CODE GENERATION OPTIONS +----------------------- + + + +**-code-model**\ =\ *model* + + Choose the code model from: + + + .. code-block:: perl + + default: Target default code model + small: Small code model + kernel: Kernel code model + medium: Medium code model + large: Large code model + + + + +**-disable-post-RA-scheduler** + + Disable scheduling after register allocation. + + + +**-disable-spill-fusing** + + Disable fusing of spill code into instructions. + + + +**-enable-correct-eh-support** + + Make the -lowerinvoke pass insert expensive, but correct, EH code. + + + +**-jit-enable-eh** + + Exception handling should be enabled in the just-in-time compiler. + + + +**-join-liveintervals** + + Coalesce copies (default=true). + + + +**-nozero-initialized-in-bss** Don't place zero-initialized symbols into the BSS section. + + + +**-pre-RA-sched**\ =\ *scheduler* + + Instruction schedulers available (before register allocation): + + + .. code-block:: perl + + =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 + + + + +**-regalloc**\ =\ *allocator* + + Register allocator to use (default=linearscan) + + + .. code-block:: perl + + =bigblock: Big-block register allocator + =linearscan: linear scan register allocator =local - local register allocator + =simple: simple register allocator + + + + +**-relocation-model**\ =\ *model* + + Choose relocation model from: + + + .. code-block:: perl + + =default: Target default relocation model + =static: Non-relocatable code =pic - Fully relocatable, position independent code + =dynamic-no-pic: Relocatable external references, non-relocatable code + + + + +**-spiller** + + Spiller to use (default=local) + + + .. code-block:: perl + + =simple: simple spiller + =local: local spiller + + + + +**-x86-asm-syntax**\ =\ *syntax* + + Choose style of code to emit from X86 backend: + + + .. code-block:: perl + + =att: Emit AT&T-style assembly + =intel: Emit Intel-style assembly + + + + + +EXIT STATUS +----------- + + +If **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. + + +SEE ALSO +-------- + + +llc|llc diff --git a/docs/CommandGuide/llvm-ar.pod b/docs/CommandGuide/llvm-ar.pod deleted file mode 100644 index a8f01b0319a0..000000000000 --- a/docs/CommandGuide/llvm-ar.pod +++ /dev/null @@ -1,406 +0,0 @@ -=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/CommandGuide/llvm-ar.rst b/docs/CommandGuide/llvm-ar.rst new file mode 100644 index 000000000000..8ff4192a5007 --- /dev/null +++ b/docs/CommandGuide/llvm-ar.rst @@ -0,0 +1,458 @@ +llvm-ar - LLVM archiver +======================= + + +SYNOPSIS +-------- + + +**llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...] + + +DESCRIPTION +----------- + + +The **llvm-ar** command is similar to the common Unix utility, ``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, +**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 **llvm-ar** command can be used to *read* both SVR4 and BSD style archive +files. However, it cannot be used to write them. While the **llvm-ar** command +produces files that are *almost* identical to the format used by other ``ar`` +implementations, it has two significant departures in order to make the +archive appropriate for LLVM. The first departure is that **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 **llvm-ar** usually won't be readable or editable with any +``ar`` implementation or useful for linking. Using the ``f`` modifier to flatten +file names will make the archive readable by other ``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 ``r`` (replace) or ``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 **llvm-ar** departs from previous ``ar`` implementations: + + +*Symbol Table* + + Since **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. + + + +*Long Paths* + + Some ``ar`` implementations (SVR4) use a separate file member to record long + path names (> 15 characters). **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. + + + +*Directory Recursion* + + Most ``ar`` implementations do not recurse through directories but simply + ignore directories if they are presented to the program in the *files* + option. **llvm-ar**, however, can recurse through directory structures and + add all the files under a directory, if requested. + + + +*TOC Verbose Output* + + When **llvm-ar** prints out the verbose table of contents (``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 'B' means + the file is an LLVM bitcode file. An 'S' means the file is the symbol table. + + + + +OPTIONS +------- + + +The options to **llvm-ar** are compatible with other ``ar`` implementations. +However, there are a few modifiers (*R*) that are not found in other ``ar`` +implementations. The options to **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 **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 ``.a`` suffix, but this is not required. Following +the *archive-name* comes a list of *files* that indicate the specific members +of the archive to operate on. If the *files* option is not specified, it +generally means either "none" or "all" members, depending on the operation. + +Operations +~~~~~~~~~~ + + + +d + + Delete files from the archive. No modifiers are applicable to this operation. + The *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 *files* are specified, the archive is not modified. + + + +m[abi] + + Move files from one location in the archive to another. The *a*, *b*, and + *i* modifiers apply to this operation. The *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 *files* are specified, the + archive is not modified. + + + +p[k] + + Print files to the standard output. The *k* modifier applies to this + operation. This operation simply prints the *files* indicated to the + standard output. If no *files* are specified, the entire archive is printed. + Printing bitcode files is ill-advised as they might confuse your terminal + settings. The *p* operation never modifies the archive. + + + +q[Rf] + + Quickly append files to the end of the archive. The *R*, and *f* + modifiers apply to this operation. This operation quickly adds the + *files* to the archive without checking for duplicates that should be + removed first. If no *files* are specified, the archive is not modified. + Because of the way that **llvm-ar** constructs the archive file, its dubious + whether the *q* operation is any faster than the *r* operation. + + + +r[Rabfu] + + Replace or insert file members. The *R*, *a*, *b*, *f*, and *u* + modifiers apply to this operation. This operation will replace existing + *files* or insert them at the end of the archive if they do not exist. If no + *files* are specified, the archive is not modified. + + + +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 *v* modifier, + **llvm-ar** also prints out the file type (B=bitcode, S=symbol + table, blank=regular file), the permission mode, the owner and group, the + size, and the date. If any *files* are specified, the listing is only for + those files. If no *files* are specified, the table of contents for the + whole archive is printed. + + + +x[oP] + + Extract archive members back to files. The *o* modifier applies to this + operation. This operation retrieves the indicated *files* from the archive + and writes them back to the operating system's file system. If no + *files* are specified, the entire archive is extract. + + + + +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. + + +[a] + + When inserting or moving member files, this option specifies the destination of + the new files as being after the *relpos* member. If *relpos* is not found, + the files are placed at the end of the archive. + + + +[b] + + When inserting or moving member files, this option specifies the destination of + the new files as being before the *relpos* member. If *relpos* is not + found, the files are placed at the end of the archive. This modifier is + identical to the *i* modifier. + + + +[f] + + Normally, **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 ``ar`` but may also + thwart correct extraction of the files (duplicates may overwrite). If used with + the *R* option, the directory recursion will be performed but the file names + will all be flattened to simple file names. + + + +[i] + + A synonym for the *b* option. + + + +[k] + + Normally, **llvm-ar** will not print the contents of bitcode files when the + *p* operation is used. This modifier defeats the default and allows the + bitcode members to be printed. + + + +[N] + + This option is ignored by **llvm-ar** but provided for compatibility. + + + +[o] + + When extracting files, this option will cause **llvm-ar** to preserve the + original modification times of the files it writes. + + + +[P] + + use full path names when matching + + + +[R] + + This modifier instructions the *r* option to recursively process directories. + Without *R*, directories are ignored and only those *files* that refer to + files will be added to the archive. When *R* is used, any directories specified + with *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. + + + +[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. + + + + +Modifiers (generic) +~~~~~~~~~~~~~~~~~~~ + + +The modifiers below may be applied to any operation. + + +[c] + + For all operations, **llvm-ar** will always create the archive if it doesn't + exist. Normally, **llvm-ar** will print a warning message indicating that the + archive is being created. Using this modifier turns off that warning. + + + +[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 + llvm-ranlib|llvm-ranlib which also creates the symbol table. + + + +[S] + + This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to + not build the symbol table. If both *s* and *S* are used, the last modifier to + occur in the options will prevail. + + + +[v] + + This modifier instructs **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. + + + + + +STANDARDS +--------- + + +The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2 +(POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or +Mac OS X) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations +then **llvm-ar** will write SVR4 compatible archives. Without this modifier, +**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. + + +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 ``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. + + +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 ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/`` + is literal. In this case, the actual name of the file is provided in the ``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. + + + +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. + + + +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. + + + +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. + + + +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. + + + +size - char[10] + + This field provides the size of the file, in bytes, encoded as a decimal ASCII + string. + + + +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. + + + +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: + + +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. + + + +length - vbr encoded 32-bit integer + + The length item provides the length of the symbol that follows. Like this + *offset* item, the length is variable bit rate encoded. + + + +symbol - character array + + The symbol item provides the text of the symbol that is associated with the + *offset*. The symbol is not terminated by any character. Its length is provided + by the *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. + + + + +EXIT STATUS +----------- + + +If **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. + + +SEE ALSO +-------- + + +llvm-ranlib|llvm-ranlib, ar(1) diff --git a/docs/CommandGuide/llvm-as.pod b/docs/CommandGuide/llvm-as.pod deleted file mode 100644 index cc8188708a53..000000000000 --- a/docs/CommandGuide/llvm-as.pod +++ /dev/null @@ -1,77 +0,0 @@ -=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/CommandGuide/llvm-as.rst b/docs/CommandGuide/llvm-as.rst new file mode 100644 index 000000000000..1b499bbe9708 --- /dev/null +++ b/docs/CommandGuide/llvm-as.rst @@ -0,0 +1,56 @@ +llvm-as - LLVM assembler +======================== + +SYNOPSIS +-------- + +**llvm-as** [*options*] [*filename*] + +DESCRIPTION +----------- + +**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 *filename* is omitted or is ``-``, then **llvm-as** reads its input from +standard input. + +If an output file is not specified with the **-o** option, then +**llvm-as** sends its output to a file or standard output by following +these rules: + +* If the input is standard input, then the output is standard output. + +* If the input is a file that ends with ``.ll``, then the output file is of the + same name, except that the suffix is changed to ``.bc``. + +* If the input is a file that does not end with the ``.ll`` suffix, then the + output file has the same name as the input file, except that the ``.bc`` + suffix is appended. + +OPTIONS +------- + +**-f** + Enable binary output on terminals. Normally, **llvm-as** will refuse to + write raw bitcode output if the output stream is a terminal. With this option, + **llvm-as** will write raw bitcode regardless of the output device. + +**-help** + Print a summary of command line options. + +**-o** *filename* + Specify the output file name. If *filename* is ``-``, then **llvm-as** + sends its output to standard output. + +EXIT STATUS +----------- + +If **llvm-as** succeeds, it will exit with 0. Otherwise, if an error occurs, it +will exit with a non-zero value. + +SEE ALSO +-------- + +llvm-dis|llvm-dis, gccas|gccas diff --git a/docs/CommandGuide/llvm-bcanalyzer.pod b/docs/CommandGuide/llvm-bcanalyzer.pod deleted file mode 100644 index 9c5021b639f1..000000000000 --- a/docs/CommandGuide/llvm-bcanalyzer.pod +++ /dev/null @@ -1,315 +0,0 @@ -=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 function. 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/CommandGuide/llvm-bcanalyzer.rst b/docs/CommandGuide/llvm-bcanalyzer.rst new file mode 100644 index 000000000000..f1e4eac1be50 --- /dev/null +++ b/docs/CommandGuide/llvm-bcanalyzer.rst @@ -0,0 +1,424 @@ +llvm-bcanalyzer - LLVM bitcode analyzer +======================================= + + +SYNOPSIS +-------- + + +**llvm-bcanalyzer** [*options*] [*filename*] + + +DESCRIPTION +----------- + + +The **llvm-bcanalyzer** command is a small utility for analyzing bitcode files. +The tool reads a bitcode file (such as generated with the **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 *filename* is omitted or is ``-``, then **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. + + +OPTIONS +------- + + + +**-nodetails** + + Causes **llvm-bcanalyzer** to abbreviate its output by writing out only a module + level summary. The details for individual functions are not displayed. + + + +**-dump** + + Causes **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. + + + +**-verify** + + Causes **llvm-bcanalyzer** to verify the module produced by reading the + bitcode. This ensures that the statistics generated are based on a consistent + module. + + + +**-help** + + Print a summary of command line options. + + + + +EXIT STATUS +----------- + + +If **llvm-bcanalyzer** succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value, usually 1. + + +SUMMARY OUTPUT DEFINITIONS +-------------------------- + + +The following items are always printed by llvm-bcanalyzer. They comprize the +summary output. + + +**Bitcode Analysis Of Module** + + This just provides the name of the module for which bitcode analysis is being + generated. + + + +**Bitcode Version Number** + + The bitcode version (not LLVM version) of the file read by the analyzer. + + + +**File Size** + + The size, in bytes, of the entire bitcode file. + + + +**Module Bytes** + + The size, in bytes, of the module block. Percentage is relative to File Size. + + + +**Function Bytes** + + The size, in bytes, of all the function blocks. Percentage is relative to File + Size. + + + +**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. + + + +**Constant Pool Bytes** + + The size, in bytes, of the Constant Pool Blocks Percentage is relative to File + Size. + + + +**Module Globals Bytes** + + Ths size, in bytes, of the Global Variable Definitions and their initializers. + Percentage is relative to File Size. + + + +**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. + + + +**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. + + + +**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. + + + +**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. + + + +**Number Of Bitcode Blocks** + + The total number of blocks of any kind in the bitcode file. + + + +**Number Of Functions** + + The total number of function definitions in the bitcode file. + + + +**Number Of Types** + + The total number of types defined in the Global Types Pool. + + + +**Number Of Constants** + + The total number of constants (of any type) defined in the Constant Pool. + + + +**Number Of Basic Blocks** + + The total number of basic blocks defined in all functions in the bitcode file. + + + +**Number Of Instructions** + + The total number of instructions defined in all functions in the bitcode file. + + + +**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. + + + +**Number Of Operands** + + The total number of operands used in all instructions in the bitcode file. + + + +**Number Of Compaction Tables** + + The total number of compaction tables in all functions in the bitcode file. + + + +**Number Of Symbol Tables** + + The total number of symbol tables in all functions in the bitcode file. + + + +**Number Of Dependent Libs** + + The total number of dependent libraries found in the bitcode file. + + + +**Total Instruction Size** + + The total size of the instructions in all functions in the bitcode file. + + + +**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. + + + +**Maximum Type Slot Number** + + The maximum value used for a type's slot number. Larger slot number values take + more bytes to encode. + + + +**Maximum Value Slot Number** + + The maximum value used for a value's slot number. Larger slot number values take + more bytes to encode. + + + +**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. + + + +**Bytes Per Global** + + The average size of a global definition (constants and global variables). + + + +**Bytes Per Function** + + The average number of bytes per function definition. This is computed by + dividing Function Bytes by Number Of Functions. + + + +**# of VBR 32-bit Integers** + + The total number of 32-bit integers encoded using the Variable Bit Rate + encoding scheme. + + + +**# of VBR 64-bit Integers** + + The total number of 64-bit integers encoded using the Variable Bit Rate encoding + scheme. + + + +**# 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. + + + +**# 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. + + + +**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. + + + + +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. + + +**Type** + + The type signature of the function. + + + +**Byte Size** + + The total number of bytes in the function's block. + + + +**Basic Blocks** + + The number of basic blocks defined by the function. + + + +**Instructions** + + The number of instructions defined by the function. + + + +**Long Instructions** + + The number of instructions using the long instruction format in the function. + + + +**Operands** + + The number of operands used by all instructions in the function. + + + +**Instruction Size** + + The number of bytes consumed by instructions in the function. + + + +**Average Instruction Size** + + The average number of bytes consumed by the instructions in the function. This + value is computed by dividing Instruction Size by Instructions. + + + +**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. + + + +**Number of VBR 32-bit Integers** + + The total number of 32-bit integers found in this function (for any use). + + + +**Number of VBR 64-bit Integers** + + The total number of 64-bit integers found in this function (for any use). + + + +**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. + + + +**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. + + + +**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. + + + + +SEE ALSO +-------- + + +llvm-dis|llvm-dis, `http://llvm.org/docs/BitCodeFormat.html <http://llvm.org/docs/BitCodeFormat.html>`_ diff --git a/docs/CommandGuide/llvm-build.pod b/docs/CommandGuide/llvm-build.pod deleted file mode 100644 index 14e08cb6299b..000000000000 --- a/docs/CommandGuide/llvm-build.pod +++ /dev/null @@ -1,86 +0,0 @@ -=pod - -=head1 NAME - -llvm-build - LLVM Project Build Utility - -=head1 SYNOPSIS - -B<llvm-build> [I<options>] - -=head1 DESCRIPTION - -B<llvm-build> is a tool for working with LLVM projects that use the LLVMBuild -system for describing their components. - -At heart, B<llvm-build> is responsible for loading, verifying, and manipulating -the project's component data. The tool is primarily designed for use in -implementing build systems and tools which need access to the project structure -information. - -=head1 OPTIONS - -=over - -=item B<-h>, B<--help> - -Print the builtin program help. - -=item B<--source-root>=I<PATH> - -If given, load the project at the given source root path. If this option is not -given, the location of the project sources will be inferred from the location of -the B<llvm-build> script itself. - -=item B<--print-tree> - -Print the component tree for the project. - -=item B<--write-library-table> - -Write out the C++ fragment which defines the components, library names, and -required libraries. This C++ fragment is built into L<llvm-config|llvm-config> -in order to provide clients with the list of required libraries for arbitrary -component combinations. - -=item B<--write-llvmbuild> - -Write out new I<LLVMBuild.txt> files based on the loaded components. This is -useful for auto-upgrading the schema of the files. B<llvm-build> will try to a -limited extent to preserve the comments which were written in the original -source file, although at this time it only preserves block comments that preceed -the section names in the I<LLVMBuild> files. - -=item B<--write-cmake-fragment> - -Write out the LLVMBuild in the form of a CMake fragment, so it can easily be -consumed by the CMake based build system. The exact contents and format of this -file are closely tied to how LLVMBuild is integrated with CMake, see LLVM's -top-level CMakeLists.txt. - -=item B<--write-make-fragment> - -Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be -consumed by a Make based build system. The exact contents and format of this -file are closely tied to how LLVMBuild is integrated with the Makefiles, see -LLVM's Makefile.rules. - -=item B<--llvmbuild-source-root>=I<PATH> - -If given, expect the I<LLVMBuild> files for the project to be rooted at the -given path, instead of inside the source tree itself. This option is primarily -designed for use in conjunction with B<--write-llvmbuild> to test changes to -I<LLVMBuild> schema. - -=back - -=head1 EXIT STATUS - -B<llvm-build> exits with 0 if operation was successful. Otherwise, it will exist -with a non-zero value. - -=head1 AUTHOR - -Maintained by the LLVM Team (L<http://llvm.org/>). - -=cut diff --git a/docs/CommandGuide/llvm-build.rst b/docs/CommandGuide/llvm-build.rst new file mode 100644 index 000000000000..f788f7c5a83e --- /dev/null +++ b/docs/CommandGuide/llvm-build.rst @@ -0,0 +1,102 @@ +llvm-build - LLVM Project Build Utility +======================================= + + +SYNOPSIS +-------- + + +**llvm-build** [*options*] + + +DESCRIPTION +----------- + + +**llvm-build** is a tool for working with LLVM projects that use the LLVMBuild +system for describing their components. + +At heart, **llvm-build** is responsible for loading, verifying, and manipulating +the project's component data. The tool is primarily designed for use in +implementing build systems and tools which need access to the project structure +information. + + +OPTIONS +------- + + + +**-h**, **--help** + + Print the builtin program help. + + + +**--source-root**\ =\ *PATH* + + If given, load the project at the given source root path. If this option is not + given, the location of the project sources will be inferred from the location of + the **llvm-build** script itself. + + + +**--print-tree** + + Print the component tree for the project. + + + +**--write-library-table** + + Write out the C++ fragment which defines the components, library names, and + required libraries. This C++ fragment is built into llvm-config|llvm-config + in order to provide clients with the list of required libraries for arbitrary + component combinations. + + + +**--write-llvmbuild** + + Write out new *LLVMBuild.txt* files based on the loaded components. This is + useful for auto-upgrading the schema of the files. **llvm-build** will try to a + limited extent to preserve the comments which were written in the original + source file, although at this time it only preserves block comments that precede + the section names in the *LLVMBuild* files. + + + +**--write-cmake-fragment** + + Write out the LLVMBuild in the form of a CMake fragment, so it can easily be + consumed by the CMake based build system. The exact contents and format of this + file are closely tied to how LLVMBuild is integrated with CMake, see LLVM's + top-level CMakeLists.txt. + + + +**--write-make-fragment** + + Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be + consumed by a Make based build system. The exact contents and format of this + file are closely tied to how LLVMBuild is integrated with the Makefiles, see + LLVM's Makefile.rules. + + + +**--llvmbuild-source-root**\ =\ *PATH* + + If given, expect the *LLVMBuild* files for the project to be rooted at the + given path, instead of inside the source tree itself. This option is primarily + designed for use in conjunction with **--write-llvmbuild** to test changes to + *LLVMBuild* schema. + + + + +EXIT STATUS +----------- + + +**llvm-build** exits with 0 if operation was successful. Otherwise, it will exist +with a non-zero value. diff --git a/docs/CommandGuide/llvm-config.pod b/docs/CommandGuide/llvm-config.pod deleted file mode 100644 index 7d68564a6d75..000000000000 --- a/docs/CommandGuide/llvm-config.pod +++ /dev/null @@ -1,131 +0,0 @@ -=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/CommandGuide/llvm-config.rst b/docs/CommandGuide/llvm-config.rst new file mode 100644 index 000000000000..0ebb344c06ad --- /dev/null +++ b/docs/CommandGuide/llvm-config.rst @@ -0,0 +1,176 @@ +llvm-config - Print LLVM compilation options +============================================ + + +SYNOPSIS +-------- + + +**llvm-config** *option* [*components*...] + + +DESCRIPTION +----------- + + +**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. + + +EXAMPLES +-------- + + +To link against the JIT: + + +.. code-block:: sh + + g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp + g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \ + `llvm-config --libs engine bcreader scalaropts` + + + +OPTIONS +------- + + + +**--version** + + Print the version number of LLVM. + + + +**-help** + + Print a summary of **llvm-config** arguments. + + + +**--prefix** + + Print the installation prefix for LLVM. + + + +**--src-root** + + Print the source root from which LLVM was built. + + + +**--obj-root** + + Print the object root used to build LLVM. + + + +**--bindir** + + Print the installation directory for LLVM binaries. + + + +**--includedir** + + Print the installation directory for LLVM headers. + + + +**--libdir** + + Print the installation directory for LLVM libraries. + + + +**--cxxflags** + + Print the C++ compiler flags needed to use LLVM headers. + + + +**--ldflags** + + Print the flags needed to link against LLVM libraries. + + + +**--libs** + + Print all the libraries needed to link against the specified LLVM + *components*, including any dependencies. + + + +**--libnames** + + Similar to **--libs**, but prints the bare filenames of the libraries + without **-l** or pathnames. Useful for linking against a not-yet-installed + copy of LLVM. + + + +**--libfiles** + + Similar to **--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. + + + +**--components** + + Print all valid component names. + + + +**--targets-built** + + Print the component names for all targets supported by this copy of LLVM. + + + +**--build-mode** + + Print the build mode used when LLVM was built (e.g. Debug or Release) + + + + +COMPONENTS +---------- + + +To print a list of all available components, run **llvm-config +--components**. In most cases, components correspond directly to LLVM +libraries. Useful "virtual" components include: + + +**all** + + Includes all LLVM libaries. The default if no components are specified. + + + +**backend** + + Includes either a native backend or the C backend. + + + +**engine** + + Includes either a native JIT or the bitcode interpreter. + + + + +EXIT STATUS +----------- + + +If **llvm-config** succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. diff --git a/docs/CommandGuide/llvm-cov.pod b/docs/CommandGuide/llvm-cov.pod deleted file mode 100644 index e8ff68311750..000000000000 --- a/docs/CommandGuide/llvm-cov.pod +++ /dev/null @@ -1,45 +0,0 @@ -=pod - -=head1 NAME - -llvm-cov - emit coverage information - -=head1 SYNOPSIS - -B<llvm-cov> [-gcno=filename] [-gcda=filename] [dump] - -=head1 DESCRIPTION - -The experimental B<llvm-cov> tool reads in description file generated by compiler -and coverage data file generated by instrumented program. This program assumes -that the description and data file uses same format as gcov files. - -=head1 OPTIONS - -=over - -=item B<-gcno=filename] - -This option selects input description file generated by compiler while instrumenting -program. - -=item B<-gcda=filename] - -This option selects coverage data file generated by instrumented compiler. - -=item B<-dump> - -This options enables output dump that is suitable for a developer to help debug -B<llvm-cov> itself. - -=back - -=head1 EXIT STATUS - -B<llvm-cov> returns 1 if it cannot read input files. Otherwise, it exits with zero. - -=head1 AUTHOR - -B<llvm-cov> is maintained by the LLVM Team (L<http://llvm.org/>). - -=cut diff --git a/docs/CommandGuide/llvm-cov.rst b/docs/CommandGuide/llvm-cov.rst new file mode 100644 index 000000000000..09275f6af714 --- /dev/null +++ b/docs/CommandGuide/llvm-cov.rst @@ -0,0 +1,51 @@ +llvm-cov - emit coverage information +==================================== + + +SYNOPSIS +-------- + + +**llvm-cov** [-gcno=filename] [-gcda=filename] [dump] + + +DESCRIPTION +----------- + + +The experimental **llvm-cov** tool reads in description file generated by compiler +and coverage data file generated by instrumented program. This program assumes +that the description and data file uses same format as gcov files. + + +OPTIONS +------- + + + +**-gcno=filename]** + + This option selects input description file generated by compiler while instrumenting + program. + + + +**-gcda=filename]** + + This option selects coverage data file generated by instrumented compiler. + + + +**-dump** + + This options enables output dump that is suitable for a developer to help debug + **llvm-cov** itself. + + + + +EXIT STATUS +----------- + + +**llvm-cov** returns 1 if it cannot read input files. Otherwise, it exits with zero. diff --git a/docs/CommandGuide/llvm-diff.pod b/docs/CommandGuide/llvm-diff.rst index ffe0b4896fdd..991d4fece04e 100644 --- a/docs/CommandGuide/llvm-diff.pod +++ b/docs/CommandGuide/llvm-diff.rst @@ -1,16 +1,19 @@ -=pod +llvm-diff - LLVM structural 'diff' +================================== -=head1 NAME -llvm-diff - LLVM structural 'diff' +SYNOPSIS +-------- + -=head1 SYNOPSIS +**llvm-diff** [*options*] *module 1* *module 2* [*global name ...*] -B<llvm-diff> [I<options>] I<module 1> I<module 2> [I<global name ...>] -=head1 DESCRIPTION +DESCRIPTION +----------- -B<llvm-diff> compares the structure of two LLVM modules, primarily + +**llvm-diff** compares the structure of two LLVM modules, primarily focusing on differences in function definitions. Insignificant differences, such as changes in the ordering of globals or in the names of local values, are ignored. @@ -23,31 +26,31 @@ are compared; otherwise, all global values are compared, and diagnostics are produced for globals which only appear in one module or the other. -B<llvm-diff> compares two functions by comparing their basic blocks, +**llvm-diff** compares two functions by comparing their basic blocks, beginning with the entry blocks. If the terminators seem to match, then the corresponding successors are compared; otherwise they are ignored. This algorithm is very sensitive to changes in control flow, which tend to stop any downstream changes from being detected. -B<llvm-diff> is intended as a debugging tool for writers of LLVM +**llvm-diff** is intended as a debugging tool for writers of LLVM passes and frontends. It does not have a stable output format. -=head1 EXIT STATUS -If B<llvm-diff> finds no differences between the modules, it will exit +EXIT STATUS +----------- + + +If **llvm-diff** finds no differences between the modules, it will exit with 0 and produce no output. Otherwise it will exit with a non-zero value. -=head1 BUGS + +BUGS +---- + Many important differences, like changes in linkage or function attributes, are not diagnosed. Changes in memory behavior (for example, coalescing loads) can cause massive detected differences in blocks. - -=head1 AUTHORS - -Maintained by the LLVM Team (L<http://llvm.org/>). - -=cut diff --git a/docs/CommandGuide/llvm-dis.pod b/docs/CommandGuide/llvm-dis.pod deleted file mode 100644 index 9f4026c27fe7..000000000000 --- a/docs/CommandGuide/llvm-dis.pod +++ /dev/null @@ -1,60 +0,0 @@ -=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/CommandGuide/llvm-dis.rst b/docs/CommandGuide/llvm-dis.rst new file mode 100644 index 000000000000..85cdca85ecdf --- /dev/null +++ b/docs/CommandGuide/llvm-dis.rst @@ -0,0 +1,69 @@ +llvm-dis - LLVM disassembler +============================ + + +SYNOPSIS +-------- + + +**llvm-dis** [*options*] [*filename*] + + +DESCRIPTION +----------- + + +The **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 ``-``, **llvm-dis** reads its +input from standard input. + +If the input is being read from standard input, then **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 ``.ll`` suffix added (any existing ``.bc`` suffix will first be +removed). You can override the choice of output file using the +**-o** option. + + +OPTIONS +------- + + + +**-f** + + Enable binary output on terminals. Normally, **llvm-dis** will refuse to + write raw bitcode output if the output stream is a terminal. With this option, + **llvm-dis** will write raw bitcode regardless of the output device. + + + +**-help** + + Print a summary of command line options. + + + +**-o** *filename* + + Specify the output file name. If *filename* is -, then the output is sent + to standard output. + + + + +EXIT STATUS +----------- + + +If **llvm-dis** succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + + +SEE ALSO +-------- + + +llvm-as|llvm-as diff --git a/docs/CommandGuide/llvm-extract.pod b/docs/CommandGuide/llvm-extract.pod deleted file mode 100644 index 67f00f0b8615..000000000000 --- a/docs/CommandGuide/llvm-extract.pod +++ /dev/null @@ -1,85 +0,0 @@ -=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<--rfunc> I<function-regular-expr> - -Extract the function(s) matching I<function-regular-expr> from the LLVM bitcode. -All functions matching the regular expression will be extracted. May be -specified multiple times. - -=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<--rglob> I<glob-regular-expr> - -Extract the global variable(s) matching I<global-regular-expr> from the LLVM -bitcode. All global variables matching the regular expression will be extracted. -May be specified multiple times. - -=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/CommandGuide/llvm-extract.rst b/docs/CommandGuide/llvm-extract.rst new file mode 100644 index 000000000000..d569e35729eb --- /dev/null +++ b/docs/CommandGuide/llvm-extract.rst @@ -0,0 +1,104 @@ +llvm-extract - extract a function from an LLVM module +===================================================== + + +SYNOPSIS +-------- + + +**llvm-extract** [*options*] **--func** *function-name* [*filename*] + + +DESCRIPTION +----------- + + +The **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, +**llvm-extract** will also remove unreachable global variables, prototypes, and +unused types. + +The **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 **-o** option is specified (see below). + + +OPTIONS +------- + + + +**-f** + + Enable binary output on terminals. Normally, **llvm-extract** will refuse to + write raw bitcode output if the output stream is a terminal. With this option, + **llvm-extract** will write raw bitcode regardless of the output device. + + + +**--func** *function-name* + + Extract the function named *function-name* from the LLVM bitcode. May be + specified multiple times to extract multiple functions at once. + + + +**--rfunc** *function-regular-expr* + + Extract the function(s) matching *function-regular-expr* from the LLVM bitcode. + All functions matching the regular expression will be extracted. May be + specified multiple times. + + + +**--glob** *global-name* + + Extract the global variable named *global-name* from the LLVM bitcode. May be + specified multiple times to extract multiple global variables at once. + + + +**--rglob** *glob-regular-expr* + + Extract the global variable(s) matching *global-regular-expr* from the LLVM + bitcode. All global variables matching the regular expression will be extracted. + May be specified multiple times. + + + +**-help** + + Print a summary of command line options. + + + +**-o** *filename* + + Specify the output filename. If filename is "-" (the default), then + **llvm-extract** sends its output to standard output. + + + +**-S** + + Write output in LLVM intermediate language (instead of bitcode). + + + + +EXIT STATUS +----------- + + +If **llvm-extract** succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + + +SEE ALSO +-------- + + +bugpoint|bugpoint diff --git a/docs/CommandGuide/llvm-ld.pod b/docs/CommandGuide/llvm-ld.pod deleted file mode 100644 index efa9ebd06c53..000000000000 --- a/docs/CommandGuide/llvm-ld.pod +++ /dev/null @@ -1,234 +0,0 @@ -=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/CommandGuide/llvm-link.pod b/docs/CommandGuide/llvm-link.pod deleted file mode 100644 index 1e466a56f4ec..000000000000 --- a/docs/CommandGuide/llvm-link.pod +++ /dev/null @@ -1,79 +0,0 @@ -=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/CommandGuide/llvm-link.rst b/docs/CommandGuide/llvm-link.rst new file mode 100644 index 000000000000..63019d7cca78 --- /dev/null +++ b/docs/CommandGuide/llvm-link.rst @@ -0,0 +1,96 @@ +llvm-link - LLVM linker +======================= + + +SYNOPSIS +-------- + + +**llvm-link** [*options*] *filename ...* + + +DESCRIPTION +----------- + + +**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 **-o** option is used to specify a filename. + +**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 +**-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. + + +OPTIONS +------- + + + +**-L** *directory* + + Add the specified *directory* to the library search path. When looking for + libraries, **llvm-link** will look in path name for libraries. This option can be + specified multiple times; **llvm-link** will search inside these directories in + the order in which they were specified on the command line. + + + +**-f** + + Enable binary output on terminals. Normally, **llvm-link** will refuse to + write raw bitcode output if the output stream is a terminal. With this option, + **llvm-link** will write raw bitcode regardless of the output device. + + + +**-o** *filename* + + Specify the output file name. If *filename* is ``-``, then **llvm-link** will + write its output to standard output. + + + +**-S** + + Write output in LLVM intermediate language (instead of bitcode). + + + +**-d** + + If specified, **llvm-link** prints a human-readable version of the output + bitcode file to standard error. + + + +**-help** + + Print a summary of command line options. + + + +**-v** + + Verbose mode. Print information about what **llvm-link** is doing. This + typically includes a message for each bitcode file linked in and for each + library found. + + + + +EXIT STATUS +----------- + + +If **llvm-link** succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + + +SEE ALSO +-------- + + +gccld|gccld diff --git a/docs/CommandGuide/llvm-nm.pod b/docs/CommandGuide/llvm-nm.pod deleted file mode 100644 index a6dc4901dd61..000000000000 --- a/docs/CommandGuide/llvm-nm.pod +++ /dev/null @@ -1,122 +0,0 @@ -=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/CommandGuide/llvm-nm.rst b/docs/CommandGuide/llvm-nm.rst new file mode 100644 index 000000000000..cbc7af207592 --- /dev/null +++ b/docs/CommandGuide/llvm-nm.rst @@ -0,0 +1,189 @@ +llvm-nm - list LLVM bitcode and object file's symbol table +========================================================== + + +SYNOPSIS +-------- + + +:program:`llvm-nm` [*options*] [*filenames...*] + + +DESCRIPTION +----------- + + +The :program:`llvm-nm` utility lists the names of symbols from the LLVM bitcode +files, object files, or :program:`ar` archives containing them, named on the +command line. Each symbol is listed along with some simple information about its +provenance. If no file name is specified, or *-* is used as a file name, +:program:`llvm-nm` will process a file on its standard input stream. + +:program:`llvm-nm`'s default output format is the traditional BSD :program:`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: + + +U + + Named object is referenced but undefined in this bitcode file + + + +C + + Common (multiple definitions link together into one def) + + + +W + + Weak reference (multiple definitions link together into zero or one definitions) + + + +t + + Local function (text) object + + + +T + + Global function (text) object + + + +d + + Local data object + + + +D + + Global data object + + + +? + + Something unrecognizable + + + +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", :program:`llvm-nm` does not print an address for any +symbol in a LLVM bitcode file, even symbols which are defined in the bitcode +file. + + +OPTIONS +------- + + +.. program:: llvm-nm + + +.. option:: -B (default) + + Use BSD output format. Alias for :option:`--format=bsd`. + + +.. option:: -P + + Use POSIX.2 output format. Alias for :option:`--format=posix`. + + +.. option:: --debug-syms, -a + + Show all symbols, even debugger only. + + +.. option:: --defined-only + + Print only symbols defined in this file (as opposed to + symbols which may be referenced by objects in this file, but not + defined in this file.) + + +.. option:: --dynamic, -D + + Display dynamic symbols instead of normal symbols. + + +.. option:: --extern-only, -g + + Print only symbols whose definitions are external; that is, accessible + from other files. + + +.. option:: --format=format, -f format + + Select an output format; *format* may be *sysv*, *posix*, or *bsd*. The default + is *bsd*. + + +.. option:: -help + + Print a summary of command-line options and their meanings. + + +.. option:: --no-sort, -p + + Shows symbols in order encountered. + + +.. option:: --numeric-sort, -n, -v + + Sort symbols by address. + + +.. option:: --print-file-name, -A, -o + + Precede each symbol with the file it came from. + + +.. option:: --print-size, -S + + Show symbol size instead of address. + + +.. option:: --size-sort + + Sort symbols by size. + + +.. option:: --undefined-only, -u + + Print only symbols referenced but not defined in this file. + + +BUGS +---- + + + * :program:`llvm-nm` cannot demangle C++ mangled names, like GNU :program:`nm` + can. + + * :program:`llvm-nm` does not support the full set of arguments that GNU + :program:`nm` does. + + +EXIT STATUS +----------- + + +:program:`llvm-nm` exits with an exit code of zero. + + +SEE ALSO +-------- + + +llvm-dis|llvm-dis, ar(1), nm(1) diff --git a/docs/CommandGuide/llvm-prof.pod b/docs/CommandGuide/llvm-prof.pod deleted file mode 100644 index 4b2e09d70470..000000000000 --- a/docs/CommandGuide/llvm-prof.pod +++ /dev/null @@ -1,57 +0,0 @@ -=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/CommandGuide/llvm-prof.rst b/docs/CommandGuide/llvm-prof.rst new file mode 100644 index 000000000000..e8d0b19ca94f --- /dev/null +++ b/docs/CommandGuide/llvm-prof.rst @@ -0,0 +1,63 @@ +llvm-prof - print execution profile of LLVM program +=================================================== + + +SYNOPSIS +-------- + + +**llvm-prof** [*options*] [*bitcode file*] [*llvmprof.out*] + + +DESCRIPTION +----------- + + +The **llvm-prof** tool reads in an *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 *utils/profile.pl* +script. This script automatically instruments a program, runs it with the JIT, +then runs **llvm-prof** to format a report. To get more information about +*utils/profile.pl*, execute it with the **-help** option. + + +OPTIONS +------- + + + +**--annotated-llvm** or **-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. + + + +**--print-all-code** + + Using this option enables the **--annotated-llvm** option, but it + prints the entire module, instead of just the most commonly executed + functions. + + + +**--time-passes** + + Record the amount of time needed for each pass and print it to standard + error. + + + + +EXIT STATUS +----------- + + +**llvm-prof** returns 1 if it cannot load the bitcode file or the profile +information. Otherwise, it exits with zero. diff --git a/docs/CommandGuide/llvm-ranlib.pod b/docs/CommandGuide/llvm-ranlib.pod deleted file mode 100644 index 431bc551048a..000000000000 --- a/docs/CommandGuide/llvm-ranlib.pod +++ /dev/null @@ -1,52 +0,0 @@ -=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/CommandGuide/llvm-ranlib.rst b/docs/CommandGuide/llvm-ranlib.rst new file mode 100644 index 000000000000..6658818f41e5 --- /dev/null +++ b/docs/CommandGuide/llvm-ranlib.rst @@ -0,0 +1,61 @@ +llvm-ranlib - Generate index for LLVM archive +============================================= + + +SYNOPSIS +-------- + + +**llvm-ranlib** [--version] [-help] <archive-file> + + +DESCRIPTION +----------- + + +The **llvm-ranlib** command is similar to the common Unix utility, ``ranlib``. It +adds or updates the symbol table in an LLVM archive file. Note that using the +**llvm-ar** modifier *s* is usually more efficient than running **llvm-ranlib** +which is only provided only for completness and compatibility. Unlike other +implementations of ``ranlib``, **llvm-ranlib** indexes LLVM bitcode files, not +native object modules. You can list the contents of the symbol table with the +``llvm-nm -s`` command. + + +OPTIONS +------- + + + +*archive-file* + + Specifies the archive-file to which the symbol table is added or updated. + + + +*--version* + + Print the version of **llvm-ranlib** and exit without building a symbol table. + + + +*-help* + + Print usage help for **llvm-ranlib** and exit without building a symbol table. + + + + +EXIT STATUS +----------- + + +If **llvm-ranlib** succeeds, it will exit with 0. If an error occurs, a non-zero +exit code will be returned. + + +SEE ALSO +-------- + + +llvm-ar|llvm-ar, ranlib(1) diff --git a/docs/CommandGuide/llvm-stress.pod b/docs/CommandGuide/llvm-stress.pod deleted file mode 100644 index 92083d2d2bc7..000000000000 --- a/docs/CommandGuide/llvm-stress.pod +++ /dev/null @@ -1,42 +0,0 @@ -=pod - -=head1 NAME - -llvm-stress - generate random .ll files - -=head1 SYNOPSIS - -B<llvm-cov> [-gcno=filename] [-gcda=filename] [dump] - -=head1 DESCRIPTION - -The B<llvm-stress> tool is used to generate random .ll files that can be used to -test different components of LLVM. - -=head1 OPTIONS - -=over - -=item B<-o> I<filename> - -Specify the output filename. - -=item B<-size> I<size> - -Specify the size of the generated .ll file. - -=item B<-seed> I<seed> - -Specify the seed to be used for the randomly generated instructions. - -=back - -=head1 EXIT STATUS - -B<llvm-stress> returns 0. - -=head1 AUTHOR - -B<llvm-stress> is maintained by the LLVM Team (L<http://llvm.org/>). - -=cut diff --git a/docs/CommandGuide/llvm-stress.rst b/docs/CommandGuide/llvm-stress.rst new file mode 100644 index 000000000000..44aa32c7557f --- /dev/null +++ b/docs/CommandGuide/llvm-stress.rst @@ -0,0 +1,48 @@ +llvm-stress - generate random .ll files +======================================= + + +SYNOPSIS +-------- + + +**llvm-stress** [-size=filesize] [-seed=initialseed] [-o=outfile] + + +DESCRIPTION +----------- + + +The **llvm-stress** tool is used to generate random .ll files that can be used to +test different components of LLVM. + + +OPTIONS +------- + + + +**-o** *filename* + + Specify the output filename. + + + +**-size** *size* + + Specify the size of the generated .ll file. + + + +**-seed** *seed* + + Specify the seed to be used for the randomly generated instructions. + + + + +EXIT STATUS +----------- + + +**llvm-stress** returns 0. diff --git a/docs/CommandGuide/manpage.css b/docs/CommandGuide/manpage.css deleted file mode 100644 index c922564dc3c3..000000000000 --- a/docs/CommandGuide/manpage.css +++ /dev/null @@ -1,256 +0,0 @@ -/* 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/CommandGuide/opt.pod b/docs/CommandGuide/opt.pod deleted file mode 100644 index f5f496817eb8..000000000000 --- a/docs/CommandGuide/opt.pod +++ /dev/null @@ -1,143 +0,0 @@ -=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/CommandGuide/opt.rst b/docs/CommandGuide/opt.rst new file mode 100644 index 000000000000..72f19034c9ed --- /dev/null +++ b/docs/CommandGuide/opt.rst @@ -0,0 +1,183 @@ +opt - LLVM optimizer +==================== + + +SYNOPSIS +-------- + + +**opt** [*options*] [*filename*] + + +DESCRIPTION +----------- + + +The **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 +**opt** depends on whether the **-analyze** option is given. + +When **-analyze** is specified, **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 **-analyze** is *not* given, **opt** attempts to produce an optimized +output file. The optimizations available via **opt** depend upon what +libraries were linked into it as well as any additional libraries that have +been loaded with the **-load** option. Use the **-help** option to determine +what optimizations you can use. + +If *filename* is omitted from the command line or is *-*, **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 **-o** option, **opt** +writes its output to the standard output. + + +OPTIONS +------- + + + +**-f** + + Enable binary output on terminals. Normally, **opt** will refuse to + write raw bitcode output if the output stream is a terminal. With this option, + **opt** will write raw bitcode regardless of the output device. + + + +**-help** + + Print a summary of command line options. + + + +**-o** *filename* + + Specify the output filename. + + + +**-S** + + Write output in LLVM intermediate language (instead of bitcode). + + + +**-{passname}** + + **opt** provides the ability to run any of LLVM's optimization or analysis passes + in any order. The **-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). + + + +**-std-compile-opts** + + This is short hand for a standard list of *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: + + + .. code-block:: sh + + llvm-as < /dev/null | opt -std-compile-opts -disable-output -debug-pass=Arguments + + + + +**-disable-inlining** + + This option is only meaningful when **-std-compile-opts** is given. It simply + removes the inlining pass from the standard list. + + + +**-disable-opt** + + This option is only meaningful when **-std-compile-opts** is given. It disables + most, but not all, of the **-std-compile-opts**. The ones that remain are + **-verify**, **-lower-setjmp**, and **-funcresolve**. + + + +**-strip-debug** + + This option causes opt to strip debug information from the module before + applying other optimizations. It is essentially the same as **-strip** but it + ensures that stripping of debug information is done first. + + + +**-verify-each** + + This option causes opt to add a verify pass after every pass otherwise specified + on the command line (including **-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 **-std-compile-opts** and **-verify-each** + can quickly track down this kind of problem. + + + +**-profile-info-file** *filename* + + Specify the name of the file loaded by the -profile-loader option. + + + +**-stats** + + Print statistics. + + + +**-time-passes** + + Record the amount of time needed for each pass and print it to standard + error. + + + +**-debug** + + If this is a debug build, this option will enable debug printouts + from passes which use the *DEBUG()* macro. See the **LLVM Programmer's + Manual**, section *#DEBUG* for more information. + + + +**-load**\ =\ *plugin* + + Load the dynamic object *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 **-help** and **-load** options together. For example: + + + .. code-block:: sh + + opt -load=plugin.so -help + + + + +**-p** + + Print module after each transformation. + + + + +EXIT STATUS +----------- + + +If **opt** succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. diff --git a/docs/CommandGuide/tblgen.pod b/docs/CommandGuide/tblgen.pod deleted file mode 100644 index 180bcc1769e6..000000000000 --- a/docs/CommandGuide/tblgen.pod +++ /dev/null @@ -1,139 +0,0 @@ - -=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<-asmparsernum> F<N> - -Make -gen-asm-parser emit assembly writer number F<N>. - -=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<-print-sets> - -Print expanded sets for testing DAG exprs. - -=item B<-gen-emitter> - -Generate machine code emitter. - -=item B<-gen-register-info> - -Generate registers and register classes info. - -=item B<-gen-instr-info> - -Generate instruction descriptions. - -=item B<-gen-asm-writer> - -Generate the assembly writer. - -=item B<-gen-disassembler> - -Generate disassembler. - -=item B<-gen-pseudo-lowering> - -Generate pseudo instruction lowering. - -=item B<-gen-dag-isel> - -Generate a DAG (Directed Acycle Graph) instruction selector. - -=item B<-gen-asm-matcher> - -Generate assembly instruction matcher. - -=item B<-gen-dfa-packetizer> - -Generate DFA Packetizer for VLIW targets. - -=item B<-gen-fast-isel> - -Generate a "fast" instruction selector. - -=item B<-gen-subtarget> - -Generate subtarget enumerations. - -=item B<-gen-intrinsic> - -Generate intrinsic information. - -=item B<-gen-tgt-intrinsic> - -Generate target intrinsic information. - -=item B<-gen-enhanced-disassembly-info> - -Generate enhanced disassembly info. - -=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 diff --git a/docs/CommandGuide/tblgen.rst b/docs/CommandGuide/tblgen.rst new file mode 100644 index 000000000000..2d191676d9f0 --- /dev/null +++ b/docs/CommandGuide/tblgen.rst @@ -0,0 +1,186 @@ +tblgen - Target Description To C++ Code Generator +================================================= + + +SYNOPSIS +-------- + + +**tblgen** [*options*] [*filename*] + + +DESCRIPTION +----------- + + +**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 **tblgen** is beyond the scope of this short +introduction. Please see the *CodeGeneration* page in the LLVM documentation. + +The *filename* argument specifies the name of a Target Description (.td) file +to read as input. + + +OPTIONS +------- + + + +**-help** + + Print a summary of command line options. + + + +**-o** *filename* + + Specify the output file name. If *filename* is ``-``, then **tblgen** + sends its output to standard output. + + + +**-I** *directory* + + Specify where to find other target description files for inclusion. The + *directory* value should be a full or partial path to a directory that contains + target description files. + + + +**-asmparsernum** *N* + + Make -gen-asm-parser emit assembly writer number *N*. + + + +**-asmwriternum** *N* + + Make -gen-asm-writer emit assembly writer number *N*. + + + +**-class** *class Name* + + Print the enumeration list for this class. + + + +**-print-records** + + Print all records to standard output (default). + + + +**-print-enums** + + Print enumeration values for a class + + + +**-print-sets** + + Print expanded sets for testing DAG exprs. + + + +**-gen-emitter** + + Generate machine code emitter. + + + +**-gen-register-info** + + Generate registers and register classes info. + + + +**-gen-instr-info** + + Generate instruction descriptions. + + + +**-gen-asm-writer** + + Generate the assembly writer. + + + +**-gen-disassembler** + + Generate disassembler. + + + +**-gen-pseudo-lowering** + + Generate pseudo instruction lowering. + + + +**-gen-dag-isel** + + Generate a DAG (Directed Acycle Graph) instruction selector. + + + +**-gen-asm-matcher** + + Generate assembly instruction matcher. + + + +**-gen-dfa-packetizer** + + Generate DFA Packetizer for VLIW targets. + + + +**-gen-fast-isel** + + Generate a "fast" instruction selector. + + + +**-gen-subtarget** + + Generate subtarget enumerations. + + + +**-gen-intrinsic** + + Generate intrinsic information. + + + +**-gen-tgt-intrinsic** + + Generate target intrinsic information. + + + +**-gen-enhanced-disassembly-info** + + Generate enhanced disassembly info. + + + +**-version** + + Show the version number of this program. + + + + +EXIT STATUS +----------- + + +If **tblgen** succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. |