AGENTS.md

Repository Guidelines

Root: CMakeLists.txt drives all builds and tests via CTest.
Source: src/, public headers in include/.
Bench configs: benchmarking/*.bench
Tooling: cmake/ (modules, toolchains), external/ (dependencies)
Vulkan headers: external/Vulkan-Headers/include/vulkan/ (do not use the system headers)

Configure (choose window system for GLES):
- mkdir build && cd build
- cmake .. -DWINDOWSYSTEM=x11 (options: sdl, fbdev, pbuffers, default is X11)
Build: make -j | Run tests: ctest --output-on-failure
Example run: ./vulkan_general --help (from build/).

Language: C++20 with -Wall -g. Match existing style in src/ and include/.
Names: test binaries follow vulkan_<name>, gles_<name>, opencl_<name>; sources in src/<api>_<name>.cpp.
CMake helpers: prefer vulkan_test(name), gles_test(name), cl_test(name, version) to add tests and install bench files.
Bench files: add benchmarking/<api>_<name>.bench aligned with the target name.
Add assert() calls to verify assumptions. Do not work around problems with defensive coding.
Avoid adding unnecessary namespaces.
Do not use lambdas, anonymous namespaces or throw new exceptions.

Run test binaries directly, do not run via CTest unless asked to.
For Vulkan tests, you can add the command line parameter --cpu to workaround AI sandbox problems.
For Vulkan tests, you can add the command line parameter -v to enable the Vulkan validation layer.
Tests shall return error code 77 when a feature is not supported.
Tests shall check the environment variable TOOLSTEST_NULL_RUN before failing or asserting on the results of GPU work.
Tests should use vkAssertBufferARM (usually accessible as vulkan.vkAssertBuffer) to allow a 'burn in' of test assumptions into API traces.