[llvm] a8398bd - [llvm][docs] Update list of llvm-lit options
David Spickett via llvm-commits
llvm-commits at lists.llvm.org
Tue Oct 29 03:36:01 PDT 2024
Author: David Spickett
Date: 2024-10-29T10:35:27Z
New Revision: a8398bd81770a2801ec083fd2cd8a19140fe92a9
URL: https://github.com/llvm/llvm-project/commit/a8398bd81770a2801ec083fd2cd8a19140fe92a9
DIFF: https://github.com/llvm/llvm-project/commit/a8398bd81770a2801ec083fd2cd8a19140fe92a9.diff
LOG: [llvm][docs] Update list of llvm-lit options
Fixes #62899
In this commit I have updated the list of options
to include any missing options and re-rordered
some of them to match the order in lit's --help.
Where there was a larger description in this document
I've used that instead of the --help description.
This *does not* include --use-unique-output-file-name
as this was only added recently and we are still
debating whether it will be kept.
Added:
Modified:
llvm/docs/CommandGuide/lit.rst
Removed:
################################################################################
diff --git a/llvm/docs/CommandGuide/lit.rst b/llvm/docs/CommandGuide/lit.rst
index bd1cfbbade511f..af8a1a08be535d 100644
--- a/llvm/docs/CommandGuide/lit.rst
+++ b/llvm/docs/CommandGuide/lit.rst
@@ -57,7 +57,11 @@ GENERAL OPTIONS
.. option:: -h, --help
- Show the :program:`lit` help message.
+ Show the :program:`lit` help message and exit.
+
+.. option:: --version
+
+ Show :program:`lit`'s version number and exit.
.. option:: -j N, --workers=N
@@ -108,23 +112,51 @@ OUTPUT OPTIONS
Enable -v, but for all tests not just failed tests.
+.. option:: -o PATH, --output PATH
+
+ Write test results to the provided path.
+
.. option:: --no-progress-bar
Do not use curses based progress bar.
+.. option:: --show-excluded
+
+ Show excluded tests.
+
+.. option:: --show-skipped
+
+ Show skipped tests.
+
.. option:: --show-unsupported
- Show the names of unsupported tests.
+ Show unsupported tests.
+
+.. option:: --show-pass
+
+ Show passed tests.
+
+.. option:: --show-flakypass
+
+ Show passed with retry tests.
.. option:: --show-xfail
- Show the names of tests that were expected to fail.
+ Show expectedly failed tests.
.. _execution-options:
EXECUTION OPTIONS
-----------------
+.. option:: --gtest-sharding
+
+ Enable sharding for GoogleTest format.
+
+.. option:: --no-gtest-sharding
+
+ Disable sharding for GoogleTest format.
+
.. option:: --path=PATH
Specify an additional ``PATH`` to use when searching for executables in tests.
@@ -139,11 +171,6 @@ EXECUTION OPTIONS
"``valgrind``" feature that can be used to conditionally disable (or expect
failure in) certain tests.
-.. option:: --vg-arg=ARG
-
- 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
@@ -151,9 +178,59 @@ EXECUTION OPTIONS
feature that can be used to conditionally disable (or expect failure in)
certain tests.
+.. option:: --vg-arg=ARG
+
+ When :option:`--vg` is used, specify an additional argument to pass to
+ :program:`valgrind` itself.
+
+.. option:: --no-execute
+
+ Don't execute any tests (assume that they pass).
+
+.. option:: --xunit-xml-output XUNIT_XML_OUTPUT
+
+ Write XUnit-compatible XML test reports to the specified file.
+
+.. option:: --resultdb-output RESULTDB_OUTPUT
+
+ Write LuCI ResultDB compatible JSON to the specified file.
+
+.. option:: --time-trace-output TIME_TRACE_OUTPUT
+
+ Write Chrome tracing compatible JSON to the specified file
+
+.. option:: --timeout MAXINDIVIDUALTESTTIME
+
+ Maximum time to spend running a single test (in seconds). 0 means no time
+ limit. [Default: 0]
+
+.. option:: --timeout=N
+
+ Spend at most ``N`` seconds (approximately) running each individual test.
+ ``0`` means no time limit, and ``0`` is the default. Note that this is not an
+ alias for :option:`--max-time`; the two are
diff erent kinds of maximums.
+
+.. option:: --max-failures MAX_FAILURES
+
+ Stop execution after the given number of failures.
+
+.. option:: --allow-empty-runs
+
+ Do not fail the run if all tests are filtered out.
+
+.. option:: --per-test-coverage
+
+ Emit the necessary test coverage data, divided per test case (involves
+ setting a unique value to LLVM_PROFILE_FILE for each RUN). The coverage
+ data files will be emitted in the directory specified by ``config.test_exec_root``.
+
+.. option:: --ignore-fail
+
+ Exit with status zero even if some tests fail.
+
.. option:: --skip-test-time-recording
- Disable tracking the wall time individual tests take to execute.
+ Do not track elapsed wall time for each test.
.. option:: --time-tests
@@ -161,10 +238,6 @@ EXECUTION OPTIONS
in the summary output. This is useful for determining which tests in a test
suite take the most time to execute.
-.. option:: --ignore-fail
-
- Exit with status zero even if some tests fail.
-
.. _selection-options:
SELECTION OPTIONS
@@ -178,23 +251,6 @@ The timing data is stored in the `test_exec_root` in a file named
`.lit_test_times.txt`. If this file does not exist, then `lit` checks the
`test_source_root` for the file to optionally accelerate clean builds.
-.. option:: --shuffle
-
- Run the tests in a random order, not failing/slowest first. Deprecated,
- use :option:`--order` instead.
-
-.. option:: --per-test-coverage
-
- Emit the necessary test coverage data, divided per test case (involves
- setting a unique value to LLVM_PROFILE_FILE for each RUN). The coverage
- data files will be emitted in the directory specified by `config.test_exec_root`.
-
-.. option:: --max-failures N
-
- Stop execution after the given number ``N`` of failures.
- An integer argument should be passed on the command line
- prior to execution.
-
.. option:: --max-tests=N
Run at most ``N`` tests and then terminate.
@@ -205,16 +261,6 @@ The timing data is stored in the `test_exec_root` in a file named
Note that this is not an alias for :option:`--timeout`; the two are
diff erent kinds of maximums.
-.. option:: --num-shards=M
-
- Divide the set of selected tests into ``M`` equal-sized subsets or
- "shards", and run only one of them. Must be used with the
- ``--run-shard=N`` option, which selects the shard to run. The environment
- variable ``LIT_NUM_SHARDS`` can also be used in place of this
- option. These two options provide a coarse mechanism for partitioning large
- testsuites, for parallel execution on separate machines (say in a large
- testing farm).
-
.. option:: --order={lexical,random,smart}
Define the order in which tests are run. The supported values are:
@@ -228,18 +274,14 @@ The timing data is stored in the `test_exec_root` in a file named
tests, all in descending execution time order. This is the default as it
optimizes concurrency.
-.. option:: --run-shard=N
+.. option:: --shuffle
- Select which shard to run, assuming the ``--num-shards=M`` option was
- provided. The two options must be used together, and the value of ``N``
- must be in the range ``1..M``. The environment variable
- ``LIT_RUN_SHARD`` can also be used in place of this option.
+ Run the tests in a random order, not failing/slowest first. Deprecated,
+ use :option:`--order` instead.
-.. option:: --timeout=N
+.. option:: -i, --incremental
- Spend at most ``N`` seconds (approximately) running each individual test.
- ``0`` means no time limit, and ``0`` is the default. Note that this is not an
- alias for :option:`--max-time`; the two are
diff erent kinds of maximums.
+ Run failed tests first (DEPRECATED: use ``--order=smart``).
.. option:: --filter=REGEXP
@@ -297,6 +339,23 @@ The timing data is stored in the `test_exec_root` in a file named
primary purpose is to suppress an ``XPASS`` result without modifying a test
case that uses the ``XFAIL`` directive.
+.. option:: --num-shards=M
+
+ Divide the set of selected tests into ``M`` equal-sized subsets or
+ "shards", and run only one of them. Must be used with the
+ ``--run-shard=N`` option, which selects the shard to run. The environment
+ variable ``LIT_NUM_SHARDS`` can also be used in place of this
+ option. These two options provide a coarse mechanism for partitioning large
+ testsuites, for parallel execution on separate machines (say in a large
+ testing farm).
+
+.. option:: --run-shard=N
+
+ Select which shard to run, assuming the ``--num-shards=M`` option was
+ provided. The two options must be used together, and the value of ``N``
+ must be in the range ``1..M``. The environment variable
+ ``LIT_RUN_SHARD`` can also be used in place of this option.
+
ADDITIONAL OPTIONS
------------------
@@ -313,6 +372,11 @@ ADDITIONAL OPTIONS
List all of the discovered tests and exit.
+.. option:: --show-used-features
+
+ Show all features used in the test suite (in ``XFAIL``, ``UNSUPPORTED`` and
+ ``REQUIRES``) and exit.
+
EXIT STATUS
-----------
More information about the llvm-commits
mailing list