Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (58 loc) · 3.4 KB

AGENTS.md

File metadata and controls

73 lines (58 loc) · 3.4 KB
Raw

Agent instructions

What this is

cython-cmake ships two CMake modules (FindCython.cmake, UseCython.cmake) plus a thin Python wrapper. The CMake modules are the actual product; the Python package is the delivery mechanism. It is consumed two ways:

  1. As a build dependency — installed alongside scikit-build-core, which adds the package's cmake/ dir to CMAKE_MODULE_PATH via the cmake.module entry point (see pyproject.toml). User CMake code then does find_package(Cython) / include(UseCython).
  2. Vendored — cython-cmake vendor <dir> copies the .cmake files into a user's project so they have no build-time dependency on this package.

Architecture

  • src/cython_cmake/cmake/*.cmake — the real logic. Editing these changes behavior for every consumer.
    • FindCython.cmake: locates the cython executable (prefers one next to the found Python), sets CYTHON_EXECUTABLE / CYTHON_VERSION and a Cython::Cython target. Supports version ranges on CMake 3.19+.
    • UseCython.cmake: defines cython_transpile(), which wires an add_custom_command to turn a .pyx into a .c/.cxx with a DEPFILE. Language is taken from LANGUAGE, else deduced from a # distutils: language=... directive, else from which of C/CXX is enabled.
  • src/cython_cmake/cmake/__init__.py — empty marker; its package dir is the module path exposed to scikit-build-core.
  • vendor.py — Members flag enum + vendorize(). Copies the .cmake files out via importlib.resources.
  • __main__.py — argparse CLI (vendor subcommand). FlagAction maps repeated --members choices onto the Members flag enum.

The Python side is intentionally tiny; most work and most tests exercise CMake.

Commands

Uses uv. Run Python tooling with uv run.

uv run pytest                    # run tests (needs cmake + ninja on PATH)
uv run pytest tests/test_package.py::test_simple   # single test
prek -a --quiet                  # lint (pre-commit); preferred over pre-commit run -a
nox -s tests                     # tests in an isolated env
nox -s pylint                    # pylint (slower; needs install into env)
nox -s build                     # build sdist + wheel

noxfile.py is a uv run --script self-contained script; nox alone runs lint

  • tests across installed Pythons.

Testing notes

  • tests/test_package.py drives real builds: it calls scikit_build_core.build.build_wheel on the fixture projects in tests/packages/ and asserts on generated .c/.cxx/.dep files and wheel contents. These need cmake and ninja available.
  • Fixtures use a # PLACEHOLDER marker in CMakeLists.txt that tests string-replace to inject arguments (e.g. OUTPUT, CYTHON_ARGS).
  • tests/test_vendorize.py checks the CLI copies files byte-for-byte against the sources — if you edit a .cmake file, no test fixture needs updating, but vendoring tests compare against the live file.
  • pytest runs with filterwarnings = ["error"] and xfail_strict — warnings fail the suite.
  • .fmf/.distro/tests/*.fmf and test_pure_cmake.sh are Fedora packaging (tmt/packit) tests, run downstream — not part of local dev.

Conventions

  • Python targets 3.8+; mypy is strict and ruff selects ALL. Keep the from __future__ import annotations header and typed signatures.
  • _version.py is generated by hatch-vcs from git tags; never edit it.