From 021536888766ab8e0e27cd4c5f48ad6031399ca4 Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Wed, 28 Nov 2012 21:40:54 +0000 Subject: Documentation: improve formatting and remove unneeded empty lines. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168817 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CommandGuide/bugpoint.rst | 78 +++++------------------------------------- 1 file changed, 9 insertions(+), 69 deletions(-) (limited to 'docs/CommandGuide') diff --git a/docs/CommandGuide/bugpoint.rst b/docs/CommandGuide/bugpoint.rst index c1b3b6eca6..66eba743d8 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 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 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 @@ -147,16 +112,11 @@ OPTIONS 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 -- cgit v1.2.3-18-g5258 From 6bb2b5d76e593476245f004d1996a7330465dd38 Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Thu, 29 Nov 2012 12:00:32 +0000 Subject: Documentation: use correct highlighter git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168871 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CommandGuide/bugpoint.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/CommandGuide') diff --git a/docs/CommandGuide/bugpoint.rst b/docs/CommandGuide/bugpoint.rst index 66eba743d8..e4663e5d44 100644 --- a/docs/CommandGuide/bugpoint.rst +++ b/docs/CommandGuide/bugpoint.rst @@ -37,7 +37,7 @@ OPTIONS 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] @@ -51,7 +51,7 @@ OPTIONS (**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] @@ -108,7 +108,7 @@ OPTIONS optimizations, use the **-help** and **--load** options together; for example: - .. code-block:: perl + .. code-block:: bash bugpoint --load myNewPass.so -help -- cgit v1.2.3-18-g5258 From e26b62cb619ec46d1fd487997ba774ea71a0eb17 Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Thu, 29 Nov 2012 17:05:34 +0000 Subject: Documentation for lit: formatting improvements. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168902 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CommandGuide/lit.rst | 158 ++++++++++++---------------------------------- 1 file changed, 41 insertions(+), 117 deletions(-) (limited to 'docs/CommandGuide') diff --git a/docs/CommandGuide/lit.rst b/docs/CommandGuide/lit.rst index 8886fe6a45..00b5c070d4 100644 --- a/docs/CommandGuide/lit.rst +++ b/docs/CommandGuide/lit.rst @@ -1,18 +1,14 @@ lit - LLVM Integrated Tester ============================ - SYNOPSIS -------- - **lit** [*options*] [*tests*] - DESCRIPTION ----------- - **lit** is a portable tool for executing LLVM and Clang style test suites, summarizing their results, and providing indication of failures. **lit** is designed to be a lightweight testing tool with as simple a user interface as @@ -20,105 +16,82 @@ 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"). +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 +which passed or failed (see :ref:`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 +summary information for test failures. See :ref:`output-options` for options controlling the **lit** progress display and output. **lit** also includes a number of options for controlling how tests are executed -(specific features may depend on the particular test format). See "EXECUTION -OPTIONS" for more information. +(specific features may depend on the particular test format). See +:ref:`execution-options` for more information. Finally, **lit** also supports additional options for only running a subset of -the options specified on the command line, see "SELECTION OPTIONS" for +the options specified on the command line, see :ref:`selection-options` for more information. Users interested in the **lit** architecture or designing a **lit** testing -implementation should see "LIT INFRASTRUCTURE" - +implementation should see :ref:`lit-infrastructure`. GENERAL OPTIONS --------------- - - **-h**, **--help** Show the **lit** help message. - - **-j** *N*, **--threads**\ =\ *N* Run *N* tests in parallel. By default, this is automatically chosen to match the number of detected available CPUs. - - **--config-prefix**\ =\ *NAME* Search for *NAME.cfg* and *NAME.site.cfg* when searching for test suites, instead of *lit.cfg* and *lit.site.cfg*. - - **--param** *NAME*, **--param** *NAME*\ =\ *VALUE* Add a user defined parameter *NAME* with the given *VALUE* (or the empty string if not given). The meaning and use of these parameters is test suite dependent. - - +.. _output-options: OUTPUT OPTIONS -------------- - - **-q**, **--quiet** Suppress any output except for test failures. - - **-s**, **--succinct** Show less output, for example don't show information on tests that pass. - - **-v**, **--verbose** Show more information on test failures, for example the entire test output instead of just the test result. - - **--no-progress-bar** Do not use curses based progress bar. - - +.. _execution-options: EXECUTION OPTIONS ----------------- - - **--path**\ =\ *PATH* Specify an addition *PATH* to use when searching for executables in tests. - - **--vg** Run individual tests under valgrind (using the memcheck tool). The @@ -129,23 +102,16 @@ EXECUTION OPTIONS "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. - - **--vg-leak** 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. - - - **--time-tests** Track the wall time individual tests take to execute and includes the results in @@ -153,78 +119,56 @@ EXECUTION OPTIONS take the most time to execute. Note that this option is most useful with *-j 1*. - - +.. _selection-options: SELECTION OPTIONS ----------------- - - **--max-tests**\ =\ *N* Run at most *N* tests and then terminate. - - **--max-time**\ =\ *N* Spend at most *N* seconds (approximately) running tests and then terminate. - - **--shuffle** Run the tests in a random order. - - - ADDITIONAL OPTIONS ------------------ - - **--debug** Run **lit** in debug mode, for debugging configuration issues and **lit** itself. - - **--show-suites** List the discovered test suites as part of the standard output. - - **--no-tcl-as-sh** Run Tcl scripts internally (instead of converting to shell scripts). - - **--repeat**\ =\ *N* Run each test *N* times. Currently this is primarily useful for timing tests, other results are not collated in any reasonable fashion. - - - EXIT STATUS ----------- - **lit** will exit with an exit code of 1 if there are any FAIL or XPASS results. Otherwise, it will exit with the status 0. Other exit codes are used for non-test related failures (for example a user error or an internal program error). +.. _test-discovery: 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 @@ -248,65 +192,52 @@ are in, and their relative path inside the test suite. For appropriately configured projects, this allows **lit** to provide convenient and flexible support for out-of-tree builds. +.. _test-status-results: TEST STATUS RESULTS ------------------- - Each test ultimately produces one of the following six results: - **PASS** The test succeeded. - - **XFAIL** The test failed, but that is expected. This is used for test formats which allow specifying that a test does not currently work, but wish to leave it in the test suite. - - **XPASS** The test succeeded, but it was expected to fail. This is used for tests which were specified as expected to fail, but are now succeeding (generally because the feature they test was broken and has been fixed). - - **FAIL** The test failed. - - **UNRESOLVED** The test result could not be determined. For example, this occurs when the test could not be run, the test itself is invalid, or the test was interrupted. - - **UNSUPPORTED** The test is not supported in this environment. This is used by test formats which can report unsupported tests. - - Depending on the test format tests may produce additional information about -their status (generally only for failures). See the Output|"OUTPUT OPTIONS" +their status (generally only for failures). See the :ref:`output-options` section for more information. +.. _lit-infrastructure: LIT INFRASTRUCTURE ------------------ - This section describes the **lit** testing architecture for users interested in creating a new **lit** testing implementation, or extending an existing one. @@ -318,8 +249,7 @@ defined by *test suites*. TEST SUITES ~~~~~~~~~~~ - -As described in "TEST DISCOVERY", tests are always located inside a *test +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. @@ -333,15 +263,12 @@ 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, @@ -390,19 +317,15 @@ executed, two important global variables are predefined: *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"). +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 @@ -410,78 +333,79 @@ 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 +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 +parameters --- for example, to change the test format, or the suffixes which identify test files. - TEST RUN OUTPUT FORMAT ~~~~~~~~~~~~~~~~~~~~~~ - 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 : () -where is a standard test result such as PASS, FAIL, XFAIL, XPASS, -UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and +where ```` 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 field can consist of an arbitrary string containing no newline. +The ```` field can consist of an arbitrary string containing no +newline. -The 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 ```` 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 TEST '()' ... log message ... -where should be the name of a preceding reported test, is a string of '\*' characters *at least* four characters long (the -recommended length is 20), and is an arbitrary (unparsed) -string. +where ```` should be the name of a preceding reported test, ```` is a string of "*" characters *at least* four characters long +(the recommended length is 20), and ```` 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. - SEE ALSO -------- - valgrind(1) -- cgit v1.2.3-18-g5258 From 6a144e40b059735cd8e701f382680fc1725954bf Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Thu, 29 Nov 2012 17:41:05 +0000 Subject: Documentation for tblgen: formatting git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168904 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CommandGuide/tblgen.rst | 139 +++++++++++++------------------------------ 1 file changed, 41 insertions(+), 98 deletions(-) (limited to 'docs/CommandGuide') 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. -- cgit v1.2.3-18-g5258 From bc5fb067852a2a0ae3de63d2d561e2b4010eb29a Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Thu, 29 Nov 2012 18:03:08 +0000 Subject: Documentation for lit: more formatting: use 'option' and 'program' directives. This enables cross-referencing and now '--' in option names are no more turned into en dashes. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168906 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CommandGuide/lit.rst | 283 +++++++++++++++++++++++----------------------- 1 file changed, 144 insertions(+), 139 deletions(-) (limited to 'docs/CommandGuide') diff --git a/docs/CommandGuide/lit.rst b/docs/CommandGuide/lit.rst index 00b5c070d4..1dcaff10bf 100644 --- a/docs/CommandGuide/lit.rst +++ b/docs/CommandGuide/lit.rst @@ -4,61 +4,62 @@ lit - LLVM Integrated Tester SYNOPSIS -------- -**lit** [*options*] [*tests*] +:program:`lit` [*options*] [*tests*] DESCRIPTION ----------- -**lit** is a portable tool for executing LLVM and Clang style test suites, -summarizing their results, and providing indication of failures. **lit** is -designed to be a lightweight testing tool with as simple a user interface as -possible. +: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** 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`). +: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 :ref:`test-status-results`). The **lit** program will -execute with a non-zero exit code if any tests fail. +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. -By default **lit** will use a succinct progress display and will only print -summary information for test failures. See :ref:`output-options` for options -controlling the **lit** progress display and output. +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. -**lit** also includes a number of options for controlling how tests are executed -(specific features may depend on the particular test format). See +: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. -Finally, **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. +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 **lit** architecture or designing a **lit** testing -implementation should see :ref:`lit-infrastructure`. +Users interested in the :program:`lit` architecture or designing a +:program:`lit` testing implementation should see :ref:`lit-infrastructure`. GENERAL OPTIONS --------------- -**-h**, **--help** +.. option:: -h, --help - Show the **lit** help message. + Show the :program:`lit` help message. -**-j** *N*, **--threads**\ =\ *N* +.. option:: -j N, --threads=N - Run *N* tests in parallel. By default, this is automatically chosen to match - the number of detected available CPUs. + Run ``N`` tests in parallel. By default, this is automatically chosen to + match the number of detected available CPUs. -**--config-prefix**\ =\ *NAME* +.. option:: --config-prefix=NAME - Search for *NAME.cfg* and *NAME.site.cfg* when searching for test suites, - instead of *lit.cfg* and *lit.site.cfg*. + 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`. -**--param** *NAME*, **--param** *NAME*\ =\ *VALUE* +.. option:: --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: @@ -66,20 +67,20 @@ GENERAL 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. @@ -88,79 +89,82 @@ OUTPUT OPTIONS EXECUTION OPTIONS ----------------- -**--path**\ =\ *PATH* +.. option:: --path=PATH - Specify an addition *PATH* to use when searching for executables in tests. + Specify an additional ``PATH`` to use when searching for executables in tests. -**--vg** +.. 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. + 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. + 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-arg**\ =\ *ARG* +.. option:: --vg-arg=ARG - When *--vg* is used, specify an additional argument to pass to valgrind itself. + When :option:`--vg` is used, specify an additional argument to pass to + :program:`valgrind` itself. -**--vg-leak** +.. option:: --vg-leak - 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, 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. -**--time-tests** +.. option:: --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 ----------------- -**--max-tests**\ =\ *N* +.. option:: --max-tests=N - Run at most *N* tests and then terminate. + Run at most ``N`` tests and then terminate. -**--max-time**\ =\ *N* +.. option:: --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 ------------------ -**--debug** +.. option:: --debug - Run **lit** in debug mode, for debugging configuration issues and **lit** itself. + Run :program:`lit` in debug mode, for debugging configuration issues and + :program:`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). -**--repeat**\ =\ *N* +.. option:: --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). @@ -169,28 +173,28 @@ error). TEST DISCOVERY -------------- -The inputs passed to **lit** can be either individual tests, or entire -directories or hierarchies of tests to run. When **lit** starts up, the first -thing it does is convert the inputs into a complete list of tests to run as part -of *test discovery*. +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*. -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: @@ -205,13 +209,13 @@ Each test ultimately produces one of the following six results: **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). @@ -221,16 +225,16 @@ Each test ultimately produces one of the following six results: **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 :ref:`output-options` +their status (generally only for failures). See the :ref:`output-options` section for more information. .. _lit-infrastructure: @@ -238,29 +242,29 @@ section for more information. LIT INFRASTRUCTURE ------------------ -This section describes the **lit** testing architecture for users interested in -creating a new **lit** testing implementation, or extending an existing one. +This section describes the :program:`lit` testing architecture for users interested in +creating a new :program:`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 :ref:`test-discovery`, tests are always located inside a *test -suite*. Test suites serve to define the format of the tests they contain, the +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** @@ -272,7 +276,7 @@ executed, two important global variables are predefined: **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: @@ -280,39 +284,39 @@ 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. @@ -320,41 +324,42 @@ executed, two important global variables are predefined: 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 +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 **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 :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. Each test result is expected to appear on a line that matches: @@ -363,7 +368,7 @@ Each test result is expected to appear on a line that matches: : () where ```` is a standard test result such as PASS, FAIL, XFAIL, -XPASS, UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and +XPASS, UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and REGRESSED are also allowed. The ```` field can consist of an arbitrary string containing no @@ -402,8 +407,8 @@ B, C, and D, and a log message for the failing test C: 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 -------- -- cgit v1.2.3-18-g5258 From dff966c9d847075c1f2ed5dd9382d492a90fbcc4 Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Thu, 29 Nov 2012 18:16:11 +0000 Subject: Documentation for llc: reformat. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168912 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CommandGuide/llc.rst | 176 +++++++++++++++------------------------------- 1 file changed, 56 insertions(+), 120 deletions(-) (limited to 'docs/CommandGuide') 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= Override the target triple specified in the input file with the specified string. - - -**-march**\ =\ *arch* +.. option:: -march= 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= 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= - -**--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= - -**--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= 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 -- cgit v1.2.3-18-g5258 From f03b5e947bb5e5ed2918b7102c29930da5f34ed9 Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Thu, 29 Nov 2012 19:02:50 +0000 Subject: Documentation for opt: reformat git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168919 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CommandGuide/opt.rst | 182 ++++++++++++++++++---------------------------- 1 file changed, 71 insertions(+), 111 deletions(-) (limited to 'docs/CommandGuide') 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 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 ar