taiki-e · bors · Sep 6, 2022 · Sep 6, 2022
diff --git a/Cargo.toml b/Cargo.toml
@@ -28,12 +28,12 @@ anyhow = "1.0.34"
 atty = "0.2.11"
 camino = "1.0.3"
 cargo_metadata = "0.14"
-clap = { version = "3.2.3", features = ["derive"] }
 duct = "0.13.1"
 fs-err = "2.5"
 glob = "0.3"
 home = "0.5"
 is_executable = "1"
+lexopt = "0.2"
 opener = "0.5"
 regex = { version = "1.3", default-features = false, features = ["perf", "std"] }
 rustc-demangle = "0.1.21"

diff --git a/README.md b/README.md
@@ -37,6 +37,8 @@ This is a wrapper around rustc [`-C instrument-coverage`][instrument-coverage] a
 <details>
 <summary>Click to show a complete list of options</summary>
 
+(See [docs](docs) directory for options of subcommands)
+
 <!-- readme-long-help:start -->
 ```console
 $ cargo llvm-cov --help
@@ -301,8 +303,6 @@ SUBCOMMANDS:
             Remove artifacts that cargo-llvm-cov has generated in the past
     nextest
             Run tests with cargo nextest
-    help
-            Print this message or the help of the given subcommand(s)
 ```
 <!-- readme-long-help:end -->
 
@@ -556,8 +556,8 @@ Note: AUR package is maintained by community, not maintainer of cargo-llvm-cov.
 
 - Branch coverage is not supported yet. See [#8] and [rust-lang/rust#79649] for more.
 - Support for doc tests is unstable and has known issues. See [#2] and [rust-lang/rust#79417] for more.
-- All the tests are run with `RUST_TEST_THREADS=1` to work around [rust-lang/rust#91092]. You can pass `--test-threads` (e.g., `--test-threads=$(nproc)`) to override this behavior.  
- 
+- All the tests are run with `RUST_TEST_THREADS=1` to work around [rust-lang/rust#91092]. You can pass `--test-threads` (e.g., `--test-threads=$(nproc)`) to override this behavior.
+
 See also [the code-coverage-related issues reported in rust-lang/rust](https://github.com/rust-lang/rust/labels/A-code-coverage).
 
 ## Related Projects
@@ -566,7 +566,6 @@ See also [the code-coverage-related issues reported in rust-lang/rust](https://g
 - [cargo-hack]: Cargo subcommand to provide various options useful for testing and continuous integration.
 - [cargo-minimal-versions]: Cargo subcommand for proper use of `-Z minimal-versions`.
 
-[#1]: https://github.com/taiki-e/cargo-llvm-cov/issues/1
 [#2]: https://github.com/taiki-e/cargo-llvm-cov/issues/2
 [#8]: https://github.com/taiki-e/cargo-llvm-cov/issues/8
 [#12]: https://github.com/taiki-e/cargo-llvm-cov/issues/12

diff --git a/docs/cargo-llvm-cov-clean.txt b/docs/cargo-llvm-cov-clean.txt
@@ -0,0 +1,16 @@
+cargo-llvm-cov-clean
+Remove artifacts that cargo-llvm-cov has generated in the past
+
+USAGE:
+    cargo llvm-cov clean [OPTIONS]
+
+OPTIONS:
+        --workspace               Remove artifacts that may affect the coverage results of packages
+                                  in the workspace
+    -v, --verbose                 Use verbose output
+        --color <WHEN>            Coloring [possible values: auto, always, never]
+        --manifest-path <PATH>    Path to Cargo.toml
+        --frozen                  Require Cargo.lock and cache are up to date
+        --locked                  Require Cargo.lock is up to date
+        --offline                 Run without accessing the network
+    -h, --help                    Print help information
diff --git a/docs/cargo-llvm-cov-nextest.txt b/docs/cargo-llvm-cov-nextest.txt
@@ -0,0 +1,9 @@
+cargo-llvm-cov-nextest
+Run tests with cargo nextest
+
+USAGE:
+    cargo llvm-cov nextest [OPTIONS] [NEXTEST_OPTIONS]
+
+ARGS:
+    [OPTIONS]          Options for cargo-llvm-cov; For more information try `cargo llvm-cov --help`
+    [NEXTEST_OPTIONS]  Options for cargo-nextest; For more information try `cargo nextest run --help`
diff --git a/tests/short-help.txt → docs/cargo-llvm-cov-run.txt b/tests/short-help.txt → docs/cargo-llvm-cov-run.txt
@@ -1,39 +1,69 @@
-cargo-llvm-cov
-Cargo subcommand to easily use LLVM source-based code coverage (-C instrument-coverage).
-
-Use -h for short descriptions and --help for more details.
+cargo-llvm-cov-run
+Run a binary or example and generate coverage report
 
 USAGE:
-    cargo llvm-cov [OPTIONS] [-- <ARGS>...] [SUBCOMMAND]
+    cargo llvm-cov run [OPTIONS] [-- <ARGS>...]
 
 ARGS:
-    <ARGS>...    Arguments for the test binary
+    <ARGS>...
+            Arguments for the test binary
 
 OPTIONS:
         --json
             Export coverage data in "json" format
 
+            If --output-path is not specified, the report will be printed to stdout.
+
+            This internally calls `llvm-cov export -format=text`. See
+            <https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-export> for more.
+
         --lcov
             Export coverage data in "lcov" format
 
+            If --output-path is not specified, the report will be printed to stdout.
+
+            This internally calls `llvm-cov export -format=lcov`. See
+            <https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-export> for more.
+
         --text
             Generate coverage report in “text” format
 
+            If --output-path or --output-dir is not specified, the report will be printed to stdout.
+
+            This internally calls `llvm-cov show -format=text`. See
+            <https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-show> for more.
+
         --html
             Generate coverage report in "html" format
 
+            If --output-dir is not specified, the report will be generated in `target/llvm-cov/html`
+            directory.
+
+            This internally calls `llvm-cov show -format=html`. See
+            <https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-show> for more.
+
         --open
             Generate coverage reports in "html" format and open them in a browser after the
-            operation
+            operation.
+
+            See --html for more.
 
         --summary-only
             Export only summary information for each file in the coverage data
 
+            This flag can only be used together with either --json or --lcov.
+
         --output-path <PATH>
-            Specify a file to write coverage data into
+            Specify a file to write coverage data into.
+
+            This flag can only be used together with --json, --lcov, or --text. See --output-dir for
+            --html and --open.
 
         --output-dir <DIRECTORY>
-            Specify a directory to write coverage report into (default to `target/llvm-cov`)
+            Specify a directory to write coverage report into (default to `target/llvm-cov`).
+
+            This flag can only be used together with --text, --html, or --open. See also
+            --output-path.
 
         --failure-mode <any|all>
             Fail if `any` or `all` profiles cannot be merged (default to `any`)
@@ -72,68 +102,17 @@ OPTIONS:
         --include-build-script
             Include build script in coverage report
 
-        --doctests
-            Including doc tests (unstable)
-
-        --no-run
-            Generate coverage report without running tests
-
-        --no-fail-fast
-            Run all tests regardless of failure
-
-        --ignore-run-fail
-            Run all tests regardless of failure and generate report
-
     -q, --quiet
-            Display one character per test instead of one line
-
-        --lib
-            Test only this package's library unit tests
+            No output printed to stdout
 
         --bin <NAME>
-            Test only the specified binary
-
-        --bins
-            Test all binaries
+            Name of the bin target to run
 
         --example <NAME>
-            Test only the specified example
-
-        --examples
-            Test all examples
-
-        --test <NAME>
-            Test only the specified test target
-
-        --tests
-            Test all tests
-
-        --bench <NAME>
-            Test only the specified bench target
-
-        --benches
-            Test all benches
-
-        --all-targets
-            Test all targets
-
-        --doc
-            Test only this library's documentation (unstable)
+            Name of the example target to run
 
     -p, --package <SPEC>
-            Package to run tests for
-
-        --workspace
-            Test all packages in the workspace [aliases: all]
-
-        --exclude <SPEC>
-            Exclude packages from both the test and report
-
-        --exclude-from-test <SPEC>
-            Exclude packages from the test (but not from the report)
-
-        --exclude-from-report <SPEC>
-            Exclude packages from the report (but not from the test)
+            Package with the target to run
 
     -j, --jobs <N>
             Number of parallel jobs, defaults to # of CPUs
@@ -156,21 +135,37 @@ OPTIONS:
         --target <TRIPLE>
             Build for the target triple
 
+            When this option is used, coverage for proc-macro and build script will not be displayed
+            because cargo does not pass RUSTFLAGS to them.
+
         --coverage-target-only
             Activate coverage reporting only for the target triple
 
+            Activate coverage reporting only for the target triple specified via `--target`. This is
+            important, if the project uses multiple targets via the cargo bindeps feature, and not
+            all targets can use `instrument-coverage`, e.g. a microkernel, or an embedded binary.
+
     -v, --verbose
             Use verbose output
 
+            Use -vv (-vvv) to propagate verbosity to cargo.
+
         --color <WHEN>
-            Coloring [possible values: auto, always, never]
+            Coloring
+
+            [possible values: auto, always, never]
 
         --remap-path-prefix
             Use --remap-path-prefix for workspace root
 
+            Note that this does not fully compatible with doctest.
+
         --include-ffi
             Include coverage of C/C++ code linked to Rust library/binary
 
+            Note that `CC`/`CXX`/`LLVM_COV`/`LLVM_PROFDATA` environment variables must be set to
+            Clang/LLVM compatible with the LLVM version used in rustc.
+
         --manifest-path <PATH>
             Path to Cargo.toml
 
@@ -188,13 +183,3 @@ OPTIONS:
 
     -h, --help
             Print help information
-
-    -V, --version
-            Print version information
-
-SUBCOMMANDS:
-    run         Run a binary or example and generate coverage report
-    show-env    Output the environment set by cargo-llvm-cov to build Rust projects
-    clean       Remove artifacts that cargo-llvm-cov has generated in the past
-    nextest     Run tests with cargo nextest
-    help        Print this message or the help of the given subcommand(s)
diff --git a/docs/cargo-llvm-cov-show-env.txt b/docs/cargo-llvm-cov-show-env.txt
@@ -0,0 +1,10 @@
+cargo-llvm-cov-show-env
+Output the environment set by cargo-llvm-cov to build Rust projects
+
+USAGE:
+    cargo llvm-cov show-env [OPTIONS]
+
+OPTIONS:
+        --export-prefix    Prepend "export " to each line, so that the output is suitable to be
+                           sourced by bash
+    -h, --help             Print help information
diff --git a/tests/long-help.txt → docs/cargo-llvm-cov.txt b/tests/long-help.txt → docs/cargo-llvm-cov.txt
@@ -259,5 +259,3 @@ SUBCOMMANDS:
             Remove artifacts that cargo-llvm-cov has generated in the past
     nextest
             Run tests with cargo nextest
-    help
-            Print this message or the help of the given subcommand(s)