NVIDIA / NVIDIA/cccl

[DOC]: libcudacxx test `lit` modifiers

Open
#6,556 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.