cython-cmake 0.3.0

CMake helpers for building Cython modules

cython-cmake

This provides helpers for using Cython. Use:

find_package(Cython MODULE REQUIRED VERSION 3.0)
include(UseCython)

If you find Python beforehand, the search will take this into account. You can specify a version range on CMake 3.19+. This will define a Cython::Cython target (along with a matching CYTHON_EXECUTABLE variable). The UseCython module will provide the following helper function:

cython_transpile(<pyx_file>
                 [LANGUAGE C | CXX]
                 [CYTHON_ARGS <args> ...]
                 [INCLUDE_DIRECTORIES <dir> ...]
                 [MODULE_NAME <module_name>]
                 [OUTPUT <OutputFile>]
                 [OUTPUT_VARIABLE <OutputVariable>]
                 [PUBLIC_HEADER_VARIABLE <PublicHeaderVariable>]
                 [API_HEADER_VARIABLE <ApiHeaderVariable>]
                 [DEPENDS <depends> ...]
                 )

This function takes a pyx file and makes a matching .c / .cxx file in the current binary directory (exact path can be specified with OUTPUT). A .py file can be given instead, to support Cython's pure Python mode. The location of the produced file is placed in the variable specified by OUTPUT_VARIABLE if given. Extra arguments to the Cython executable can be given with CYTHON_ARGS, and if this is not set, it will take a default from a CYTHON_ARGS variable.

INCLUDE_DIRECTORIES lists directories to search for cimported .pxd files; each is passed to Cython as -I <dir>, with relative paths resolved against the current source directory. Prefer this over adding -I to CYTHON_ARGS, which is a single escape hatch. See Sharing .pxd files between packages.

MODULE_NAME sets the fully qualified dotted module name (e.g. pkg.sub.mod), forwarded as --module-name. Without it, Cython derives the name from the filename and can only qualify it with the containing package if it can walk __init__ files from the source location — set this explicitly when that is not the case, since it affects __module__, pickling, and error messages.

A .pyx with cdef public or cdef api declarations makes Cython write a <name>.h or <name>_api.h header next to the generated source. Pass PUBLIC_HEADER_VARIABLE and/or API_HEADER_VARIABLE to declare those headers as build outputs (so other targets can depend on them) and receive their paths in the given variables. This is useful when embedding Cython in a larger C/C++ application.

cimported .pxd files are tracked automatically through the depfile. Use DEPENDS for extra files or targets the transpilation needs but that do not exist at configure time, such as a .pxd generated by another target (e.g. autopxd).

If the LANGUAGE is not given, and both C and CXX are enabled globally, then the language will try to be deduced from a # distutils: language=... comment in the source file, and C will be used if not found. Only the language directive is read; unlike cythonize, other # distutils: directives (libraries, include_dirs, extra_compile_args, ...) are ignored, since CMake owns the build configuration — express those as properties on the target you build from the generated source.

This utility relies on the DEPFILE feature introduced for Ninja in CMake 3.7, and added for Make in CMake 3.20, and Visual Studio & Xcode in CMake 3.21.

Example

find_package(
  Python
  COMPONENTS Interpreter Development.Module
  REQUIRED)
include(UseCython)

cython_transpile(simple.pyx LANGUAGE C CYTHON_ARGS -X language_level=3 OUTPUT_VARIABLE simple_c)

python_add_library(simple MODULE "${simple_c}" WITH_SOABI)
install(TARGETS simple DESTINATION .)

Sharing .pxd files between packages

If your package exposes declarations that others should be able to cimport (the NumPy pattern), install the .pxd files next to the compiled modules so they ship in the wheel:

install(TARGETS mymod DESTINATION mypkg)
install(FILES mymod.pxd DESTINATION mypkg)

A consumer then locates the installed package and points INCLUDE_DIRECTORIES at it. The provider's install root can be found by querying its module location with the Python interpreter you already found:

find_package(
  Python
  COMPONENTS Interpreter Development.Module
  REQUIRED)

execute_process(
  COMMAND "${Python_EXECUTABLE}" -c
          "import mypkg, os; print(os.path.dirname(mypkg.__file__))"
  OUTPUT_VARIABLE mypkg_include_dir
  OUTPUT_STRIP_TRAILING_WHITESPACE)

cython_transpile(consumer.pyx
  INCLUDE_DIRECTORIES "${mypkg_include_dir}"
  OUTPUT_VARIABLE consumer_c
)

The consumer's .pyx can now cimport from the provider (e.g. from mypkg.mymod cimport ...). cimported .pxd files reached this way are tracked in the depfile like any other, so incremental rebuilds work.

scikit-build-core

To use this package with scikit-build-core, you need to include it in your build requirements:

[build-system]
requires = ["scikit-build-core", "cython", "cython-cmake"]
build-backend = "scikit_build_core.build"

It is also recommended to require CMake 3.21 or newer in your CMakeLists.txt.

Vendoring

You can vendor FindCython and/or UseCython into your package, as well. This avoids requiring a dependency at build time and protects you against changes in this package, at the expense of requiring manual re-vendoring to get bugfixes and/or improvements. This mechanism is also ideal if you want to support direct builds, outside of scikit-build-core.

You should make a CMake helper directory, such as cmake. Add this to your CMakeLists.txt like this:

list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")

Then, you can vendor our files into that folder:

pipx run cython-cmake vendor cmake

If you want to just vendor one of the two files, use --member FindCython or --member UseCython. You can rerun this command to revendor. The directory must already exist.