skbuild package

scikit-build is an improved build system generator for CPython C extensions.

This module provides the glue between the setuptools Python module and CMake.

skbuild.setup(*, cmake_args: Sequence[str] = (), cmake_install_dir: str = '', cmake_source_dir: str = '', cmake_with_sdist: bool = False, cmake_languages: Sequence[str] = ('C', 'CXX'), cmake_minimum_required_version: str | None = None, cmake_process_manifest_hook: Callable[[list[str]], list[str]] | None = None, cmake_install_target: str = 'install', **kw: Any) Distribution[source]

This function wraps setup() so that we can run cmake, make, CMake build, then proceed as usual with setuptools, appending the CMake-generated output as necessary.

The CMake project is re-configured only if needed. This is achieved by (1) retrieving the environment mapping associated with the generator set in the CMakeCache.txt file, (2) saving the CMake configure arguments and version in skbuild.constants.CMAKE_SPEC_FILE(): and (3) re-configuring only if either the generator or the CMake specs change.

Subpackages

Submodules

skbuild.cmaker module

This module provides an interface for invoking CMake executable.

class skbuild.cmaker.CMaker(cmake_executable: str = 'cmake')[source]

Bases: object

Interface to CMake executable.

Example:
>>> # Setup dummy repo
>>> from skbuild.cmaker import CMaker
>>> import ubelt as ub
>>> from os.path import join
>>> repo_dpath = ub.ensure_app_cache_dir('skbuild', 'test_cmaker')
>>> ub.delete(repo_dpath)
>>> src_dpath = ub.ensuredir(join(repo_dpath, 'SRC'))
>>> cmake_fpath = join(src_dpath, 'CMakeLists.txt')
>>> open(cmake_fpath, 'w').write(ub.codeblock(
        '''
        cmake_minimum_required(VERSION 3.5.0)
        project(foobar NONE)
        file(WRITE "${CMAKE_BINARY_DIR}/foo.txt" "# foo")
        install(FILES "${CMAKE_BINARY_DIR}/foo.txt" DESTINATION ".")
        install(CODE "message(STATUS \\"Project has been installed\\")")
        message(STATUS "CMAKE_SOURCE_DIR:${CMAKE_SOURCE_DIR}")
        message(STATUS "CMAKE_BINARY_DIR:${CMAKE_BINARY_DIR}")
        '''
>>> ))
>>> # create a cmaker instance in the dummy repo, configure, and make.
>>> from skbuild.utils import push_dir
>>> with push_dir(repo_dpath):
>>>     cmkr = CMaker()
>>>     config_kwargs = {'cmake_source_dir': str(src_dpath)}
>>>     print('--- test cmaker configure ---')
>>>     env = cmkr.configure(**config_kwargs)
>>>     print('--- test cmaker make ---')
>>>     cmkr.make(env=env)
static check_for_bad_installs() None[source]

This function tries to catch files that are meant to be installed outside the project root before they are actually installed.

Indeed, we can not wait for the manifest, so we try to extract the information (install destination) from the CMake build files *.cmake found in skbuild.constants.CMAKE_BUILD_DIR().

It raises skbuild.exceptions.SKBuildError if it found install destination outside of skbuild.constants.CMAKE_INSTALL_DIR().

configure(clargs: Sequence[str] = (), generator_name: str | None = None, skip_generator_test: bool = False, cmake_source_dir: str = '.', cmake_install_dir: str = '', languages: Sequence[str] = ('C', 'CXX'), cleanup: bool = True) dict[str, str][source]

Calls cmake to generate the Makefile/VS Solution/XCode project.

clargs: tuple

List of command line arguments to pass to cmake executable.

generator_name: string

The string representing the CMake generator to use. If None, uses defaults for your platform.

skip_generator_test: bool

If set to True and if a generator name is specified (either as a keyword argument or as clargs using -G <generator_name>), the generator test is skipped.

cmake_source_dir: string

Path to source tree containing a CMakeLists.txt

cmake_install_dir: string

Relative directory to append to skbuild.constants.CMAKE_INSTALL_DIR().

languages: tuple

List of languages required to configure the project and expected to be supported by the compiler. The language identifier that can be specified in the list corresponds to the one recognized by CMake.

cleanup: bool

If True, cleans up temporary folder used to test generators. Set to False for debugging to see CMake’s output files.

Return a mapping of the environment associated with the selected skbuild.platform_specifics.abstract.CMakeGenerator.

Mapping of the environment can also be later retrieved using get_cached_generator_env().

static get_cached(variable_name: str) str | None[source]

If set, returns the variable cached value from the skbuild.constants.CMAKE_BUILD_DIR(), otherwise returns None

get_cached_generator_env() dict[str, str] | None[source]

If any, return a mapping of environment associated with the cached generator.

classmethod get_cached_generator_name() str | None[source]

Reads and returns the cached generator from the skbuild.constants.CMAKE_BUILD_DIR():. Returns None if not found.

static get_python_include_dir(python_version: str) str | None[source]

Get include directory associated with the current python interpreter.

Args:

python_version (str): python version, may be partial.

Returns:

PathLike: python include dir

Example:
>>> # xdoc: +IGNORE_WANT
>>> from skbuild.cmaker import CMaker
>>> python_version = CMaker.get_python_version()
>>> python_include_dir = CMaker.get_python_include_dir(python_version)
>>> print('python_include_dir = {!r}'.format(python_include_dir))
python_include_dir = '.../conda/envs/py37/include/python3.7m'
static get_python_library(python_version: str) str | None[source]

Get path to the python library associated with the current python interpreter.

Args:

python_version (str): python version, may be partial.

Returns:

PathLike: python_library : python shared library

Example:
>>> # xdoc: +IGNORE_WANT
>>> from skbuild.cmaker import CMaker
>>> python_version = CMaker.get_python_version()
>>> python_library = CMaker.get_python_include_dir(python_version)
>>> print('python_library = {!r}'.format(python_library))
python_library = '.../conda/envs/py37/include/python3.7m'
static get_python_version() str[source]

Get version associated with the current python interpreter.

Returns:

str: python version string

Example:
>>> # xdoc: +IGNORE_WANT
>>> from skbuild.cmaker import CMaker
>>> python_version = CMaker.get_python_version()
>>> print('python_version = {!r}'.format(python_version))
python_version = '3.7'
install() list[str][source]

Returns a list of file paths to install via setuptools that is compatible with the data_files keyword argument.

make(clargs: Sequence[str] = (), config: str = 'Release', source_dir: str = '.', install_target: str = 'install', env: Mapping[str, str] | None = None) None[source]

Calls the system-specific make program to compile code.

install_target: string

Name of the target responsible to install the project. Default is “install”.

Note

To workaround CMake issue #8438. See https://gitlab.kitware.com/cmake/cmake/-/issues/8438 Due to a limitation of CMake preventing from adding a dependency on the “build-all” built-in target, we explicitly build the project first when the install target is different from the default on.

make_impl(clargs: list[str], config: str, source_dir: str, install_target: str | None, env: Mapping[str, str] | None = None) None[source]

Precondition: clargs does not have –config nor –install-target options. These command line arguments are extracted in the caller function make with clargs, config = pop_arg(’–config’, clargs, config)

This is a refactor effort for calling the function make twice in case the install_target is different than the default install.

skbuild.cmaker.get_cmake_version(cmake_executable: str = 'cmake') str[source]

Runs CMake and extracts associated version information. Raises skbuild.exceptions.SKBuildError if it failed to execute CMake.

Example:
>>> # xdoc: IGNORE_WANT
>>> from skbuild.cmaker import get_cmake_version
>>> print(get_cmake_version())
3.14.4
skbuild.cmaker.has_cmake_cache_arg(cmake_args: list[str], arg_name: str, arg_value: str | None = None) bool[source]

Return True if -D<arg_name>:TYPE=<arg_value> is found in cmake_args. If arg_value is None, return True only if -D<arg_name>: is found in the list.

skbuild.cmaker.pop_arg(arg: str, args: Sequence[str], default: None = None) tuple[list[str], str | None][source]
skbuild.cmaker.pop_arg(arg: str, args: Sequence[str], default: str) tuple[list[str], str]

Pops an argument arg from an argument list args and returns the new list and the value of the argument if present and a default otherwise.

skbuild.constants module

This module defines constants commonly used in scikit-build.

skbuild.constants.CMAKE_BUILD_DIR() str[source]

CMake build directory.

skbuild.constants.CMAKE_DEFAULT_EXECUTABLE = 'cmake'

Default path to CMake executable.

skbuild.constants.CMAKE_INSTALL_DIR() str[source]

CMake install directory.

skbuild.constants.CMAKE_SPEC_FILE() str[source]

CMake specification file storing CMake version, CMake configuration arguments and environment variables PYTHONNOUSERSITE and PYTHONPATH.

skbuild.constants.SETUPTOOLS_INSTALL_DIR() str[source]

Setuptools install directory.

skbuild.constants.SKBUILD_DIR() str[source]

Top-level directory where setuptools and CMake directories are generated.

skbuild.constants.SKBUILD_MARKER_FILE() str[source]

Marker file used by skbuild.command.generate_source_manifest.generate_source_manifest.run().

skbuild.constants.set_skbuild_plat_name(plat_name: str) None[source]

Set platform name associated with scikit-build functions returning a path:

skbuild.constants.skbuild_plat_name() str[source]

Get platform name formatted as <operating_system>[-<operating_system_version>]-<machine_architecture>.

Default value corresponds to _default_skbuild_plat_name() and can be overridden with set_skbuild_plat_name().

Examples of values are macosx-10.9-x86_64, linux-x86_64, linux-i686 or win-am64.

skbuild.exceptions module

This module defines exceptions commonly used in scikit-build.

exception skbuild.exceptions.SKBuildError[source]

Bases: RuntimeError

Exception raised when an error occurs while configuring or building a project.

exception skbuild.exceptions.SKBuildGeneratorNotFoundError[source]

Bases: SKBuildError

Exception raised when no suitable generator is found for the current platform.

exception skbuild.exceptions.SKBuildInvalidFileInstallationError[source]

Bases: SKBuildError

Exception raised when a file is being installed into an invalid location.

skbuild.setuptools_wrap module

This module provides functionality for wrapping key infrastructure components from distutils and setuptools.

skbuild.setuptools_wrap.create_skbuild_argparser() ArgumentParser[source]

Create and return a scikit-build argument parser.

skbuild.setuptools_wrap.get_default_include_package_data() bool[source]

Include package data if pyproject.toml contains the project or tool.setuptools table.

skbuild.setuptools_wrap.parse_args() tuple[list[str], str | None, bool, list[str], list[str]][source]

This function parses the command-line arguments sys.argv and returns the tuple (setuptools_args, cmake_executable, skip_generator_test, cmake_args, build_tool_args) where each *_args element corresponds to a set of arguments separated by --.

skbuild.setuptools_wrap.parse_skbuild_args(args: Sequence[str], cmake_args: Sequence[str], build_tool_args: Sequence[str]) tuple[list[str], str | None, bool, list[str], list[str]][source]

Parse arguments in the scikit-build argument set. Convert specified arguments to proper format and append to cmake_args and build_tool_args. Returns the tuple (remaining arguments, cmake executable, skip_generator_test).

skbuild.setuptools_wrap.setup(*, cmake_args: Sequence[str] = (), cmake_install_dir: str = '', cmake_source_dir: str = '', cmake_with_sdist: bool = False, cmake_languages: Sequence[str] = ('C', 'CXX'), cmake_minimum_required_version: str | None = None, cmake_process_manifest_hook: Callable[[list[str]], list[str]] | None = None, cmake_install_target: str = 'install', **kw: Any) Distribution[source]

This function wraps setup() so that we can run cmake, make, CMake build, then proceed as usual with setuptools, appending the CMake-generated output as necessary.

The CMake project is re-configured only if needed. This is achieved by (1) retrieving the environment mapping associated with the generator set in the CMakeCache.txt file, (2) saving the CMake configure arguments and version in skbuild.constants.CMAKE_SPEC_FILE(): and (3) re-configuring only if either the generator or the CMake specs change.

skbuild.setuptools_wrap.strip_package(package_parts: Sequence[str], module_file: str) str[source]

Given package_parts (e.g. ['foo', 'bar']) and a module_file (e.g. foo/bar/jaz/rock/roll.py), starting from the left, this function will strip the parts of the path matching the package parts and return a new string (e.g jaz/rock/roll.py).

The function will work as expected for either Windows or Unix-style module_file and this independently of the platform.