feat(cccl): integrate missing CCCL directories — python/, ci/, .agent/, docs/, test/
Sparse-checkout from NVIDIA/cccl main branch to complete cccl_upstream: Added: - python/cuda_cccl/ (226 files) — Python bindings for device-level algorithms Critical for muh toolchain: cuda.compute.reduce_into, scan, radix_sort, etc. Includes 204 .py files with full test coverage for all 27 algorithms - ci/ (163 files) — Build/test infrastructure build_cub.sh, test_cub.sh, build_and_test_targets.sh, matrix.yaml Directly maps to our [INFRA-CI] and [INFRA-BUILD] items - .agent/skills/ (7 files) — NVIDIA's own agent skills for CCCL cccl-style/SKILL.md, cccl-test/SKILL.md, sass-diff/SKILL.md - docs/ (491 files) — Official CCCL documentation CI references, CMake guides, Python compute docs, libcudacxx PTX docs - test/ (12 files) — Top-level integration tests (cuda_smoke, stdpar) - Root configs: .clang-format, .clang-tidy, CONTRIBUTING.md, pyproject.toml - CLAUDE.md symlink → AGENTS.md (NVIDIA's standard) cccl_upstream now mirrors full NVIDIA/cccl structure: Before: 42M (cub + thrust + libcudacxx + cudax + c + examples + benchmarks) After: 53M (+python +ci +docs +.agent +test +configs) This completes the CCCL base needed for: - [muh-bench] items: ci/util/build_and_test_targets.sh for targeted builds - [CCCL-verify] items: python/cuda_cccl/tests/ as reference implementations - [CCCL-test] items: ci/test_cub.sh, ci/test_thrust.sh - Agent workflow: .agent/skills/ for consistent style and test patterns
This commit is contained in:
muh-bot
14
cccl_upstream/.agent/skills/cccl-style/SKILL.md
Normal file
14
cccl_upstream/.agent/skills/cccl-style/SKILL.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: cccl-style
|
||||
description: Use when editing or reviewing CCCL code for style conventions; read common CCCL guidance and the path-specific references named by this skill.
|
||||
---
|
||||
|
||||
# CCCL Style
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Read `references/common.md` for guidance that applies across CCCL.
|
||||
2. For `libcudacxx/include/**/*`, also read `references/libcudacxx.md`.
|
||||
3. For `cudax/include/**/*`, also read `references/libcudacxx.md`.
|
||||
4. If no path-specific reference exists, follow nearby code and repository docs. Do not import rules from another subproject.
|
||||
5. Apply each reference only to its stated scope. Rules for one CCCL subproject do not automatically apply to another.
|
||||
70
cccl_upstream/.agent/skills/cccl-style/references/common.md
Normal file
70
cccl_upstream/.agent/skills/cccl-style/references/common.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# Common CCCL Style Guidance
|
||||
|
||||
Apply this guidance across CCCL unless a path-specific style reference says otherwise.
|
||||
|
||||
## Naming Style
|
||||
|
||||
- Macros: macro style, e.g. `MY_MACRO`.
|
||||
- Template parameters: PascalCase, e.g. `MyParameter`.
|
||||
- All other symbols: snake style, e.g. `my_variable`. The one exception is the CUB public API, which uses PascalCase.
|
||||
|
||||
## Variables
|
||||
|
||||
- All variables that are not modified must use `const`. This includes variables initialized by casts (`static_cast`, `reinterpret_cast`, `bit_cast`), function return values, and loop-invariant computations.
|
||||
- All variables that can be evaluated at compile-time must use `constexpr`.
|
||||
- All `constexpr` variables at namespace/global scope must use `inline`, including variable templates.
|
||||
- Consider using plural names for array, span, list, e.g. `int values[4]` instead of `int value[4]`.
|
||||
- Use uniform initialization for class constructors (not enforced to builtin types) and compile-time conversions, e.g. `constexpr auto x = int{sizeof(float)};`.
|
||||
|
||||
## Headers
|
||||
|
||||
- Files must include all headers related to the symbols that they are using.
|
||||
- Relying on transitive header inclusion is not allowed.
|
||||
- Unneeded headers must be removed.
|
||||
- All headers must have the correct license. This also applies to source files.
|
||||
- All header inclusions must use the syntax `<header>`.
|
||||
- Use forward declaration, namely `__fwd/header.h` or direct type declaration, when possible instead of including the implementation header.
|
||||
- Headers should be the most precise available, e.g. `#include <cuda/std/__type_traits/is_array.h>`.
|
||||
- Do not include headers in `cuda/std/__cccl/` directly; they are provided by `__config` or the prologue/epilogue mechanism.
|
||||
|
||||
## Functions
|
||||
|
||||
- Functions must be marked `_CCCL_HOST_API`, `_CCCL_DEVICE_API`, `_CCCL_HOST_DEVICE_API`, `_CCCL_TILE_API`, or `_CCCL_API`.
|
||||
- Non-template, non-`constexpr` functions must use `inline`.
|
||||
- Most functions with a non-void return type should use `[[nodiscard]]`; functions with known side effects may be exceptions.
|
||||
- Functions that do not throw exceptions must use `noexcept`.
|
||||
- Use `_CCCL_CONSTEVAL` when the function can only be evaluated at compile time.
|
||||
- Use C++20 concept macros instead of SFINAE, e.g. `_CCCL_TEMPLATE(...)` and `_CCCL_REQUIRES(...)`.
|
||||
|
||||
## Function Calls And Types
|
||||
|
||||
- In headers, apply global qualification where the subproject requires it:
|
||||
- libcudacxx and cudax require free function calls to be fully qualified from the global namespace, e.g. `::cuda::ceil_div(...)`.
|
||||
- CUB applies this rule only to calls to symbols under the `::cuda` namespace hierarchy; otherwise follow existing CUB qualification style.
|
||||
- Thrust uses leading `::` for many symbols under the `::cuda` namespace hierarchy, but relies on ADL in many places and the blanket free-function qualification rule does not apply to those calls.
|
||||
- For covered calls, this includes calls to functions defined in the same namespace, e.g. inside `cuda::`, call `::cuda::ceil_div(...)`, not `ceil_div(...)`. This does not apply to (static) member functions of classes. The only exceptions for covered calls are functions that are supposed to be found through argument-dependent lookup (ADL), such as `::cuda::std::swap` and `::cuda::std::get`. Those functions can be called unqualified with a preceding `using ::cuda::std::get;`.
|
||||
- This global-qualification rule does not apply to source files such as tests and benchmarks.
|
||||
- In headers, apply type-name qualification where the subproject requires it:
|
||||
- libcudacxx and cudax require type names to be fully qualified except when they are already declared in the current namespace or an enclosing one. Outside those namespaces, fully qualify `cuda::std` and standard integer type aliases such as `::cuda::std::size_t`.
|
||||
- CUB applies this rule only to type names under the `::cuda` namespace hierarchy. Do not apply the libcudacxx/cudax blanket type-qualification rule to CUB namespaces or `detail` namespaces.
|
||||
- Thrust does not apply the libcudacxx/cudax blanket type-qualification rule. It uses leading `::` for many `::cuda` and `::cuda::std` type names, but also uses Thrust namespace patterns; follow neighboring Thrust code.
|
||||
- A local `using` declaration, e.g. `using ::cuda::std::size_t;`, is acceptable to avoid repetition within a function body.
|
||||
- Static member functions of a class template inherit the class's namespace.
|
||||
|
||||
## Comments
|
||||
|
||||
- Commented code without a description is not allowed.
|
||||
|
||||
## General Guidelines
|
||||
|
||||
- The code must reuse `cuda/` or `cuda/std` functionalities as much as possible, including macros.
|
||||
- Try to use modern C++ as much as possible. The repository supports C++17 but many more recent functionalities have been backported with functions and macros.
|
||||
|
||||
## Prevent Compiler Errors And Improve Compatibility
|
||||
|
||||
- Remove unused code, variables, functions, types, template parameters, headers, etc.
|
||||
- Variables that are unsigned, or that can become unsigned after template instantiation, must not check for negative values directly. Use `cuda::std::is_unsigned_v<T> ? false : (var < 0)` instead.
|
||||
|
||||
## Compiler Compatibility
|
||||
|
||||
- Protect host-only code with `#if !_CCCL_COMPILER(NVRTC)`.
|
||||
@@ -0,0 +1,55 @@
|
||||
# libcudacxx Style Guidance
|
||||
|
||||
Use this reference for `libcudacxx/include/**/*` and `cudax/include/**/*`.
|
||||
|
||||
## Naming Style
|
||||
|
||||
All non-public symbols must be C++ reserved identifiers:
|
||||
|
||||
- `_` for macros and template parameters, e.g. `_MY_MACRO`, `_MyParameter`.
|
||||
- `__` for all other symbols, e.g. `__my_variable`.
|
||||
- Never use reserved keywords, such as `__in`, `__out`, or `__inout` as variables, parameters, or function names.
|
||||
- Avoid single-letter template parameter names. Wrong: `_T`; correct: `_Tp`.
|
||||
|
||||
## Class / Struct
|
||||
|
||||
- Data member names have postfix `_`, e.g. `class __myclass { int __data_; };`.
|
||||
- Constructor parameter names should match class/struct data member names without the postfix `_`, e.g. `class __myclass { __myclass(int __data) : __data_(__data) {} };`.
|
||||
|
||||
## Functions
|
||||
|
||||
- Use `constexpr` for functions that do not depend on run-time features, such as pointers.
|
||||
- If the return type is not explicit (`auto`), then a trailing return type is strongly preferred.
|
||||
|
||||
## Headers
|
||||
|
||||
- Use the correct license:
|
||||
- `libcudacxx/include/cuda/std` files ported from LLVM libc++ use the LLVM license.
|
||||
- `libcudacxx/include/cuda/` files use Apache License v2.0 with LLVM Exceptions.
|
||||
- Headers use include guards with names derived from the uppercase full path and closing `#endif` comments repeating the guard name.
|
||||
- Right after the include guard, include:
|
||||
|
||||
```cpp
|
||||
#include <cuda/std/detail/__config>
|
||||
|
||||
#if defined(_CCCL_IMPLICIT_SYSTEM_HEADER_GCC)
|
||||
# pragma GCC system_header
|
||||
#elif defined(_CCCL_IMPLICIT_SYSTEM_HEADER_CLANG)
|
||||
# pragma clang system_header
|
||||
#elif defined(_CCCL_IMPLICIT_SYSTEM_HEADER_MSVC)
|
||||
# pragma system_header
|
||||
#endif // no system header
|
||||
```
|
||||
|
||||
- The last included header before code must be `<cuda/std/__cccl/prologue.h>`, and `<cuda/std/__cccl/epilogue.h>` must appear at the end of the file.
|
||||
|
||||
## Comments
|
||||
|
||||
- Use Doxygen-style `//! @brief` comments.
|
||||
- Documented functions must include `//! @brief`, `//! @param[in/out/in,out]` for every parameter, and `//! @return` for non-void functions.
|
||||
- The `@brief/@param/@return` description must accurately reflect the current functionality of the function.
|
||||
|
||||
## Compiler Compatibility
|
||||
|
||||
- Do not use lambda expressions in device-only or host-device code.
|
||||
- Do not rely on deduction guides for initialization; use explicit template arguments instead.
|
||||
13
cccl_upstream/.agent/skills/cccl-test/SKILL.md
Normal file
13
cccl_upstream/.agent/skills/cccl-test/SKILL.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
name: cccl-test
|
||||
description: Use when writing, updating, reviewing, or validating CCCL tests; read common CCCL test guidance and the path-specific references named by this skill.
|
||||
---
|
||||
|
||||
# CCCL Test
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Read `references/common.md` for guidance that applies across CCCL tests.
|
||||
2. For `libcudacxx/test/**/*`, also read `references/libcudacxx.md`.
|
||||
3. If no path-specific reference exists, follow nearby tests and repository docs. Do not import test rules from another subproject.
|
||||
4. Apply each reference only to its stated scope. Rules for one CCCL subproject do not automatically apply to another.
|
||||
31
cccl_upstream/.agent/skills/cccl-test/references/common.md
Normal file
31
cccl_upstream/.agent/skills/cccl-test/references/common.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Common CCCL Test Guidance
|
||||
|
||||
Apply this guidance across CCCL tests unless a path-specific test reference says otherwise.
|
||||
|
||||
## Local Consistency
|
||||
|
||||
- Read nearby tests first and mirror their directory layout, file names, helper types, includes, assertion style, and local gating or skip mechanisms.
|
||||
|
||||
## Coverage
|
||||
|
||||
- Cover relevant edge cases.
|
||||
- Cover relevant input and output types.
|
||||
- Cover error behavior when applicable.
|
||||
- Cover runtime and compile-time behavior when applicable.
|
||||
- Cover device and host behavior when applicable.
|
||||
|
||||
## Test Structure
|
||||
|
||||
- All tests must have the correct license banner.
|
||||
- Use the local test harness assertions and helpers.
|
||||
- Use compile-time checks for compile-time guarantees and constexpr coverage when relevant.
|
||||
- Negative tests should check the intended diagnostic or failure mode when the local harness supports it.
|
||||
|
||||
## Portability
|
||||
|
||||
- Prefer project test macros and helpers for compiler, dialect, exception, host/device, and platform probes instead of spelling ad hoc checks directly.
|
||||
- If a test is unsupported, expected to fail, disabled, or skipped on a platform, motivate it with a comment.
|
||||
|
||||
## Validation
|
||||
|
||||
- Use targeted test runs for the project and files being changed.
|
||||
@@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
50
cccl_upstream/.agent/skills/sass-diff/SKILL.md
Normal file
50
cccl_upstream/.agent/skills/sass-diff/SKILL.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
name: sass-diff
|
||||
description: Use when asked to check for SASS (or PTX) changes between commits, branches, or a local changeset; guides normalization, comparison, and reporting of CUDA disassembly diffs.
|
||||
---
|
||||
|
||||
# SASS Diffs
|
||||
|
||||
Use this when asked to check for SASS changes between commits, branches or a local changeset.
|
||||
|
||||
## Goal
|
||||
|
||||
Detect relevant changes in generated CUDA machine code (i.e. SASS) while filtering noise from addresses, symbols, metadata, etc.
|
||||
Any non-trivial change must be detected.
|
||||
|
||||
## Inputs to establish
|
||||
|
||||
* Compilation target under test
|
||||
* The CUDA SM architectures to compile for. Try to detect this from the code and offer the user a list of suggestions.
|
||||
The user must confirm or provide this list.
|
||||
* Baseline source (e.g. the previous commit/branch or the current commit without the changes in the working copy).
|
||||
* Comparison source (e.g. the current commit/branch or the current commit with the changes in the working copy).
|
||||
* Whether a SASS (default) or PTX diff is requested.
|
||||
|
||||
## Disassembly listing generation
|
||||
|
||||
* Compile both, the baseline and comparison source, with the same compiler flags and options.
|
||||
When not specified otherwise, lookup the options from `compile_commands.json`
|
||||
or the current build system (i.e. CMake files).
|
||||
Make sure the CUDA SM architectures (`CMAKE_CUDA_ARCHITECTURES`) are set to the user-provided or approved list.
|
||||
* Dump the disassembly from the binaries produced in the previous set using `cuobjdump -sass` or `cuobjdump -ptx`.
|
||||
|
||||
## Comparison rules (what matters)
|
||||
|
||||
Ignore as trivial:
|
||||
|
||||
* Register renaming with identical instruction sequence and operands.
|
||||
* Pure label renumbering or reordering of identical basic blocks.
|
||||
* Formatting-only differences or reordered symbol tables.
|
||||
* Changes to symbol names (global function names)
|
||||
|
||||
## Reporting
|
||||
|
||||
* If any non-trivial change was detected, report the top 5 regions where a non-trivial change was detected,
|
||||
including the name of the kernel they appeared in.
|
||||
* Provide a short summary of the diff type,
|
||||
including opcode changes, memory access size/cache policy changes, control-flow changes, register-count changes,
|
||||
spills/local memory, shared memory, and occupancy-relevant resource deltas.
|
||||
* Explicitly state if only noise was detected.
|
||||
* If you are not sure if the differences are impactful, show it and ask the user for guidance.
|
||||
* Keep the disassembly dumps available and tell the user where they can find them.
|
||||
Reference in New Issue
Block a user