84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
|
# libcudacxx Test
|
||
|
|
|
||
|
|
## Organization
|
||
|
|
|
||
|
|
- Put CUDA Standard Library tests under `libcudacxx/test/libcudacxx/std/...`.
|
||
|
|
- Put CUDA-specific API tests under `libcudacxx/test/libcudacxx/cuda/...`, unless an adjacent `std/...` directory is clearly the established home for the functionality.
|
||
|
|
- Read nearby tests first and mirror their directory layout, file names, helper types, includes, and lit gates.
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
|
||
|
|
- Validate libcudacxx functionality. It is fundamental to verify:
|
||
|
|
|
||
|
|
- Edge cases.
|
||
|
|
- Input and output types.
|
||
|
|
- Exception behavior.
|
||
|
|
- Runtime and constant-evaluation behavior.
|
||
|
|
- Device and host behavior.
|
||
|
|
|
||
|
|
## Test kinds
|
||
|
|
|
||
|
|
- `.pass.cpp`: compiles, links, runs, and returns 0.
|
||
|
|
- `.compile.pass.cpp`: compiles correctly.
|
||
|
|
- `.fail.cpp`: must fail compilation. Prefer precise `expected-error`, `expected-warning`, `expected-note`, or `expected-no-diagnostics` annotations when clang verify is supported.
|
||
|
|
- `.runfail.cpp`: compiles and runs but must return non-zero.
|
||
|
|
|
||
|
|
## Test structure
|
||
|
|
|
||
|
|
- All tests must have the correct license banner.
|
||
|
|
- Always include top level headers, never internal ones with `__` prefix.
|
||
|
|
- Include support headers `"test_macros.h"`, `"test_iterators.h"`, `"test_comparisons.h"`, when needed.
|
||
|
|
- Use `static_assert(...)` for compile-time guarantees and constexpr coverage.
|
||
|
|
- Use `<cuda/std/cassert>` and `assert(...)` for runtime checks.
|
||
|
|
- The `main` function must be present, dispatch runtime and static-evaluation tests, and return 0.
|
||
|
|
|
||
|
|
## Style
|
||
|
|
|
||
|
|
- Use `cuda::std` names, not `std::` names, unless the test is intentionally checking interoperability with host standard library types.
|
||
|
|
- Do not fully qualify names in header includes unless the test is intentionally checking interoperability with host standard library types.
|
||
|
|
- Mark helper functions that may run on host and device with `TEST_FUNC`; use `TEST_DEVICE_FUNC` for device-only helpers.
|
||
|
|
use `TEST_TILE_FUNC` for tile only helpers and `TEST_TILE_DEVICE_FUNC` for functions that can run on tile and device
|
||
|
|
- `const`-qualification is discouraged.
|
||
|
|
- Don't use `noexcept` for helper functions unless strictly necessary.
|
||
|
|
- Do not use lambda expressions in host/device test code unless nearby tests already prove the pattern is supported.
|
||
|
|
|
||
|
|
## Portability
|
||
|
|
|
||
|
|
- Guard host-only or device-only behavior with `NV_IF_TARGET(NV_IS_HOST, (...))` and `NV_IF_TARGET(NV_IS_DEVICE, (...))` respectively.
|
||
|
|
- Use `TEST_STD_VER`, `TEST_COMPILER`, `TEST_CUDA_COMPILER`, `TEST_HAS_EXCEPTIONS`, and `TEST_THROW` from `"test_macros.h"` instead of spelling compiler or dialect probes directly.
|
||
|
|
- Unsupported platforms can be disabled with `UNSUPPORTED: <feature-name>` or `XFAIL: <feature-name>` lit directives. Some common feature names are `nvrtc`, `enable-tile`, `pre-sm-70`, `c++17`, `c++20`, `msvc`, `gcc-<version>`, or `clang-<version>`.
|
||
|
|
|
||
|
|
- Always motivate unsupported features with a comment.
|
||
|
|
|
||
|
|
## Lit directives
|
||
|
|
|
||
|
|
- Put lit directives near the top of the file before includes.
|
||
|
|
- Common directives: `UNSUPPORTED:`, `XFAIL:`, `REQUIRES:`, `ADDITIONAL_COMPILE_DEFINITIONS:`, `ADDITIONAL_COMPILE_OPTIONS_HOST:`, `ADDITIONAL_COMPILE_OPTIONS_CUDA:`, `MODULES_DEFINES:`, and `CONSTEXPR_STEPS:`.
|
||
|
|
- For diagnostics in `.fail.cpp`, annotate the exact line that should fail when possible:
|
||
|
|
|
||
|
|
```cpp
|
||
|
|
bad_expression(); // expected-error {{message fragment}}
|
||
|
|
```
|
||
|
|
|
||
|
|
- Prefer checking the intended diagnostic over accepting any compile failure.
|
||
|
|
|
||
|
|
## Validation
|
||
|
|
|
||
|
|
Use targeted libcudacxx lit runs. Paths passed to `--lit-precompile-tests` and `--lit-tests` are relative to `libcudacxx/test/libcudacxx/`.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
ci/util/build_and_test_targets.sh \
|
||
|
|
--preset libcudacxx \
|
||
|
|
--lit-precompile-tests "std/algorithms/alg.nonmodifying/alg.any_of/any_of.pass.cpp" \
|
||
|
|
--lit-tests "std/algorithms/alg.nonmodifying/alg.any_of/any_of.pass.cpp"
|
||
|
|
```
|
||
|
|
|
||
|
|
If running lit directly, use the configured site file:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
LIBCUDACXX_SITE_CONFIG=<path-to-cccl>/build/<preset>/libcudacxx/test/libcudacxx/lit.site.cfg \
|
||
|
|
lit -v libcudacxx/test/libcudacxx/<relative-test-path>
|
||
|
|
```
|
||
|
|
|
||
|
|
- Use `-Dexecutor=NoopExecutor()` for precompile-only validation when runtime execution is unavailable or GPU coverage is not required.
|