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 inskbuild.constants.CMAKE_SPEC_FILE()
: and (3) re-configuring only if either the generator or the CMake specs change.
Subpackages¶
- skbuild.command package
CommandMixinProtocol
set_build_base_mixin
- Submodules
- skbuild.command.bdist module
- skbuild.command.bdist_wheel module
- skbuild.command.build module
- skbuild.command.build_ext module
- skbuild.command.build_py module
- skbuild.command.clean module
- skbuild.command.egg_info module
- skbuild.command.generate_source_manifest module
- skbuild.command.install module
- skbuild.command.install_lib module
- skbuild.command.install_scripts module
- skbuild.command.sdist module
- skbuild.command.test module
- skbuild.platform_specifics package
CMakeGenerator
get_platform()
- Submodules
- skbuild.platform_specifics.abstract module
- skbuild.platform_specifics.bsd module
- skbuild.platform_specifics.cygwin module
- skbuild.platform_specifics.linux module
- skbuild.platform_specifics.osx module
- skbuild.platform_specifics.aix module
- skbuild.platform_specifics.platform_factory module
- skbuild.platform_specifics.unix module
- skbuild.platform_specifics.windows module
- skbuild.utils package
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 inskbuild.constants.CMAKE_BUILD_DIR()
.It raises
skbuild.exceptions.SKBuildError
if it found install destination outside ofskbuild.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 incmake_args
. Ifarg_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 listargs
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_DEFAULT_EXECUTABLE = 'cmake'¶
Default path to CMake executable.
- skbuild.constants.CMAKE_SPEC_FILE() str [source]¶
CMake specification file storing CMake version, CMake configuration arguments and environment variables
PYTHONNOUSERSITE
andPYTHONPATH
.
- 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 withset_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 inskbuild.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 amodule_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.gjaz/rock/roll.py
).The function will work as expected for either Windows or Unix-style
module_file
and this independently of the platform.