# 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

  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

- skbuild.command package
  - `CommandMixinProtocol`
    - `CommandMixinProtocol.build_base`
    - `CommandMixinProtocol.distribution`
    - `CommandMixinProtocol.finalize_options()`
    - `CommandMixinProtocol.install_lib`
    - `CommandMixinProtocol.install_platlib`
    - `CommandMixinProtocol.outfiles`
  - `set_build_base_mixin`
    - `set_build_base_mixin.finalize_options()`
  - Submodules
  - skbuild.command.bdist module
    - `bdist`
  - skbuild.command.bdist_wheel module
    - `bdist_wheel`
      - `bdist_wheel.run()`
      - `bdist_wheel.write_wheelfile()`
  - skbuild.command.build module
    - `build`
  - skbuild.command.build_ext module
    - `build_ext`
      - `build_ext.copy_extensions_to_source()`
  - skbuild.command.build_py module
    - `build_py`
      - `build_py.build_module()`
      - `build_py.find_modules()`
      - `build_py.initialize_options()`
      - `build_py.run()`
  - skbuild.command.clean module
    - `clean`
      - `clean.run()`
  - skbuild.command.egg_info module
    - `egg_info`
      - `egg_info.finalize_options()`
  - skbuild.command.generate_source_manifest module
    - `generate_source_manifest`
      - `generate_source_manifest.description`
      - `generate_source_manifest.finalize_options()`
      - `generate_source_manifest.initialize_options()`
      - `generate_source_manifest.run()`
  - skbuild.command.install module
    - `install`
      - `install.finalize_options()`
  - skbuild.command.install_lib module
    - `install_lib`
      - `install_lib.install()`
  - skbuild.command.install_scripts module
    - `install_scripts`
      - `install_scripts.run()`
  - skbuild.command.sdist module
    - `sdist`
      - `sdist.make_archive()`
      - `sdist.make_release_tree()`
      - `sdist.run()`
  - skbuild.command.test module
- skbuild.platform_specifics package
  - `CMakeGenerator`
    - `CMakeGenerator.__init__()`
    - `CMakeGenerator.architecture`
    - `CMakeGenerator.description`
    - `CMakeGenerator.name`
    - `CMakeGenerator.toolset`
  - `get_platform()`
  - Submodules
  - skbuild.platform_specifics.abstract module
    - `CMakeGenerator`
      - `CMakeGenerator.__init__()`
      - `CMakeGenerator.architecture`
      - `CMakeGenerator.description`
      - `CMakeGenerator.name`
      - `CMakeGenerator.toolset`
    - `CMakePlatform`
      - `CMakePlatform.cleanup_test()`
      - `CMakePlatform.compile_test_cmakelist()`
      - `CMakePlatform.default_generators`
      - `CMakePlatform.generator_installation_help`
      - `CMakePlatform.get_best_generator()`
      - `CMakePlatform.get_generator()`
      - `CMakePlatform.get_generators()`
      - `CMakePlatform.write_test_cmakelist()`
  - skbuild.platform_specifics.bsd module
    - `BSDPlatform`
  - skbuild.platform_specifics.cygwin module
    - `CygwinPlatform`
      - `CygwinPlatform.generator_installation_help`
  - skbuild.platform_specifics.linux module
    - `LinuxPlatform`
      - `LinuxPlatform.build_essential_install_cmd()`
      - `LinuxPlatform.generator_installation_help`
  - skbuild.platform_specifics.osx module
    - `OSXPlatform`
      - `OSXPlatform.generator_installation_help`
  - skbuild.platform_specifics.aix module
    - `AIXPlatform`
      - `AIXPlatform.generator_installation_help`
  - skbuild.platform_specifics.platform_factory module
    - `get_platform()`
  - skbuild.platform_specifics.unix module
    - `UnixPlatform`
  - skbuild.platform_specifics.windows module
    - `CMakeVisualStudioCommandLineGenerator`
      - `CMakeVisualStudioCommandLineGenerator.__init__()`
    - `CMakeVisualStudioIDEGenerator`
      - `CMakeVisualStudioIDEGenerator.__init__()`
    - `CachedEnv`
      - `CachedEnv.INCLUDE`
      - `CachedEnv.LIB`
      - `CachedEnv.PATH`
    - `VS_YEAR_TO_VERSION`
    - `WindowsPlatform`
      - `WindowsPlatform.generator_installation_help`
    - `find_visual_studio()`
- skbuild.utils package
  - `CommonLog`
    - `CommonLog.info()`
  - `Distribution`
    - `Distribution.script_name`
  - `PythonModuleFinder`
    - `PythonModuleFinder.check_module()`
    - `PythonModuleFinder.distribution`
    - `PythonModuleFinder.find_all_modules()`
    - `PythonModuleFinder.find_package_modules()`
  - `distribution_hide_listing()`
  - `mkdir_p()`
  - `parse_manifestin()`
  - `push_dir`
    - `push_dir.old_cwd`
  - `to_platform_path()`
  - `to_unix_path()`

## Submodules

## skbuild.cmaker module

This module provides an interface for invoking CMake executable.

class skbuild.cmaker.CMaker(cmake_executable: str = '/usr/bin/cmake')

  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

    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]

    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

    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

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

  classmethod get_cached_generator_name() → str | None

    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

    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

    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

    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]

    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

    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

    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 = '/usr/bin/cmake') → str

  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

  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]
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

  CMake build directory.

skbuild.constants.CMAKE_DEFAULT_EXECUTABLE = '/usr/bin/cmake'

  Default path to CMake executable.

skbuild.constants.CMAKE_INSTALL_DIR() → str

  CMake install directory.

skbuild.constants.CMAKE_SPEC_FILE() → str

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

skbuild.constants.SETUPTOOLS_INSTALL_DIR() → str

  Setuptools install directory.

skbuild.constants.SKBUILD_DIR() → str

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

skbuild.constants.SKBUILD_MARKER_FILE() → str

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

skbuild.constants.get_cmake_version(cmake_path: PathLike[str] | str) → Version

skbuild.constants.set_skbuild_plat_name(plat_name: str) → None

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

  - `SKBUILD_DIR()`

  - `SKBUILD_MARKER_FILE()`

  - `CMAKE_BUILD_DIR()`

  - `CMAKE_INSTALL_DIR()`

  - `CMAKE_SPEC_FILE()`

  - `SETUPTOOLS_INSTALL_DIR()`

skbuild.constants.skbuild_plat_name() → str

  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

  Bases: `RuntimeError`

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

exception skbuild.exceptions.SKBuildGeneratorNotFoundError

  Bases: `SKBuildError`

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

exception skbuild.exceptions.SKBuildInvalidFileInstallationError

  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

  Create and return a scikit-build argument parser.

skbuild.setuptools_wrap.get_default_include_package_data() → bool

  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]]

  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]]

  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

  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

  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.