diff options
Diffstat (limited to 'docs/CommandGuide')
| -rw-r--r-- | docs/CommandGuide/FileCheck.pod | 65 | ||||
| -rw-r--r-- | docs/CommandGuide/Makefile | 10 | ||||
| -rw-r--r-- | docs/CommandGuide/index.html | 4 | ||||
| -rw-r--r-- | docs/CommandGuide/lit.pod | 222 | ||||
| -rw-r--r-- | docs/CommandGuide/llc.pod | 22 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-as.pod | 6 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-dis.pod | 6 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-extract.pod | 10 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-ld.pod | 6 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-link.pod | 9 | ||||
| -rw-r--r-- | docs/CommandGuide/llvmc.pod | 6 | ||||
| -rw-r--r-- | docs/CommandGuide/opt.pod | 29 |
12 files changed, 356 insertions, 39 deletions
diff --git a/docs/CommandGuide/FileCheck.pod b/docs/CommandGuide/FileCheck.pod new file mode 100644 index 0000000..539f66f --- /dev/null +++ b/docs/CommandGuide/FileCheck.pod @@ -0,0 +1,65 @@ + +=pod + +=head1 NAME + +FileCheck - Flexible pattern matching file verifier + +=head1 SYNOPSIS + +B<FileCheck> I<match-filename> [I<--check-prefix=XXX>] [I<--strict-whitespace>] + +=head1 DESCRIPTION + +B<FileCheck> reads two files (one from standard input, and one specified on the +command line) and uses one to verify the other. This behavior is particularly +useful for the testsuite, which wants to verify that the output of some tool +(e.g. llc) contains the expected information (for example, a movsd from esp or +whatever is interesting). This is similar to using grep, but it is optimized +for matching multiple different inputs in one file in a specific order. + +The I<match-filename> file specifies the file that contains the patterns to +match. The file to verify is always read from standard input. + +The input and output of B<FileCheck> is beyond the scope of this short +introduction. Please see the I<TestingGuide> page in the LLVM documentation. + +=head1 OPTIONS + +=over + +=item B<--help> + +Print a summary of command line options. + +=item B<--check-prefix> I<prefix> + +FileCheck searches the contents of I<match-filename> for patterns to match. By +default, these patterns are prefixed with "CHECK:". If you'd like to use a +different prefix (e.g. because the same input file is checking multiple +different tool or options), the B<--check-prefix> argument allows you to specify +a specific prefix to match. + +=item B<--strict-whitespace> + +By default, FileCheck canonicalizes input horizontal whitespace (spaces and +tabs) which causes it to ignore these differences (a space will match a tab). +The --strict-whitespace argument disables this behavior. + +=item B<-version> + +Show the version number of this program. + +=back + +=head1 EXIT STATUS + +If B<FileCheck> verifies that the file matches the expected contents, it exits +with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero +value. + +=head1 AUTHORS + +Maintained by The LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/CommandGuide/Makefile b/docs/CommandGuide/Makefile index cf77e6a..3b65183 100644 --- a/docs/CommandGuide/Makefile +++ b/docs/CommandGuide/Makefile @@ -48,6 +48,12 @@ 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 + +# The set of man pages that we will install +INSTALL_MANS = $(filter-out $(NO_INSTALL_MANS), $(MAN)) + .SUFFIXES: .SUFFIXES: .html .pod .1 .ps @@ -75,7 +81,7 @@ HTML_DIR := $(PROJ_docsdir)/html/CommandGuide MAN_DIR := $(PROJ_mandir)/man1 PS_DIR := $(PROJ_docsdir)/ps -install-local:: $(HTML) $(MAN) $(PS) +install-local:: $(HTML) $(INSTALL_MANS) $(PS) $(Echo) Installing HTML CommandGuide Documentation $(Verb) $(MKDIR) $(HTML_DIR) $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) @@ -83,7 +89,7 @@ install-local:: $(HTML) $(MAN) $(PS) $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR) $(Echo) Installing MAN CommandGuide Documentation $(Verb) $(MKDIR) $(MAN_DIR) - $(Verb) $(DataInstall) $(MAN) $(MAN_DIR) + $(Verb) $(DataInstall) $(INSTALL_MANS) $(MAN_DIR) $(Echo) Installing PS CommandGuide Documentation $(Verb) $(MKDIR) $(PS_DIR) $(Verb) $(DataInstall) $(PS) $(PS_DIR) diff --git a/docs/CommandGuide/index.html b/docs/CommandGuide/index.html index f05260b..f1046fa 100644 --- a/docs/CommandGuide/index.html +++ b/docs/CommandGuide/index.html @@ -128,6 +128,8 @@ options) arguments to the tool you are interested in.</p> <div class="doc_text"> <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> @@ -144,7 +146,7 @@ options) arguments to the tool you are interested in.</p> 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: 2008-12-11 18:12:52 +0100 (Thu, 11 Dec 2008) $ + Last modified: $Date: 2009-08-15 17:38:11 +0200 (Sat, 15 Aug 2009) $ </address> </body> diff --git a/docs/CommandGuide/lit.pod b/docs/CommandGuide/lit.pod new file mode 100644 index 0000000..a818302 --- /dev/null +++ b/docs/CommandGuide/lit.pod @@ -0,0 +1,222 @@ +=pod + +=head1 NAME + +lit - LLVM Integrated Tester + +=head1 SYNOPSIS + +B<lit> [I<options>] [I<tests>] + +=head1 DESCRIPTION + +B<lit> is a portable tool for executing LLVM and Clang style test suites, +summarizing their results, and providing indication of failures. B<lit> is +designed to be a lightweight testing tool with as simple a user interface as +possible. + +B<lit> should be run with one or more I<tests> to run specified on the command +line. Tests can be either individual test files or directories to search for +tests (see L<"TEST DISCOVERY">). + +Each specified test will be executed (potentially in parallel) and once all +tests have been run B<lit> will print summary information on the number of tests +which passed or failed (see L<"TEST STATUS RESULTS">). The B<lit> program will +execute with a non-zero exit code if any tests fail. + +By default B<lit> will use a succinct progress display and will only print +summary information for test failures. See L<"OUTPUT OPTIONS"> for options +controlling the B<lit> progress display and output. + +B<lit> also includes a number of options for controlling how tests are exected +(specific features may depend on the particular test format). See L<"EXECUTION +OPTIONS"> for more information. + +Finally, B<lit> also supports additional options for only running a subset of +the options specified on the command line, see L<"SELECTION OPTIONS"> for +more information. + +=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 chose to match the +number of detected available CPUs. + +=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). + +=back + +=head1 EXIT STATUS + +B<lit> will exit with an exit code of 1 if there are any FAIL or XPASS +results. Otherwise, it will exit with the status 0. Other exit codes used for +non-test related failures (for example a user error or an internal program +error). + +=head1 TEST DISCOVERY + +The inputs passed to B<lit> can be either individual tests, or entire +directories or hierarchies of tests to run. When B<lit> starts up, the first +thing it does is convert the inputs into a complete list of tests to run as part +of I<test discovery>. + +In the B<lit> model, every test must exist inside some I<test suite>. B<lit> +resolves the inputs specified on the command line to test suites by searching +upwards from the input path until it finds a I<lit.cfg> or I<lit.site.cfg> +file. These files serve as both a marker of test suites and as configuration +files which B<lit> loads in order to understand how to find and run the tests +inside the test suite. + +Once B<lit> has mapped the inputs into test suites it traverses the list of +inputs adding tests for individual files and recursively searching for tests in +directories. + +This behavior makes it easy to specify a subset of tests to run, while still +allowing the test suite configuration to control exactly how tests are +interpreted. In addition, B<lit> always identifies tests by the test suite they +are in, and their relative path inside the test suite. For appropriately +configured projects, this allows B<lit> to provide convenient and flexible +support for out-of-tree builds. + +=head1 TEST STATUS RESULTS + +Each test ultimately produces one of the following six results: + +=over + +=item B<PASS> + +The test succeeded. + +=item B<XFAIL> + +The test failed, but that is expected. This is used for test formats which allow +specifying that a test does not currently work, but wish to leave it in the test +suite. + +=item B<XPASS> + +The test succeeded, but it was expected to fail. This is used for tests which +were specified as expected to fail, but are now succeeding (generally because +the feautre they test was broken and has been fixed). + +=item B<FAIL> + +The test failed. + +=item B<UNRESOLVED> + +The test result could not be determined. For example, this occurs when the test +could not be run, the test itself is invalid, or the test was interrupted. + +=item B<UNSUPPORTED> + +The test is not supported in this environment. This is used by test formats +which can report unsupported tests. + +=back + +Depending on the test format tests may produce additional information about +their status (generally only for failures). See the L<Output|"LIT OUTPUT"> +section for more information. + +=head1 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/llc.pod b/docs/CommandGuide/llc.pod index eba7859..8adfb68 100644 --- a/docs/CommandGuide/llc.pod +++ b/docs/CommandGuide/llc.pod @@ -10,18 +10,19 @@ B<llc> [I<options>] [I<filename>] =head1 DESCRIPTION -The B<llc> command compiles LLVM bitcode into assembly language for a +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 bitcode file, unless the B<-march> option is used to -override the default. +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 LLVM bitcode from standard input. -Otherwise, it will read LLVM bitcode from I<filename>. +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 -, @@ -47,20 +48,15 @@ Generate code at different optimization levels. These correspond to the I<-O0>, I<-O1>, I<-O2>, I<-O3>, and I<-O4> optimization levels used by B<llvm-gcc> and B<clang>. -=item B<-f> - -Overwrite output files. By default, B<llc> will refuse to overwrite -an output file which already exists. - =item B<-mtriple>=I<target triple> -Override the target triple specified in the input bitcode file with the -specified string. +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 bitcode file. See the output of B<llc --help> for a list of +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. diff --git a/docs/CommandGuide/llvm-as.pod b/docs/CommandGuide/llvm-as.pod index 2befed1..045a924 100644 --- a/docs/CommandGuide/llvm-as.pod +++ b/docs/CommandGuide/llvm-as.pod @@ -46,9 +46,9 @@ suffix is appended. =item B<-f> -Force overwrite. Normally, B<llvm-as> will refuse to overwrite an -output file that already exists. With this option, B<llvm-as> -will overwrite the output file and replace it with new bitcode. +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> diff --git a/docs/CommandGuide/llvm-dis.pod b/docs/CommandGuide/llvm-dis.pod index 8df382d..2b83290 100644 --- a/docs/CommandGuide/llvm-dis.pod +++ b/docs/CommandGuide/llvm-dis.pod @@ -29,9 +29,9 @@ B<-o> option. =item B<-f> -Force overwrite. Normally, B<llvm-dis> will refuse to overwrite -an output file that already exists. With this option, B<llvm-dis> -will overwrite the output file. +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> diff --git a/docs/CommandGuide/llvm-extract.pod b/docs/CommandGuide/llvm-extract.pod index d916612..b62e8ae 100644 --- a/docs/CommandGuide/llvm-extract.pod +++ b/docs/CommandGuide/llvm-extract.pod @@ -28,9 +28,9 @@ unless the B<-o> option is specified (see below). =item B<-f> -Force overwrite. Normally, B<llvm-extract> will refuse to overwrite an -output file that already exists. With this option, B<llvm-extract> -will overwrite the output file and replace it with new bitcode. +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> @@ -45,6 +45,10 @@ Print a summary of command line options. 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 diff --git a/docs/CommandGuide/llvm-ld.pod b/docs/CommandGuide/llvm-ld.pod index 224939c..536ab0f 100644 --- a/docs/CommandGuide/llvm-ld.pod +++ b/docs/CommandGuide/llvm-ld.pod @@ -104,6 +104,12 @@ 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 diff --git a/docs/CommandGuide/llvm-link.pod b/docs/CommandGuide/llvm-link.pod index 5f4dcb6..e1a1267 100644 --- a/docs/CommandGuide/llvm-link.pod +++ b/docs/CommandGuide/llvm-link.pod @@ -33,14 +33,19 @@ the order in which they were specified on the command line. =item B<-f> -Overwrite output files. By default, B<llvm-link> will not overwrite an output -file if it already exists. +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 diff --git a/docs/CommandGuide/llvmc.pod b/docs/CommandGuide/llvmc.pod index 97445ed..e3031e1 100644 --- a/docs/CommandGuide/llvmc.pod +++ b/docs/CommandGuide/llvmc.pod @@ -71,6 +71,12 @@ write files into the directory specified with the I<-o> option. The I<--save-temps=cwd> and I<--save-temps> switches are both synonyms for the default behaviour. +=item B<--temp-dir> I<directory> + +Store temporary files in the given directory. This directory is deleted on exit +unless I<--save-temps> is specified. If I<--save-temps=obj> is also specified, +I<--temp-dir> is given the precedence. + =item B<--help> Print a summary of command-line options and exit. diff --git a/docs/CommandGuide/opt.pod b/docs/CommandGuide/opt.pod index 75b7edd..d1d1db5 100644 --- a/docs/CommandGuide/opt.pod +++ b/docs/CommandGuide/opt.pod @@ -11,24 +11,25 @@ B<opt> [I<options>] [I<filename>] =head1 DESCRIPTION The B<opt> command is the modular LLVM optimizer and analyzer. It takes LLVM -bitcode as input, runs the specified optimizations or analyses on it, and then -outputs the optimized LLVM bitcode or the analysis results. The function of +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 LLVM -bitcode. 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. +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 -bitcode file. The optimizations available via B<opt> depend upon what +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. The input must be an LLVM bitcode file. +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. @@ -39,9 +40,9 @@ writes its output to the standard output. =item B<-f> -Force overwrite. Normally, B<opt> will refuse to overwrite an -output file that already exists. With this option, B<opt> will -overwrite the output file and replace it with new bitcode. +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> @@ -51,6 +52,10 @@ Print a summary of command line options. 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 |
