From 59850d0874429601812bc13408cb1f776649027c Mon Sep 17 00:00:00 2001 From: Roman Divacky Date: Wed, 14 Oct 2009 17:57:32 +0000 Subject: Update llvm to r84119. --- docs/CommandGuide/FileCheck.pod | 65 +++++++++++ docs/CommandGuide/Makefile | 10 +- docs/CommandGuide/index.html | 4 +- docs/CommandGuide/lit.pod | 222 +++++++++++++++++++++++++++++++++++++ docs/CommandGuide/llc.pod | 22 ++-- docs/CommandGuide/llvm-as.pod | 6 +- docs/CommandGuide/llvm-dis.pod | 6 +- docs/CommandGuide/llvm-extract.pod | 10 +- docs/CommandGuide/llvm-ld.pod | 6 + docs/CommandGuide/llvm-link.pod | 9 +- docs/CommandGuide/llvmc.pod | 6 + docs/CommandGuide/opt.pod | 29 +++-- 12 files changed, 356 insertions(+), 39 deletions(-) create mode 100644 docs/CommandGuide/FileCheck.pod create mode 100644 docs/CommandGuide/lit.pod (limited to 'docs/CommandGuide') diff --git a/docs/CommandGuide/FileCheck.pod b/docs/CommandGuide/FileCheck.pod new file mode 100644 index 000000000000..539f66fea545 --- /dev/null +++ b/docs/CommandGuide/FileCheck.pod @@ -0,0 +1,65 @@ + +=pod + +=head1 NAME + +FileCheck - Flexible pattern matching file verifier + +=head1 SYNOPSIS + +B I [I<--check-prefix=XXX>] [I<--strict-whitespace>] + +=head1 DESCRIPTION + +B 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 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 is beyond the scope of this short +introduction. Please see the I page in the LLVM documentation. + +=head1 OPTIONS + +=over + +=item B<--help> + +Print a summary of command line options. + +=item B<--check-prefix> I + +FileCheck searches the contents of I 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 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). + +=cut diff --git a/docs/CommandGuide/Makefile b/docs/CommandGuide/Makefile index cf77e6a33db0..3b6518310726 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 f05260bfebb3..f1046fac4480 100644 --- a/docs/CommandGuide/index.html +++ b/docs/CommandGuide/index.html @@ -128,6 +128,8 @@ options) arguments to the tool you are interested in.

    +
  • FileCheck - + Flexible file verifier used extensively by the testing harness
  • tblgen - target description reader and generator
    • @@ -144,7 +146,7 @@ options) arguments to the tool you are interested in.

    src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"> LLVM Compiler Infrastructure
    - 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) $ diff --git a/docs/CommandGuide/lit.pod b/docs/CommandGuide/lit.pod new file mode 100644 index 000000000000..a818302c242a --- /dev/null +++ b/docs/CommandGuide/lit.pod @@ -0,0 +1,222 @@ +=pod + +=head1 NAME + +lit - LLVM Integrated Tester + +=head1 SYNOPSIS + +B [I] [I] + +=head1 DESCRIPTION + +B is a portable tool for executing LLVM and Clang style test suites, +summarizing their results, and providing indication of failures. B is +designed to be a lightweight testing tool with as simple a user interface as +possible. + +B should be run with one or more I 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 will print summary information on the number of tests +which passed or failed (see L<"TEST STATUS RESULTS">). The B program will +execute with a non-zero exit code if any tests fail. + +By default B will use a succinct progress display and will only print +summary information for test failures. See L<"OUTPUT OPTIONS"> for options +controlling the B progress display and output. + +B 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 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 help message. + +=item B<-j> I, B<--threads>=I + +Run I 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 + +Specify an addition I 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 + +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 + +Run at most I tests and then terminate. + +=item B<--max-time>=I + +Spend at most I 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 in debug mode, for debugging configuration issues and B 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 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 can be either individual tests, or entire +directories or hierarchies of tests to run. When B starts up, the first +thing it does is convert the inputs into a complete list of tests to run as part +of I. + +In the B model, every test must exist inside some I. B +resolves the inputs specified on the command line to test suites by searching +upwards from the input path until it finds a I or I +file. These files serve as both a marker of test suites and as configuration +files which B loads in order to understand how to find and run the tests +inside the test suite. + +Once B 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 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 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 + +The test succeeded. + +=item B + +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 + +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 + +The test failed. + +=item B + +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 + +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 +section for more information. + +=head1 SEE ALSO + +L + +=head1 AUTHOR + +Written by Daniel Dunbar and maintained by the LLVM Team (L). + +=cut diff --git a/docs/CommandGuide/llc.pod b/docs/CommandGuide/llc.pod index eba7859e2882..8adfb682be01 100644 --- a/docs/CommandGuide/llc.pod +++ b/docs/CommandGuide/llc.pod @@ -10,18 +10,19 @@ B [I] [I] =head1 DESCRIPTION -The B command compiles LLVM bitcode into assembly language for a +The B 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 is - or omitted, B reads LLVM bitcode from standard input. -Otherwise, it will read LLVM bitcode from I. +If I is - or omitted, B reads from standard input. Otherwise, it +will from I. 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 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 and B. -=item B<-f> - -Overwrite output files. By default, B will refuse to overwrite -an output file which already exists. - =item B<-mtriple>=I -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 Specify the architecture for which to generate assembly, overriding the target -encoded in the bitcode file. See the output of B for a list of +encoded in the input file. See the output of B 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 2befed13ae00..045a9245b609 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 will refuse to overwrite an -output file that already exists. With this option, B -will overwrite the output file and replace it with new bitcode. +Enable binary output on terminals. Normally, B will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B 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 8df382d2e9c0..2b83290c9b2e 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 will refuse to overwrite -an output file that already exists. With this option, B -will overwrite the output file. +Enable binary output on terminals. Normally, B will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B 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 d916612ec5c6..b62e8ae312bf 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 will refuse to overwrite an -output file that already exists. With this option, B -will overwrite the output file and replace it with new bitcode. +Enable binary output on terminals. Normally, B will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B will write raw bitcode regardless of the output device. =item B<--func> I @@ -45,6 +45,10 @@ Print a summary of command line options. Specify the output filename. If filename is "-" (the default), then B 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 224939c77c94..536ab0fa43d5 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 generates a file named F for compatibility with B. The output will be written to F. +=item B<-b> F + +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 This option specifies the F of a library to search when resolving symbols diff --git a/docs/CommandGuide/llvm-link.pod b/docs/CommandGuide/llvm-link.pod index 5f4dcb6e354d..e1a1267c52ec 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 will not overwrite an output -file if it already exists. +Enable binary output on terminals. Normally, B will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B will write raw bitcode regardless of the output device. =item B<-o> F Specify the output file name. If F is C<->, then B 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 prints a human-readable version of the output diff --git a/docs/CommandGuide/llvmc.pod b/docs/CommandGuide/llvmc.pod index 97445edf4127..e3031e123d38 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 + +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 75b7eddd4cf1..d1d1db5ef67e 100644 --- a/docs/CommandGuide/opt.pod +++ b/docs/CommandGuide/opt.pod @@ -11,24 +11,25 @@ B [I] [I] =head1 DESCRIPTION The B 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 depends on whether the B<-analyze> option is given. -When B<-analyze> is specified, B 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 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 given, B attempts to produce an optimized -bitcode file. The optimizations available via B depend upon what +output file. The optimizations available via B 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 is omitted from the command line or is I<->, B 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 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 will refuse to overwrite an -output file that already exists. With this option, B will -overwrite the output file and replace it with new bitcode. +Enable binary output on terminals. Normally, B will refuse to +write raw bitcode output if the output stream is a terminal. With this option, +B 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 provides the ability to run any of LLVM's optimization or analysis passes -- cgit v1.2.3