0
# scikit-build
1

2
An improved build system generator for Python C/C++/Fortran/Cython extensions that serves as glue between setuptools and CMake. scikit-build provides enhanced build capabilities for projects that need to compile native code extensions, offering cross-platform compatibility and automated handling of complex build processes.
3

4
## Package Information
5

6
- **Package Name**: scikit-build
7
- **Language**: Python
8
- **Installation**: `pip install scikit-build`
9

10
## Core Imports
11

12
```python
13
from skbuild import setup
14
```
15

16
Basic usage typically only requires importing the setup function:
17

18
```python
19
from skbuild import setup, __version__
20
```
21

22
For advanced configuration:
23

24
```python
25
from skbuild import setup
26
from skbuild.constants import CMAKE_INSTALL_DIR, CMAKE_BUILD_DIR
27
from skbuild.exceptions import SKBuildError
28
```
29

30
## Basic Usage
31

32
```python
33
from skbuild import setup
34

35
setup(
36
    name="my-extension",
37
    version="1.0.0",
38
    description="Python extension with C++ code",
39
    author="Your Name",
40
    
41
    # scikit-build specific options
42
    cmake_args=["-DCMAKE_BUILD_TYPE=Release"],
43
    cmake_source_dir="src",
44
    cmake_install_dir="",
45
    cmake_languages=["C", "CXX"],
46
    
47
    # Standard setuptools options
48
    packages=["my_extension"],
49
    python_requires=">=3.7",
50
)
51
```
52

53
## Architecture
54

55
scikit-build bridges the gap between Python's setuptools ecosystem and CMake's powerful build system capabilities through several key components:
56

57
- **Setup Function**: Enhanced replacement for setuptools.setup() with CMake integration
58
- **CMaker Interface**: Direct interface to CMake executable for configuration and building
59
- **Platform Abstraction**: Platform-specific handling of generators and build environments
60
- **Build Commands**: Custom setuptools commands that integrate CMake into the build process
61
- **Constants and Utilities**: Helper functions and configuration constants for build management
62

63
This design enables developers to create and distribute Python packages that include compiled extensions while maintaining compatibility with modern Python packaging standards and providing robust tooling for managing dependencies, build configurations, and platform-specific compilation requirements across different operating systems and architectures.
64

65
## Capabilities
66

67
### Setup and Configuration
68

69
Enhanced setup function that replaces setuptools.setup() with integrated CMake build system support. Handles CMake configuration, argument parsing, and build orchestration while maintaining full compatibility with setuptools features.
70

71
```python { .api }
72
def setup(
73
    *,
74
    cmake_args: Sequence[str] = (),
75
    cmake_install_dir: str = "",
76
    cmake_source_dir: str = "",
77
    cmake_with_sdist: bool = False,
78
    cmake_languages: Sequence[str] = ("C", "CXX"),
79
    cmake_minimum_required_version: str | None = None,
80
    cmake_process_manifest_hook: Callable[[list[str]], list[str]] | None = None,
81
    cmake_install_target: str = "install",
82
    **kw: Any,
83
) -> upstream_Distribution
84
```
85

86
[Setup and Configuration](./setup-configuration.md)
87

88
### CMake Interface
89

90
Direct interface to CMake executable for project configuration, building, and installation. Provides programmatic access to CMake operations with Python integration for version detection, cache management, and platform-specific build handling.
91

92
```python { .api }
93
class CMaker:
94
    def __init__(self, cmake_executable: str = CMAKE_DEFAULT_EXECUTABLE) -> None: ...
95
    def configure(self, 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]: ...
96
    def make(self, clargs: Sequence[str] = (), config: str = "Release", source_dir: str = ".", install_target: str = "install", env: Mapping[str, str] | None = None) -> None: ...
97
    def install(self) -> list[str]: ...
98
```
99

100
[CMake Interface](./cmake-interface.md)
101

102
### Constants and Utilities
103

104
Configuration constants, directory path functions, and utility functions for build management. Includes platform detection, directory creation, path manipulation, and build artifact management.
105

106
```python { .api }
107
# Directory functions
108
def SKBUILD_DIR() -> str: ...
109
def CMAKE_BUILD_DIR() -> str: ...
110
def CMAKE_INSTALL_DIR() -> str: ...
111

112
# Platform functions  
113
def skbuild_plat_name() -> str: ...
114
def set_skbuild_plat_name(plat_name: str) -> None: ...
115

116
# Utility functions
117
def mkdir_p(path: str) -> None: ...
118
def to_platform_path(path: OptStr) -> OptStr: ...
119
def to_unix_path(path: OptStr) -> OptStr: ...
120
```
121

122
[Constants and Utilities](./constants-utilities.md)
123

124
### Exception Handling
125

126
Exception classes for error handling during CMake configuration, building, and installation processes. Provides specific error types for different failure scenarios.
127

128
```python { .api }
129
class SKBuildError(RuntimeError): ...
130
class SKBuildInvalidFileInstallationError(SKBuildError): ...
131
class SKBuildGeneratorNotFoundError(SKBuildError): ...
132
```
133

134
[Exception Handling](./exception-handling.md)
135

136
### Build Commands
137

138
Custom setuptools command classes that extend standard distutils/setuptools commands with CMake integration. These commands handle the build process orchestration between Python packaging and CMake.
139

140
```python { .api }
141
class build: ...
142
class build_py: ...
143
class build_ext: ...
144
class install: ...
145
class clean: ...
146
class sdist: ...
147
class bdist_wheel: ...
148
```
149

150
[Build Commands](./build-commands.md)
151

152
### Platform Integration
153

154
Platform-specific functionality for CMake generator detection, selection, and cross-platform build configuration. Provides automatic platform detection and generator compatibility testing.
155

156
```python { .api }
157
def get_platform(): ...
158
class CMakeGenerator: ...
159
class CMakePlatform: ...
160
```
161

162
[Platform Integration](./platform-integration.md)
163

164
## Types
165

166
```python { .api }
167
# Type aliases from _compat.typing
168
Protocol: type
169
TypedDict: type  
170
Final: type
171
Literal: type
172
NamedTuple: type
173

174
# External types from dependencies
175
upstream_Distribution = setuptools.dist.Distribution
176
Version = packaging.version.Version
177

178
# Optional string type
179
OptStr = str | None
180

181
# Version information types
182
version: str
183
__version__: str
184
version_tuple: tuple[int, int, int, str, str] | tuple[int, int, int]
185
__version_tuple__: tuple[int, int, int, str, str] | tuple[int, int, int]
186
```