ref(upstream): FULL TREE — Deep-Spark xllm (1470) + ds_vllm csrc/models (703)
Replaces cherry-picked upstream_ref with complete source trees. xllm/ — Iluvatar official C++ inference engine (15MB, 1470 files) Complete: kernels → layers → models → runtime → scheduler → api Excluded: .git, binary images, third_party submodule checkouts ds_vllm/ — Iluvatar official vllm fork (8MB, 703 files) Included: csrc/ (ALL CUDA kernels), fused_moe/, qwen3_5 model, _custom_ops Excluded: tests, benchmarks, docs, examples (not needed for reference) Critical call chains now fully traceable: MoE: moe_topk_softmax_kernels.cuh → ixformer.h → fused_moe.cpp → layer GDN: qwen3_gated_delta_net_base.cpp → qwen3_5_gated_delta_net.cpp Attention: ixformer.h → xllm_paged_attention → attention.cpp
This commit is contained in:
EX Engine
48
upstream_ref/xllm/.agents/skills/add-unit-test/SKILL.md
Normal file
48
upstream_ref/xllm/.agents/skills/add-unit-test/SKILL.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
name: add-unit-test
|
||||
description: Add or update xLLM unit tests in the repository. Use when Codex needs to create a new C++/CUDA/NPU/MLU unit test, place a test under tests/, wire it into CMake with cc_test, update an existing test target, choose platform gates, or validate test naming and dependencies against current xLLM test conventions.
|
||||
---
|
||||
|
||||
# Add Unit Test
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Inspect the production code and the nearest existing tests before writing a new test.
|
||||
- Match the production path under `xllm/` to `tests/` where possible.
|
||||
- Prefer extending an existing nearby `*_test.cpp` and `cc_test` target when the behavior belongs to the same domain.
|
||||
- Create a new test source only when it improves isolation, keeps platform setup separate, or follows an existing directory pattern.
|
||||
|
||||
2. Read the project style guide before editing production files under `xllm/`, and apply the same C++ style discipline to new test code:
|
||||
`.agents/skills/code-review/references/custom-code-style.md`.
|
||||
|
||||
3. Follow the current test layout and CMake conventions.
|
||||
- Read [xllm-test-patterns.md](references/xllm-test-patterns.md) when adding a new test file, new `cc_test`, platform-specific test, or test directory.
|
||||
- Use `*_test.cpp` for C++ test files and `*_test.cu` for CUDA source tests.
|
||||
- Do not create nested `test/` or `tests/` directories for new unit tests unless the surrounding tree already requires that structure.
|
||||
|
||||
4. Wire tests through CMake with `include(cc_test)` and `cc_test(...)`.
|
||||
- Keep source names relative to the current test directory unless an existing target already uses an absolute source path for a production `.cpp`.
|
||||
- Use target names ending in `_test`.
|
||||
- Put platform-directory gates in the parent `CMakeLists.txt` when the whole child directory is platform-specific.
|
||||
- Use target-level `if(USE_NPU)`, `if(USE_MLU)`, `if(USE_CUDA)`, or generator expressions only when a mixed directory contains both generic and platform-specific tests.
|
||||
|
||||
5. Write tests for observable behavior, not implementation trivia.
|
||||
- Cover success, edge, and error paths touched by the change.
|
||||
- Prefer deterministic inputs, fixed seeds, and small tensors/data structures.
|
||||
- Keep helpers file-local in an anonymous namespace unless shared by multiple test files.
|
||||
- Use `TEST`/`TEST_F` names that describe behavior clearly.
|
||||
|
||||
6. Validate narrowly before finishing.
|
||||
- Always run `git diff --check` for the changed test paths.
|
||||
- Search for stale filenames after moving or renaming tests.
|
||||
- Run the narrowest build/test command available locally; if not feasible, state the exact reason and what was checked instead.
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
rg --files tests/<area>
|
||||
rg "old_test_name|old_file_name" tests xllm CMakeLists.txt
|
||||
git diff --check -- tests/<area>
|
||||
```
|
||||
|
||||
For full remote validation on the development machine, use the repository AGENTS instructions for SSH, container, build, and test commands.
|
||||
@@ -0,0 +1,124 @@
|
||||
# xLLM Unit Test Patterns
|
||||
|
||||
Use this reference when creating or changing unit tests under `tests/`.
|
||||
|
||||
## Layout
|
||||
|
||||
- Mirror production structure where practical:
|
||||
- `xllm/core/framework/tokenizer` -> `tests/core/framework/tokenizer`
|
||||
- `xllm/core/layers/mlu` -> `tests/core/layers/mlu`
|
||||
- `xllm/function_call/...` -> `tests/function_call/...`
|
||||
- Keep tests directly in the relevant leaf directory.
|
||||
- Avoid new nested `test/` or `tests/` directories. Recent cleanup moved those tests into their parent directories.
|
||||
- Shared helpers may live beside tests, such as `tests/core/layers/mlu/tests_utils.cpp`.
|
||||
|
||||
## Naming
|
||||
|
||||
- Test source files use singular suffixes:
|
||||
- C++: `thing_test.cpp`
|
||||
- CUDA source: `thing_test.cu`
|
||||
- Test CMake target names also end in `_test`.
|
||||
- If a target aggregates several source files, keep the target name at the domain level, for example `layer_test`, `moe_layer_test`, or `sampler_test`.
|
||||
- Keep helper files out of the `*_test.cpp` suffix unless they define tests.
|
||||
|
||||
## CMake Basics
|
||||
|
||||
Use `cc_test` for C++/CUDA unit test binaries:
|
||||
|
||||
```cmake
|
||||
include(cc_test)
|
||||
|
||||
cc_test(
|
||||
NAME
|
||||
feature_test
|
||||
SRCS
|
||||
feature_test.cpp
|
||||
DEPS
|
||||
:feature
|
||||
GTest::gtest_main
|
||||
glog::glog
|
||||
)
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Add `include(cc_test)` in each CMake file that declares `cc_test`.
|
||||
- Use dependencies that match nearby tests first.
|
||||
- Prefer `GTest::gtest_main`; add `GTest::gtest` only when nearby tests need it or the target explicitly uses it.
|
||||
- Add `target_link_libraries(...)` and `add_dependencies(...)` after `cc_test` when needed for `brpc`, `OpenSSL`, `protobuf`, platform runtime libraries, or link-group handling.
|
||||
- Use `:target_name` for local production CMake targets where existing tests do so.
|
||||
|
||||
## Platform Gates
|
||||
|
||||
Gate entire platform-only directories in the parent `CMakeLists.txt`.
|
||||
|
||||
Current examples:
|
||||
|
||||
```cmake
|
||||
if(USE_CUDA)
|
||||
add_subdirectory(cuda)
|
||||
endif()
|
||||
|
||||
if(USE_NPU)
|
||||
add_subdirectory(npu)
|
||||
endif()
|
||||
```
|
||||
|
||||
```cmake
|
||||
if(USE_CUDA)
|
||||
add_subdirectory(cuda)
|
||||
endif()
|
||||
|
||||
if(USE_MLU)
|
||||
add_subdirectory(mlu)
|
||||
endif()
|
||||
```
|
||||
|
||||
Do not repeat the same platform `if(...)` inside every child CMake file when the parent already gates the directory.
|
||||
|
||||
Use target-level platform gates only for mixed directories where generic and platform-specific tests coexist, such as `tests/core/runtime` or framework directories with both generic and NPU-only targets.
|
||||
|
||||
Use generator expressions for platform-specific optional link libraries when the target exists across platforms:
|
||||
|
||||
```cmake
|
||||
target_link_libraries(example_test
|
||||
PUBLIC
|
||||
Python::Python
|
||||
$<$<BOOL:${USE_NPU}>:ascendcl>
|
||||
$<$<BOOL:${USE_NPU}>:hccl>
|
||||
$<$<BOOL:${USE_NPU}>:c_sec>)
|
||||
```
|
||||
|
||||
## Source Style
|
||||
|
||||
- Add the xLLM copyright header to new files, using the current year.
|
||||
- Include `<gtest/gtest.h>` in every test source.
|
||||
- Use project-root-relative includes; avoid `../` includes.
|
||||
- Put file-local helpers in an anonymous namespace.
|
||||
- Prefer fixed-width integers (`int32_t`, `int64_t`) unless an API requires plain `int`.
|
||||
- Use `static_cast`, `nullptr`, braces on all control statements, and concise comments only where they clarify test setup.
|
||||
- Keep deterministic random or tensor tests seeded with stable labels or fixed seeds.
|
||||
|
||||
## Test Design
|
||||
|
||||
- Test behavior through public or stable internal interfaces used by nearby tests.
|
||||
- Cover the regression or edge case that motivated the test.
|
||||
- For parser and pure logic tests, keep inputs small and assert exact outputs/errors.
|
||||
- For tensor/device tests, keep tensor shapes small, check dtype/device expectations, and compare against a simple reference implementation.
|
||||
- For forked-process or device-init-sensitive tests, follow nearby standalone target patterns and leave a short CMake comment explaining why the target is isolated.
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before finishing:
|
||||
|
||||
```bash
|
||||
rg --files tests/<area>
|
||||
rg "old_file_name|old_target_name" tests xllm CMakeLists.txt
|
||||
git diff --check -- tests/<area>
|
||||
```
|
||||
|
||||
Run the narrowest feasible validation:
|
||||
|
||||
- Local CMake/build target if available.
|
||||
- `python setup.py test` in the project container when full validation is requested or risk is high.
|
||||
- For development-machine validation, follow the repo AGENTS instructions for `ssh gpu-h800-195`, `/export/home/zhangxu709/xllm`, container `zx-xllm-cuda`, and the build/test commands.
|
||||
Reference in New Issue
Block a user