[DOC]: libcudacxx test `lit` modifiers
- Dominant language
- C++
- Stars
- 2.5k
- Forks
- 486
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 295
Description
### Is this a duplicate?
- [x] I confirmed there appear to be no [duplicate issues](https://github.com/NVIDIA/cccl/issues) for this bug and that I agree to the [Code of Conduct](CODE_OF_CONDUCT.md)
### Is this for new documentation, or an update to existing docs?
New
### Describe the incorrect/future/missing documentation
Libcudacxx's lit tests contain in-source metadata annotations that are used to control compilation / test execution / etc. These appear to be of the form:
```cpp
// KEYWORD_WITHOUT_ARGS.
// KEYWORD_WITH_ARGS: foo bar baz
```
These don't appear to be documented anywhere.
-----
I extracted lines matching these patterns using `ripgrep` in an attempt to understand their behavior and made my best guesses below. I also included some unused annotations I found in [here](https://github.com/NVIDIA/cccl/blob/main/libcudacxx/test/utils/libcudacxx/test/format.py#L47-L65).
```bash
# Detect used lit modifiers:
rg "^\s*//\s*([A-Z_]+[:.].*)\$" -r \$1 --no-filename --no-line-number | sort | uniq
```
## Observed modifiers
`ADDITIONAL_COMPILE_DEFINITIONS: `
- Adds definitions to compiler invocation.
- Currently only used to add a single definition per use.
- Need to check whether multiple defs in one line are allowed.
`ADDITIONAL_COMPILE_OPTIONS_CUDA: `
- Checks if the option is supported by detected CUDA compiler, adds it if so.
- Currently unused. Unsure if multiple options are supported, need to check.
`ADDITIONAL_COMPILE_OPTIONS_HOST: `
- Checks if the option is supported by detected CXX compiler, adds it if so.
- Wraps in `-Xcompiler=` for nvcc if needed.
- Currently only used to add a single definition per use.
- Unsure if multiple options are supported, need to check.
`CONSTEXPR_STEPS: N`
- Sets a compiler flag increasing the limit of constexpr steps.
- Flag varies across compilers.
`FLAKY_TEST.`
- Currently unused.
- Implementation retries test up to 3x on failure.
- Probably can be dropped, code smell.
`FORCE_ALL_WARNINGS.`
- Used once; enables a specific set of warning flags.
`MODULES_DEFINES: _LIBCUDACXX_TESTING_FALLBACK_IS_CONSTRUCTIBLE`
- Unclear what the difference is between this and ADDITIONAL_COMPILE_DEFINITIONS
- Only used once with indicated argument.
`REQUIRES: [ || REQ... ]`
- Skips test if requirements aren't met.
- Multiple reqs supported with `||` combinations.
- `&&` not used, need to check if that's supported.
- `()` grouping not used, need to check if that's supported.
- Currently used `REQ`s are:
- `c++XX` -- C++ standard dialect. 98, 03, 11, 14, 17 are currently in use.
- `clang` -- unsure if other compilers are implemented.
- `has-unix-headers` -- Used once, can't find an implementation for this.
- `libatomic` -- adds `-latomic` to flags
- `long_tests` -- Appears to label expensive tests to allow toggling. Used twice.
- `template-cost-testing` / `template-const-testing`
- One is clearly a typo.
- Only appears in libcxx 'stress' tests.
- No implementation/handler found, unsure what the purpose is.
- `verify-support` -- Something about invoking `clang -verify`. Unclear if we need it.
- `diagnose-if-support` -- used once; unclear; no handler found.
`RUN: `
- Command may span multiple lines all prefixed with `RUN:` if trailing `\` are used.
- Supports a variety of special keywords in command string.
- %run %build %cxx %flags %compile_flags %link_flags %s %S %t
- No handler found; not sure this is actually used by our lit implementation.
`UNSUPPORTED: [ , ]...`
- Appears to be inverse of `REQUIRES`.
- `expr` is a boolean combination of features. Observed syntax:
- `!expr` for inversion
- `(!expr)` used for inverting a single feature, unclear how well supported `()` grouping is.
- `&&` combines multiple requirements (e.g. `clang && !nvcc`). `||` is not observed.
- Multiple independent features observed separated by `, ` (e.g. `clang-14, gcc-7, msvc-19.29`)
- Observed features:
- `[-]` -- Compiler with optional version. Observed compilers:
- `nvrtc` with no versioning
- `clang` with `X.Y` versioning, `X` versioning, and no versioning.
- `gcc` with `X.Y` versioning, `X` versioning, and no versioning.
- `msvc` with `XX.YY` versioning, `XX` versioning, and no versioning. (`XX` is 19, not 14)
- `nvcc` with `XX.Y` versioning, `XX` versioning, and no versioning.
- `nvhpc` with `XX.Y` versioning and no versioning.
- `c++XX` -- C++ standard dialect. Observed: 98, 03, 11, 14, 17, 20
- `pre-sm-XX` -- Disabled on CUDA archs < smXX. Observed 60, 70, 80, 90.
- `windows` -- Presumably equivalent to `msvc` for our purposes?
- `aarch64-unknown-linux-gnu` -- Presumably ARM64 + linux.
- `true` -- Presumable disables the test in all situations.
- `asan` -- Address sanitizer? I don't think we support that with lit currently.
- Misc specific features, obvious:
- `no-exceptions`
- `stdlib=libstdc++`
- Misc specific features, unclear when these apply or what they mean:
- `LIBCUDACXX-has-no-concepts`
- `LIBCUDACXX-has-no-incomplete-ranges`
- `libcpp-has-debug-mode`
- `libcpp-has-no-incomplete-pstl`
- `libcpp-has-no-threads`
- `libcpp-no-deduction-guides`
- `libcpp-no-exceptions`
- `no-localization`
- `no_execute`
- `sanitizer-new-delete`
`XFAIL: [ , ]...`
- Test is expected to fail (at runtime? compile time?)
- Appears to support the same logic, syntax, and features as `UNSUPPORTED`.
- features observed here but not in `UNSUPPORTED`:
- `*`
- `LIBCXX-WINDOWS-FIXME`
- `dylib-has-no-filesystem`
### If this is a correction, please provide a link to the incorrect documentation. If this is a new documentation request, please link to where you have looked.
Just greppin'.
Contributor guide
Assessment
This issue has not been assessed yet.