diff options
Diffstat (limited to 'docs/CommandGuide')
| -rw-r--r-- | docs/CommandGuide/FileCheck.rst | 97 | ||||
| -rw-r--r-- | docs/CommandGuide/bugpoint.rst | 84 | ||||
| -rw-r--r-- | docs/CommandGuide/lit.rst | 417 | ||||
| -rw-r--r-- | docs/CommandGuide/llc.rst | 176 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-cov.rst | 40 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-link.rst | 86 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-stress.rst | 30 | ||||
| -rw-r--r-- | docs/CommandGuide/opt.rst | 182 | ||||
| -rw-r--r-- | docs/CommandGuide/tblgen.rst | 139 |
9 files changed, 454 insertions, 797 deletions
diff --git a/docs/CommandGuide/FileCheck.rst b/docs/CommandGuide/FileCheck.rst index 5e145f620f..256970b362 100644 --- a/docs/CommandGuide/FileCheck.rst +++ b/docs/CommandGuide/FileCheck.rst @@ -4,57 +4,57 @@ FileCheck - Flexible pattern matching file verifier SYNOPSIS -------- -**FileCheck** *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] +:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] DESCRIPTION ----------- -**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. +:program:`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. :program:`llc`) contains the expected information +(for example, a movsd from esp or whatever is interesting). This is similar to +using :program:`grep`, but it is optimized for matching multiple different +inputs in one file in a specific order. -The *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. OPTIONS ------- -**-help** +.. option:: -help Print a summary of command line options. -**--check-prefix** *prefix* +.. option:: --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. + 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 :option:`--check-prefix` argument allows you + to specify a specific prefix to match. -**--input-file** *filename* +.. option:: --input-file filename File to check (defaults to stdin). -**--strict-whitespace** +.. option:: --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. + The :option:`--strict-whitespace` argument disables this behavior. - -**-version** +.. option:: -version Show the version number of this program. 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. +If :program:`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. TUTORIAL -------- @@ -67,7 +67,6 @@ like this: ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s - This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``. This means that FileCheck will be verifying its standard input (the llc output) @@ -93,7 +92,6 @@ against the filename argument specified (the original ``.ll`` file specified by ret void } - Here you can see some "``CHECK:``" lines specified in comments. Now you can see how the file is piped into ``llvm-as``, then ``llc``, and the machine code output is what we are verifying. FileCheck checks the machine code output to @@ -114,9 +112,10 @@ exists anywhere in the file. 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: +The FileCheck :option:`-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 +:program:`llc`. Here's a simple example: .. code-block:: llvm @@ -194,7 +193,6 @@ can be used: ; CHECK: ret i8 } - FileCheck Pattern Matching Syntax ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -225,9 +223,9 @@ FileCheck Variables It is often useful to match a pattern and then verify that it occurs again later in the file. For codegen tests, this can be useful to allow any register, -but verify that that register is used consistently later. To do this, FileCheck -allows named variables to be defined and substituted into patterns. Here is a -simple example: +but verify that that register is used consistently later. To do this, +:program:`FileCheck` allows named variables to be defined and substituted into +patterns. Here is a simple example: .. code-block:: llvm @@ -237,31 +235,30 @@ simple example: 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 ``[[ ]]`` pairs, and their names can be -formed with the regex ``[a-zA-Z][a-zA-Z0-9]*``. If a colon follows the name, +``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck` +variable references are always contained in ``[[ ]]`` pairs, and their names can +be formed with the regex ``[a-zA-Z][a-zA-Z0-9]*``. If a colon follows the name, then it is a definition of the variable; otherwise, 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 "``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. +:program:`FileCheck` variables can be defined multiple times, and uses always +get the latest value. Variables can also be used later on the same line they +were defined on. For example: +.. code-block:: llvm + + ; CHECK: op [[REG:r[0-9]+]], [[REG]] + +Can be useful if you want the operands of ``op`` to be the same register, +and don't care exactly which register it is. FileCheck Expressions ~~~~~~~~~~~~~~~~~~~~~ - -Sometimes there's a need to verify output which refers line numbers of the match -file, e.g. when testing compiler diagnostics. This introduces a certain -fragility of the match file structure, as CHECK: lines contain absolute line -numbers in the same file, which have to be updated whenever line numbers change -due to text addition or deletion. +Sometimes there's a need to verify output which refers line numbers of the +match file, e.g. when testing compiler diagnostics. This introduces a certain +fragility of the match file structure, as "``CHECK:``" lines contain absolute +line numbers in the same file, which have to be updated whenever line numbers +change due to text addition or deletion. To support this case, FileCheck allows using ``[[@LINE]]``, ``[[@LINE+<offset>]]``, ``[[@LINE-<offset>]]`` expressions in patterns. These diff --git a/docs/CommandGuide/bugpoint.rst b/docs/CommandGuide/bugpoint.rst index c1b3b6eca6..e4663e5d44 100644 --- a/docs/CommandGuide/bugpoint.rst +++ b/docs/CommandGuide/bugpoint.rst @@ -1,19 +1,15 @@ 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 @@ -22,82 +18,61 @@ For more information on the design and inner workings of **bugpoint**, as well a 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: - + 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 + .. code-block:: bash 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. - - + 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 + 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 + .. code-block:: bash 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.) - - + 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 @@ -105,36 +80,26 @@ OPTIONS 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 @@ -143,20 +108,15 @@ OPTIONS optimizations, use the **-help** and **--load** options together; for example: - .. code-block:: perl + .. code-block:: bash 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 @@ -164,14 +124,10 @@ OPTIONS 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 @@ -179,8 +135,6 @@ OPTIONS 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 @@ -192,16 +146,12 @@ OPTIONS 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** @@ -210,38 +160,28 @@ OPTIONS 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/lit.rst b/docs/CommandGuide/lit.rst index 8886fe6a45..1dcaff10bf 100644 --- a/docs/CommandGuide/lit.rst +++ b/docs/CommandGuide/lit.rst @@ -1,351 +1,282 @@ lit - LLVM Integrated Tester ============================ - SYNOPSIS -------- - -**lit** [*options*] [*tests*] - +:program:`lit` [*options*] [*tests*] DESCRIPTION ----------- +:program:`lit` is a portable tool for executing LLVM and Clang style test +suites, summarizing their results, and providing indication of failures. +:program:`lit` is designed to be a lightweight testing tool with as simple a +user interface as possible. -**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"). +:program:`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 :ref:`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. +tests have been run :program:`lit` will print summary information on the number +of tests which passed or failed (see :ref:`test-status-results`). The +:program:`lit` program will execute with a non-zero exit code if any tests +fail. -**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. +By default :program:`lit` will use a succinct progress display and will only +print summary information for test failures. See :ref:`output-options` for +options controlling the :program:`lit` progress display and output. -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. +:program:`lit` also includes a number of options for controlling how tests are +executed (specific features may depend on the particular test format). See +:ref:`execution-options` for more information. -Users interested in the **lit** architecture or designing a **lit** testing -implementation should see "LIT INFRASTRUCTURE" +Finally, :program:`lit` also supports additional options for only running a +subset of the options specified on the command line, see +:ref:`selection-options` for more information. +Users interested in the :program:`lit` architecture or designing a +:program:`lit` testing implementation should see :ref:`lit-infrastructure`. GENERAL OPTIONS --------------- +.. option:: -h, --help + Show the :program:`lit` help message. -**-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. - - +.. option:: -j N, --threads=N -**--config-prefix**\ =\ *NAME* + Run ``N`` tests in parallel. By default, this is automatically chosen to + match the number of detected available CPUs. - Search for *NAME.cfg* and *NAME.site.cfg* when searching for test suites, - instead of *lit.cfg* and *lit.site.cfg*. +.. option:: --config-prefix=NAME + Search for :file:`{NAME}.cfg` and :file:`{NAME}.site.cfg` when searching for + test suites, instead of :file:`lit.cfg` and :file:`lit.site.cfg`. +.. option:: --param NAME, --param NAME=VALUE -**--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 + 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: OUTPUT OPTIONS -------------- - - -**-q**, **--quiet** +.. option:: -q, --quiet Suppress any output except for test failures. - - -**-s**, **--succinct** +.. option:: -s, --succinct Show less output, for example don't show information on tests that pass. - - -**-v**, **--verbose** +.. option:: -v, --verbose Show more information on test failures, for example the entire test output instead of just the test result. - - -**--no-progress-bar** +.. option:: --no-progress-bar Do not use curses based progress bar. - - +.. _execution-options: EXECUTION OPTIONS ----------------- +.. option:: --path=PATH + Specify an additional ``PATH`` to use when searching for executables in tests. -**--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. - - When this option is enabled, **lit** will also automatically provide a - "valgrind" feature that can be used to conditionally disable (or expect failure - in) certain tests. - - - -**--vg-arg**\ =\ *ARG* - - When *--vg* is used, specify an additional argument to pass to valgrind itself. +.. option:: --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. + When this option is enabled, :program:`lit` will also automatically provide a + "``valgrind``" feature that can be used to conditionally disable (or expect + failure in) certain tests. -**--vg-leak** +.. option:: --vg-arg=ARG - When *--vg* is used, enable memory leak checks. When this option is enabled, - **lit** will also automatically provide a "vg_leak" feature that can be - used to conditionally disable (or expect failure in) certain tests. + When :option:`--vg` is used, specify an additional argument to pass to + :program:`valgrind` itself. +.. option:: --vg-leak + When :option:`--vg` is used, enable memory leak checks. When this option is + enabled, :program:`lit` will also automatically provide a "``vg_leak``" + feature that can be used to conditionally disable (or expect failure in) + certain tests. +.. option:: --time-tests -**--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*. - - + 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: SELECTION OPTIONS ----------------- +.. option:: --max-tests=N + Run at most ``N`` tests and then terminate. -**--max-tests**\ =\ *N* - - Run at most *N* tests and then terminate. - - +.. option:: --max-time=N -**--max-time**\ =\ *N* + Spend at most ``N`` seconds (approximately) running tests and then terminate. - Spend at most *N* seconds (approximately) running tests and then terminate. - - - -**--shuffle** +.. option:: --shuffle Run the tests in a random order. - - - ADDITIONAL OPTIONS ------------------ +.. option:: --debug + Run :program:`lit` in debug mode, for debugging configuration issues and + :program:`lit` itself. -**--debug** - - Run **lit** in debug mode, for debugging configuration issues and **lit** itself. - - - -**--show-suites** +.. option:: --show-suites List the discovered test suites as part of the standard output. - - -**--no-tcl-as-sh** +.. option:: --no-tcl-as-sh Run Tcl scripts internally (instead of converting to shell scripts). +.. option:: --repeat=N - -**--repeat**\ =\ *N* - - Run each test *N* times. Currently this is primarily useful for timing tests, - other results are not collated in any reasonable fashion. - - - + 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 +:program:`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: TEST DISCOVERY -------------- +The inputs passed to :program:`lit` can be either individual tests, or entire +directories or hierarchies of tests to run. When :program:`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*. -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. +In the :program:`lit` model, every test must exist inside some *test suite*. +:program:`lit` resolves the inputs specified on the command line to test suites +by searching upwards from the input path until it finds a :file:`lit.cfg` or +:file:`lit.site.cfg` file. These files serve as both a marker of test suites +and as configuration files which :program:`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. +Once :program:`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. +interpreted. In addition, :program:`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 :program:`lit` to provide +convenient and flexible support for out-of-tree builds. +.. _test-status-results: 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 + 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 + 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 + 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 + 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" +their status (generally only for failures). See the :ref:`output-options` section for more information. +.. _lit-infrastructure: LIT INFRASTRUCTURE ------------------ +This section describes the :program:`lit` testing architecture for users interested in +creating a new :program:`lit` testing implementation, or extending an existing one. -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 +:program:`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 +tests. :program:`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 +As described in :ref:`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. +:program:`lit` identifies test suites as directories containing ``lit.cfg`` or +``lit.site.cfg`` files (see also :option:`--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 +:option:`--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 +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 + 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: @@ -353,135 +284,133 @@ executed, two important global variables are predefined: 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 + 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 + **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 + 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*, + 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*. + 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*. + 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 + **root** The root configuration. This is the top-most :program:`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* + 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 + 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"). +Once test suites are located, :program:`lit` recursively traverses the source +directory (following *test_src_root*) looking for tests. When :program:`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 +:ref:`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. +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: 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. - +When :program:`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 :program:`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 :program:`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. -The **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: -Each test result is expected to appear on a line that matches:: +.. code-block:: none <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 +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 ``<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. +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:: +following format: + +.. code-block:: none <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. +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:: +B, C, and D, and a log message for the failing test C: + +.. code-block:: none PASS: A (1 of 4) PASS: B (2 of 4) FAIL: C (3 of 4) - \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* TEST 'C' FAILED \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* + ******************** 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. - +The :program:`lit` distribution contains several example implementations of +test suites in the *ExampleTests* directory. SEE ALSO -------- - valgrind(1) diff --git a/docs/CommandGuide/llc.rst b/docs/CommandGuide/llc.rst index 6f1c486c3f..70354b0343 100644 --- a/docs/CommandGuide/llc.rst +++ b/docs/CommandGuide/llc.rst @@ -1,251 +1,187 @@ llc - LLVM static compiler ========================== - SYNOPSIS -------- - -**llc** [*options*] [*filename*] - +:program:`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 :program:`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. - +determined from the input file, unless the :option:`-march` option is used to +override the default. OPTIONS ------- +If ``filename`` is "``-``" or omitted, :program:`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 *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 :option:`-o` option is omitted, then :program:`llc` will send its output +to standard output if the input is from standard input. If the :option:`-o` +option specifies "``-``", then the output will also be sent to standard output. -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 :option:`-o` option is specified and an input file other than "``-``" is +specified, then :program:`llc` creates the output filename by taking the input +filename, removing any existing ``.bc`` extension, and adding a ``.s`` suffix. -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: +Other :program:`llc` options are described below. End-user Options ~~~~~~~~~~~~~~~~ - - -**-help** +.. option:: -help Print a summary of command line options. +.. option:: -O=uint + Generate code at different optimization levels. These correspond to the + ``-O0``, ``-O1``, ``-O2``, and ``-O3`` optimization levels used by + :program:`llvm-gcc` and :program:`clang`. -**-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* +.. option:: -mtriple=<target triple> Override the target triple specified in the input file with the specified string. - - -**-march**\ =\ *arch* +.. option:: -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 + 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* +.. option:: -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** + .. code-block:: none + llvm-as < /dev/null | llc -march=xyz -mcpu=help -**-mattr**\ =\ *a1,+a2,-a3,...* +.. option:: -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** + .. code-block:: none + llvm-as < /dev/null | llc -march=xyz -mattr=help -**--disable-fp-elim** +.. option:: --disable-fp-elim Disable frame pointer elimination optimization. - - -**--disable-excess-fp-precision** +.. option:: --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** +.. option:: --enable-no-infs-fp-math Enable optimizations that assume no Inf values. - - -**--enable-no-nans-fp-math** +.. option:: --enable-no-nans-fp-math Enable optimizations that assume no NAN values. - - -**--enable-unsafe-fp-math** +.. option:: --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). - + would otherwise not be usable (such as ``fsin`` on X86). +.. option:: --enable-correct-eh-support -**--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. - Instruct the **lowerinvoke** pass to insert code for correct exception handling - support. This is expensive and is by default omitted for efficiency. - - - -**--stats** +.. option:: --stats Print statistics recorded by code-generation passes. - - -**--time-passes** +.. option:: --time-passes Record the amount of time needed for each pass and print a report to standard error. +.. option:: --load=<dso_path> - -**--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. - - - + 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 :option:`-march` option so that code can be generated for that target. Tuning/Configuration Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -**--print-machineinstrs** +.. option:: --print-machineinstrs Print generated machine code between compilation phases (useful for debugging). +.. option:: --regalloc=<allocator> - -**--regalloc**\ =\ *allocator* - - Specify the register allocator to use. The default *allocator* is *local*. + 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* +.. option:: --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: - + 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: --x86-asm-syntax=[att|intel] - -**--x86-asm-syntax=att|intel** - - Specify whether to emit assembly code in AT&T syntax (the default) or 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. - +If :program:`llc` succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. SEE ALSO -------- +lli -lli|lli diff --git a/docs/CommandGuide/llvm-cov.rst b/docs/CommandGuide/llvm-cov.rst index 09275f6af7..524f24087f 100644 --- a/docs/CommandGuide/llvm-cov.rst +++ b/docs/CommandGuide/llvm-cov.rst @@ -1,51 +1,39 @@ llvm-cov - emit coverage information ==================================== - SYNOPSIS -------- - -**llvm-cov** [-gcno=filename] [-gcda=filename] [dump] - +:program:`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. - +The experimental :program:`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 ------- +.. option:: -gcno=filename + This option selects input description file generated by compiler while + instrumenting program. -**-gcno=filename]** - - This option selects input description file generated by compiler while instrumenting - program. - - - -**-gcda=filename]** +.. option:: -gcda=filename This option selects coverage data file generated by instrumented compiler. +.. option:: -dump - -**-dump** - - This options enables output dump that is suitable for a developer to help debug - **llvm-cov** itself. - - - + This options enables output dump that is suitable for a developer to help + debug :program:`llvm-cov` itself. EXIT STATUS ----------- +:program:`llvm-cov` returns 1 if it cannot read input files. Otherwise, it +exits with zero. -**llvm-cov** returns 1 if it cannot read input files. Otherwise, it exits with zero. diff --git a/docs/CommandGuide/llvm-link.rst b/docs/CommandGuide/llvm-link.rst index 63019d7cca..e4f2228841 100644 --- a/docs/CommandGuide/llvm-link.rst +++ b/docs/CommandGuide/llvm-link.rst @@ -1,96 +1,74 @@ llvm-link - LLVM linker ======================= - SYNOPSIS -------- - -**llvm-link** [*options*] *filename ...* - +:program:`llvm-link` [*options*] *filename ...* DESCRIPTION ----------- +:program:`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 :option:`-o` option is used to specify a filename. -**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. - +:program:`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 :option:`-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 ------- +.. option:: -L directory + Add the specified ``directory`` to the library search path. When looking for + libraries, :program:`llvm-link` will look in path name for libraries. This + option can be specified multiple times; :program:`llvm-link` will search + inside these directories in the order in which they were specified on the + command line. -**-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. - - +.. option:: -f -**-o** *filename* + Enable binary output on terminals. Normally, :program:`llvm-link` will refuse + to write raw bitcode output if the output stream is a terminal. With this + option, :program:`llvm-link` will write raw bitcode regardless of the output + device. - Specify the output file name. If *filename* is ``-``, then **llvm-link** will - write its output to standard output. +.. option:: -o filename + Specify the output file name. If ``filename`` is "``-``", then + :program:`llvm-link` will write its output to standard output. - -**-S** +.. option:: -S Write output in LLVM intermediate language (instead of bitcode). +.. option:: -d - -**-d** - - If specified, **llvm-link** prints a human-readable version of the output + If specified, :program:`llvm-link` prints a human-readable version of the output bitcode file to standard error. - - -**-help** +.. option:: -help Print a summary of command line options. +.. option:: -v - -**-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 + Verbose mode. Print information about what :program:`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 +If :program:`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|gccld diff --git a/docs/CommandGuide/llvm-stress.rst b/docs/CommandGuide/llvm-stress.rst index 44aa32c755..fb006f562b 100644 --- a/docs/CommandGuide/llvm-stress.rst +++ b/docs/CommandGuide/llvm-stress.rst @@ -1,48 +1,34 @@ llvm-stress - generate random .ll files ======================================= - SYNOPSIS -------- - -**llvm-stress** [-size=filesize] [-seed=initialseed] [-o=outfile] - +:program:`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. - +The :program:`llvm-stress` tool is used to generate random ``.ll`` files that +can be used to test different components of LLVM. OPTIONS ------- - - -**-o** *filename* +.. option:: -o filename Specify the output filename. +.. option:: -size size + Specify the size of the generated ``.ll`` file. -**-size** *size* - - Specify the size of the generated .ll file. - - - -**-seed** *seed* +.. option:: -seed seed Specify the seed to be used for the randomly generated instructions. - - - EXIT STATUS ----------- +:program:`llvm-stress` returns 0. -**llvm-stress** returns 0. diff --git a/docs/CommandGuide/opt.rst b/docs/CommandGuide/opt.rst index 72f19034c9..179c297c22 100644 --- a/docs/CommandGuide/opt.rst +++ b/docs/CommandGuide/opt.rst @@ -1,183 +1,143 @@ opt - LLVM optimizer ==================== - SYNOPSIS -------- - -**opt** [*options*] [*filename*] - +:program:`opt` [*options*] [*filename*] DESCRIPTION ----------- +The :program:`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 :program:`opt` depends on whether the :option:`-analyze` option is +given. -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 +When :option:`-analyze` is specified, :program:`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). +While :option:`-analyze` is *not* given, :program:`opt` attempts to produce an +optimized output file. The optimizations available via :program:`opt` depend +upon what libraries were linked into it as well as any additional libraries +that have been loaded with the :option:`-load` option. Use the :option:`-help` +option to determine what optimizations you can use. -If an output filename is not specified with the **-o** option, **opt** -writes its output to the standard output. +If ``filename`` is omitted from the command line or is "``-``", :program:`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 :option:`-o` option, +:program:`opt` writes its output to the standard output. OPTIONS ------- +.. option:: -f + Enable binary output on terminals. Normally, :program:`opt` will refuse to + write raw bitcode output if the output stream is a terminal. With this option, + :program:`opt` will write raw bitcode regardless of the output device. -**-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** +.. option:: -help Print a summary of command line options. - - -**-o** *filename* +.. option:: -o <filename> Specify the output filename. - - -**-S** +.. option:: -S Write output in LLVM intermediate language (instead of bitcode). +.. option:: -{passname} + :program:`opt` provides the ability to run any of LLVM's optimization or + analysis passes in any order. The :option:`-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). -**-{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** +.. option:: -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: - + 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 +.. option:: -disable-inlining + This option is only meaningful when :option:`-std-compile-opts` is given. It + simply removes the inlining pass from the standard list. +.. option:: -disable-opt -**-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**. + This option is only meaningful when :option:`-std-compile-opts` is given. It + disables most, but not all, of the :option:`-std-compile-opts`. The ones that + remain are :option:`-verify`, :option:`-lower-setjmp`, and + :option:`-funcresolve`. - - -**-strip-debug** +.. option:: -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. + applying other optimizations. It is essentially the same as :option:`-strip` + but it ensures that stripping of debug information is done first. +.. option:: -verify-each + This option causes opt to add a verify pass after every pass otherwise + specified on the command line (including :option:`-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 + :option:`-std-compile-opts` and :option:`-verify-each` can quickly track down + this kind of problem. -**-profile-info-file** *filename* +.. option:: -profile-info-file <filename> - Specify the name of the file loaded by the -profile-loader option. + Specify the name of the file loaded by the ``-profile-loader`` option. - - -**-stats** +.. option:: -stats Print statistics. - - -**-time-passes** +.. option:: -time-passes Record the amount of time needed for each pass and print it to standard error. +.. option:: -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 + <../ProgrammersManual.html>`_, section ``#DEBUG`` for more information. -**-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: +.. option:: -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 :option:`-help` and :option:`-load` + options together. For example: .. code-block:: sh opt -load=plugin.so -help - - - -**-p** +.. option:: -p Print module after each transformation. - - - EXIT STATUS ----------- - -If **opt** succeeds, it will exit with 0. Otherwise, if an error +If :program:`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.rst b/docs/CommandGuide/tblgen.rst index 2d191676d9..1858ee447d 100644 --- a/docs/CommandGuide/tblgen.rst +++ b/docs/CommandGuide/tblgen.rst @@ -1,186 +1,129 @@ tblgen - Target Description To C++ Code Generator ================================================= - SYNOPSIS -------- - -**tblgen** [*options*] [*filename*] - +:program:`tblgen` [*options*] [*filename*] DESCRIPTION ----------- +:program:`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. -**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. +The input and output of :program:`tblgen` is beyond the scope of this short +introduction. Please see :doc:`../TableGenFundamentals`. +The *filename* argument specifies the name of a Target Description (``.td``) +file to read as input. OPTIONS ------- - - -**-help** +.. option:: -help Print a summary of command line options. +.. option:: -o filename + Specify the output file name. If ``filename`` is ``-``, then + :program:`tblgen` sends its output to standard output. -**-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* +.. option:: -I directory - Make -gen-asm-parser emit assembly writer number *N*. + 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. +.. option:: -asmparsernum N + Make -gen-asm-parser emit assembly writer number ``N``. -**-asmwriternum** *N* +.. option:: -asmwriternum N - Make -gen-asm-writer emit assembly writer number *N*. + Make -gen-asm-writer emit assembly writer number ``N``. - - -**-class** *class Name* +.. option:: -class className Print the enumeration list for this class. - - -**-print-records** +.. option:: -print-records Print all records to standard output (default). - - -**-print-enums** +.. option:: -print-enums Print enumeration values for a class - - -**-print-sets** +.. option:: -print-sets Print expanded sets for testing DAG exprs. - - -**-gen-emitter** +.. option:: -gen-emitter Generate machine code emitter. - - -**-gen-register-info** +.. option:: -gen-register-info Generate registers and register classes info. - - -**-gen-instr-info** +.. option:: -gen-instr-info Generate instruction descriptions. - - -**-gen-asm-writer** +.. option:: -gen-asm-writer Generate the assembly writer. - - -**-gen-disassembler** +.. option:: -gen-disassembler Generate disassembler. - - -**-gen-pseudo-lowering** +.. option:: -gen-pseudo-lowering Generate pseudo instruction lowering. - - -**-gen-dag-isel** +.. option:: -gen-dag-isel Generate a DAG (Directed Acycle Graph) instruction selector. - - -**-gen-asm-matcher** +.. option:: -gen-asm-matcher Generate assembly instruction matcher. - - -**-gen-dfa-packetizer** +.. option:: -gen-dfa-packetizer Generate DFA Packetizer for VLIW targets. - - -**-gen-fast-isel** +.. option:: -gen-fast-isel Generate a "fast" instruction selector. - - -**-gen-subtarget** +.. option:: -gen-subtarget Generate subtarget enumerations. - - -**-gen-intrinsic** +.. option:: -gen-intrinsic Generate intrinsic information. - - -**-gen-tgt-intrinsic** +.. option:: -gen-tgt-intrinsic Generate target intrinsic information. - - -**-gen-enhanced-disassembly-info** +.. option:: -gen-enhanced-disassembly-info Generate enhanced disassembly info. - - -**-version** +.. option:: -version Show the version number of this program. - - - EXIT STATUS ----------- - -If **tblgen** succeeds, it will exit with 0. Otherwise, if an error +If :program:`tblgen` succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non-zero value. |