@@ -11,22 +11,29 @@ library (`libsyclinterface`). It is compiled with Intel oneAPI DPC++ (`icx`/`icp
1111 ` source /opt/intel/oneapi/setvars.sh && python -m pytest dpctl/tests/... ` .
1212- Check visible devices: ` sycl-ls ` . Tests skip on missing devices/aspects; a CPU
1313 OpenCL device is enough for most of the suite.
14- - Python build deps: ` pip install numpy cython scikit-build cmake ninja pytest "versioneer[toml]==0.29" ` .
14+ - Python build deps: ` pip install numpy cython scikit-build cmake ninja setuptools pybind11 pytest "versioneer[toml]==0.29" ` .
1515
1616## Commands
1717
1818- Build in place + editable install: ` python scripts/build_locally.py --verbose `
19- - defaults to ` icx ` /` icpx ` on ` PATH ` ; other compilers need ` --compiler-root `
19+ - defaults to ` icx ` /` icpx ` on ` PATH ` ; for other compilers pass absolute
20+ ` --c-compiler ` /` --cxx-compiler ` paths, or names plus ` --compiler-root=<bin dir> `
2021 - ` --debug ` , ` --clean ` , ` --target-cuda[=sm_XX] ` , ` --target-hip=<arch> ` ,
2122 ` --cmake-opts="-D..." `
23+ - the first configure clones the Level Zero headers and downloads pybind11;
24+ offline, pass ` --no-level-zero ` (or
25+ ` --cmake-opts="-DDPCTL_LEVEL_ZERO_INCLUDE_DIR=<dir>" ` ) and install ` pybind11 `
2226- Python tests: ` python -m pytest dpctl/tests `
2327 - one file: ` python -m pytest dpctl/tests/test_sycl_queue.py `
2428 - one test: ` python -m pytest dpctl/tests/test_sycl_queue_memset.py::test_memset_partial_count `
2529 - without a C compiler/Cython: add ` -k "not test_cython_api and not test_c_headers" `
26- - C API tests (GoogleTest, needs ` GTEST_ROOT ` ): ` (cd libsyclinterface && bash dbg_build.sh) `
27- - Coverage (C + Python, rebuilds with ` -DDPCTL_BUILD_CAPI_TESTS=ON ` ):
28- ` python scripts/gen_coverage.py --oneapi `
29- - Docs (needs doxyrest): ` python scripts/gen_docs.py --doxyrest-root=<path> `
30+ - C API tests (Linux; GoogleTest must be findable by CMake, e.g. via ` GTEST_ROOT ` ):
31+ ` (cd libsyclinterface && bash dbg_build.sh) `
32+ - Coverage (Linux; C + Python, rebuilds in place with ` -DDPCTL_BUILD_CAPI_TESTS=ON ` ,
33+ then runs the full pytest suite unless ` --skip-pytest ` ): ` python scripts/gen_coverage.py ` ,
34+ then ` python scripts/build_locally.py --clean ` for a normal build
35+ - Docs (Linux only; needs Doxygen and the ` docs ` extras from ` pyproject.toml ` ):
36+ ` python scripts/gen_docs.py ` , plus ` --doxyrest-root=<path> ` for the C API reference
3037- Lint/format one file (no build needed): ` pre-commit run --files <path> `
3138- Lint/format everything: ` pre-commit run --all-files `
3239 (black, isort, flake8, cython-lint, clang-format, codespell, bandit, shellcheck,
@@ -37,6 +44,7 @@ library (`libsyclinterface`). It is compiled with Intel oneAPI DPC++ (`icx`/`icp
3744- ` libsyclinterface/ ` — C API over SYCL (C++ implementation)
3845 - ` include/syclinterface/*.h ` — public C headers, ` DPCTL<Type>_<Op> ` functions
3946 - ` source/*.cpp ` — implementations
47+ - ` helper/ ` — error handlers and enum/string conversion utils
4048 - ` tests/*.cpp ` — GoogleTest suite; ` *.spv ` are prebuilt kernel fixtures
4149- ` dpctl/ ` — Python package
4250 - ` _backend.pxd ` — Cython ` extern ` declarations of the C API
@@ -51,23 +59,28 @@ library (`libsyclinterface`). It is compiled with Intel oneAPI DPC++ (`icx`/`icp
5159- ` docs/doc_sources/ ` — Sphinx sources
5260- ` conda-recipe/ ` , ` conda-recipe-cf/ ` — conda packaging used by CI
5361- ` scripts/ ` — build, coverage, docs drivers
62+ - ` benchmarks/ ` — asv benchmarks
63+ - ` cmake/ ` — CMake config for downstream projects (` dpctl-config.cmake ` )
5464
5565## Adding a SYCL feature (typical PR shape)
5666
57671 . Declare in ` libsyclinterface/include/syclinterface/dpctl_sycl_<x>_interface.h `
58- with a Doxygen comment and ownership attributes.
68+ with a Doxygen comment and ownership attributes. For an existing SYCL type,
69+ extend its files in steps 1-4 rather than creating new ones.
59702 . Implement in ` libsyclinterface/source/dpctl_sycl_<x>_interface.cpp ` .
60713 . Add GoogleTest cases in ` libsyclinterface/tests/test_sycl_<x>_interface.cpp ` .
61724 . Declare in ` dpctl/_backend.pxd ` ; wrap in ` dpctl/_sycl_<x>.pyx ` (and ` .pxd ` if
62- the method is ` cdef ` ).
73+ the method is ` cdef ` or ` cpdef ` ).
63745 . Add pytest coverage in ` dpctl/tests/ ` .
64- 6 . Add a ` CHANGELOG.md ` entry with the PR link.
75+ 6 . Export new public names (e.g. enums) in ` dpctl/__init__.py ` and list them in
76+ ` docs/doc_sources/api_reference/dpctl/*.rst ` .
77+ 7 . For user-visible changes, add a ` CHANGELOG.md ` entry (see Git).
6578
6679Reference PRs to copy from:
67- - New queue operation: gh-2361 (` DPCTLQueue_Memset ` → ` SyclQueue.memset ` ,
68- ` dpctl/tests/test_sycl_queue_memset.py ` ).
80+ - New queue operation: gh-2361 (` DPCTLQueue_MemsetWithEvents ` →
81+ ` SyclQueue.memset ` / ` memset_async ` , ` dpctl/tests/test_sycl_queue_memset.py ` ).
6982- New device info query: gh-2324 (` dpctl_sycl_device_interface.h ` →
70- ` dpctl/_sycl_device.pyx ` ; register the check in
83+ ` dpctl/_sycl_device.pyx ` ; add a ` check_<name>(device) ` to ` list_of_checks ` in
7184 ` dpctl/tests/_device_attributes_checks.py ` ). New enums go through
7285 ` dpctl_sycl_enum_types.h ` , ` libsyclinterface/helper/ ` , and ` dpctl/enum_types.py ` .
7386
@@ -81,45 +94,53 @@ Reference PRs to copy from:
8194- Never let a C++ exception cross the C boundary: catch, call
8295 ` error_handler(e, __FILE__, __func__, __LINE__) ` , return ` nullptr ` /error value.
8396- Null-check every incoming ref and report via ` error_handler ` .
84- - Errors are silent unless ` DPCTL_VERBOSITY=warning ` (or ` error ` ) is set; set it
85- when debugging a ` nullptr ` return.
97+ - Errors are silent unless ` DPCTL_VERBOSITY ` is set; use ` warning ` when debugging
98+ a ` nullptr ` return ( ` error ` hides the null-ref messages) .
8699
87100### Cython / Python
88101- Release the GIL (` with nogil: ` ) around calls that may block on the device.
89102- Python-visible errors: raise specific exceptions (` TypeError ` , ` ValueError ` ,
90103 ` SyclQueueCreationError ` , ...) when the C API returns ` NULL ` .
91104- Free-threaded CPython (3.14t) is supported; do not rely on the GIL for
92- thread safety of shared state.
105+ thread safety of shared state. New ` .pyx ` files need
106+ ` # cython: freethreading_compatible = True ` , like the existing ones.
93107- Line length 80 (black, isort, cython-lint, clang-format).
94108
95109### Tests
96- - Get devices with ` get_queue_or_skip() ` / skip on missing aspects; never assume
97- a GPU or fp64 support.
110+ - Create queues with ` get_queue_or_skip() ` (` dpctl/tests/helper ` ) or
111+ ` try: dpctl.SyclQueue() ` / ` except dpctl.SyclQueueCreationError: pytest.skip(...) ` ;
112+ skip on missing aspects, never assume a GPU or fp64 support.
98113- Test both sync and ` *_async ` variants when adding queue operations.
99114
100115### Files
101- - New files need the Apache-2.0 license header from ` CONTRIBUTING.md `
102- ( C/C++ headers also need the ` \file ` Doxygen block) .
116+ - New files need the Apache-2.0 license header from ` CONTRIBUTING.md ` with the
117+ current year; all C/C++ files (not only headers) also need the ` \file ` Doxygen block.
103118- Comments and docstrings: short, describe what the code does.
104119
105120## Git
106121
107122- Branch off ` master ` ; pre-commit blocks commits directly to ` master ` and
108123 ` maintenance/* ` .
109124- One concern per PR; fill in ` .github/pull_request_template.md ` .
110- - Update ` CHANGELOG.md ` (Keep a Changelog sections: Added, Changed, Deprecated,
111- Removed, Fixed, Maintenance) for user-visible changes, citing ` gh-NNNN ` .
125+ - Update ` CHANGELOG.md ` under ` ## [dev] ` (Keep a Changelog sections: Added, Changed,
126+ Deprecated, Removed, Fixed, Maintenance) for user-visible changes, e.g.
127+ ` * Added ... [gh-NNNN](https://github.com/IntelPython/dpctl/pull/NNNN) ` ; the
128+ number is only known once the PR is opened.
112129
113130## Boundaries
114131
115132- Generated, do not edit: ` dpctl/*.cxx ` , ` dpctl/**/*.cxx ` , ` dpctl/include/ `
116- (headers copied/generated at build time), ` dpctl/_version.py ` (versioneer),
117- ` _skbuild/ ` , ` build/ ` .
118- - Edit C headers in ` libsyclinterface/include/ ` , not their copies under ` dpctl/include/ ` .
133+ (headers copied/generated at build time), ` _skbuild/ ` , ` build/ ` .
134+ - ` dpctl/_version.py ` is a committed, vendored versioneer file; do not edit it by hand.
135+ - Edit C headers in ` libsyclinterface/include/ ` and Python C-API headers in
136+ ` dpctl/apis/include/ ` , not their copies under ` dpctl/include/ ` .
137+ ` Config/dpctl_config.h ` is generated from ` dpctl_config.h.in ` ; edit the ` .in ` .
119138- In-place ` .so ` files survive branch switches; rebuild (` --clean ` ) before
120139 trusting test results after checking out another branch.
121140- Changing an existing C API signature or enum value is a breaking change:
122- call it out in the PR and the CHANGELOG ` NOTE ` list.
141+ call it out in the PR and in a ` **NOTE**: This release contains breaking changes: `
142+ list at the top of the ` [dev] ` section (as under 0.23.0).
123143- ` .github/workflows/ ` actions are pinned to commit SHAs (checked by zizmor);
124144 keep that when adding steps.
125- - ` conda-recipe*/ ` , release versions, and doc version lists need maintainer review.
145+ - Don't change ` conda-recipe*/ ` , release versions, or ` docs/doc_versions.txt `
146+ unless asked; call such changes out in the PR.
0 commit comments