project_6/cccl_upstream/.agent/skills/cccl-test/references/libcudacxx.md

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:

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/.

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:

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.