0
# Constants and Utilities
1

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

4
## Capabilities
5

6
### Directory Path Functions
7

8
Functions that return standardized directory paths used throughout the scikit-build process for organizing build artifacts and installation files.
9

10
```python { .api }
11
def SKBUILD_DIR() -> str:
12
    """
13
    Return top-level directory for build artifacts (_skbuild).
14
    
15
    This directory contains all scikit-build generated files including
16
    CMake build directory, installation directory, and configuration files.
17
    
18
    Returns:
19
    Path to _skbuild directory
20
    """
21

22
def CMAKE_BUILD_DIR() -> str:
23
    """
24
    Return CMake build directory path.
25
    
26
    Directory where CMake performs the actual build process,
27
    containing generated makefiles, object files, and build artifacts.
28
    
29
    Returns:
30
    Path to CMake build directory within _skbuild
31
    """
32

33
def CMAKE_INSTALL_DIR() -> str:
34
    """
35
    Return CMake installation directory path.
36
    
37
    Directory where CMake installs built artifacts before they are
38
    copied to their final package locations.
39
    
40
    Returns:
41
    Path to CMake installation directory within _skbuild
42
    """
43

44
def CMAKE_SPEC_FILE() -> str:
45
    """
46
    Return path to CMake specification file.
47
    
48
    File that stores CMake version and configuration information
49
    from the build process for reuse in subsequent builds.
50
    
51
    Returns:
52
    Path to cmake-spec.json file
53
    """
54

55
def SETUPTOOLS_INSTALL_DIR() -> str:
56
    """
57
    Return setuptools installation directory path.
58
    
59
    Directory where setuptools installs Python files and packages
60
    during the build process.
61
    
62
    Returns:
63
    Path to setuptools installation directory within _skbuild
64
    """
65

66
def SKBUILD_MARKER_FILE() -> str:
67
    """
68
    Return path to scikit-build marker file.
69
    
70
    Marker file used by generate_source_manifest command to track
71
    scikit-build generated files.
72
    
73
    Returns:
74
    Path to marker file
75
    """
76
```
77

78
### Platform Configuration
79

80
Functions for managing platform-specific build configuration and platform name detection.
81

82
```python { .api }
83
def skbuild_plat_name() -> str:
84
    """
85
    Get platform name formatted for scikit-build.
86
    
87
    Returns platform name in the format:
88
    <operating_system>[-<operating_system_version>]-<machine_architecture>
89
    
90
    Examples:
91
    - linux-x86_64
92
    - win-amd64  
93
    - macosx-10.15-x86_64
94
    
95
    Returns:
96
    Formatted platform name string
97
    """
98

99
def set_skbuild_plat_name(plat_name: str) -> None:
100
    """
101
    Set platform name for scikit-build operations.
102
    
103
    Override the automatically detected platform name with a custom
104
    value for cross-compilation or specific platform targeting.
105
    
106
    Parameters:
107
    - plat_name: Platform name string to use
108
    """
109
```
110

111
### Version Detection
112

113
Functions for detecting and validating CMake version information.
114

115
```python { .api }
116
def get_cmake_version(cmake_path: os.PathLike[str] | str) -> Version:
117
    """
118
    Extract CMake version from executable path.
119
    
120
    Executes the CMake binary to determine its version and returns
121
    a parsed Version object for comparison and validation.
122
    
123
    Parameters:
124
    - cmake_path: Path to cmake executable
125
    
126
    Returns:
127
    packaging.version.Version object representing CMake version
128
    
129
    Raises:
130
    SKBuildError: If cmake executable not found or version extraction fails
131
    """
132
```
133

134
### Directory Management
135

136
Utility functions for creating directories and managing the filesystem during builds.
137

138
```python { .api }
139
def mkdir_p(path: str) -> None:
140
    """
141
    Create directory and parent directories if they don't exist.
142
    
143
    Equivalent to 'mkdir -p' command - creates the target directory
144
    and any missing parent directories in the path.
145
    
146
    Parameters:
147
    - path: Directory path to create
148
    
149
    Raises:
150
    OSError: If directory creation fails due to permissions or other errors
151
    """
152
```
153

154
### Path Manipulation
155

156
Functions for converting paths between different formats for cross-platform compatibility.
157

158
```python { .api }
159
def to_platform_path(path: OptStr) -> OptStr:
160
    """
161
    Convert path separators to platform-specific format.
162
    
163
    Converts all path separators in the given path to the format
164
    appropriate for the current operating system (os.sep).
165
    
166
    Parameters:
167
    - path: Path string to convert, or None
168
    
169
    Returns:
170
    Path with platform-specific separators, or None if input was None
171
    """
172

173
def to_unix_path(path: OptStr) -> OptStr:
174
    """
175
    Convert path separators to forward slashes.
176
    
177
    Converts all path separators to forward slashes ('/') regardless
178
    of the current platform, useful for CMake paths and cross-platform scripts.
179
    
180
    Parameters:
181
    - path: Path string to convert, or None
182
    
183
    Returns:
184
    Path with forward slash separators, or None if input was None
185
    """
186
```
187

188
### Build Utilities
189

190
Utility classes and functions for managing the build process and package discovery.
191

192
```python { .api }
193
class Distribution(NamedTuple):
194
    """Distribution information container."""
195
    script_name: str
196

197
class push_dir:
198
    """
199
    Context manager for temporarily changing directory.
200
    
201
    Changes to the specified directory for the duration of the
202
    context and restores the original directory when exiting.
203
    """
204
    def __init__(self, new_dir: str) -> None: ...
205
    def __enter__(self) -> str: ...
206
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
207

208
class PythonModuleFinder:
209
    """
210
    Utility class for finding Python modules in packages.
211
    
212
    Extends distutils build_py functionality to locate Python
213
    modules within package structures for installation.
214
    """
215
    def find_all_modules(self) -> list[tuple[str, str, str]]: ...
216
    def find_modules_in_package(self, package: str) -> list[tuple[str, str, str]]: ...
217
```
218

219
### Manifest Processing
220

221
Functions for processing MANIFEST.in files and package data.
222

223
```python { .api }
224
def parse_manifestin(template: str) -> list[str]:
225
    """
226
    Parse MANIFEST.in template files and return file patterns.
227
    
228
    Processes MANIFEST.in template syntax and returns a list of
229
    file patterns that match the template rules.
230
    
231
    Parameters:
232
    - template: MANIFEST.in template content string
233
    
234
    Returns:
235
    List of file pattern strings derived from template
236
    
237
    Raises:
238
    ValueError: If template syntax is invalid
239
    """
240
```
241

242
### Distribution Management
243

244
Context manager for controlling setuptools output during the build process.
245

246
```python { .api }
247
def distribution_hide_listing(
248
    distribution: setuptools._distutils.dist.Distribution | Distribution
249
) -> Iterator[bool | int]:
250
    """
251
    Context manager to temporarily suppress distribution listing output.
252
    
253
    Temporarily hides verbose output from setuptools distribution
254
    operations to reduce noise during the build process.
255
    
256
    Parameters:
257
    - distribution: Setuptools distribution object
258
    
259
    Yields:
260
    Previous listing state value
261
    """
262
```
263

264
### Constants
265

266
Essential constants used throughout scikit-build for default configuration.
267

268
```python { .api }
269
CMAKE_DEFAULT_EXECUTABLE: str = "cmake"
270
"""Default CMake executable name for platform detection and execution."""
271
```
272

273
## Usage Examples
274

275
### Directory Management
276

277
```python
278
from skbuild.constants import SKBUILD_DIR, CMAKE_BUILD_DIR, CMAKE_INSTALL_DIR
279
from skbuild.utils import mkdir_p, push_dir
280
import os
281

282
# Get standard build directories
283
skbuild_dir = SKBUILD_DIR()
284
build_dir = CMAKE_BUILD_DIR()
285
install_dir = CMAKE_INSTALL_DIR()
286

287
print(f"Build artifacts in: {skbuild_dir}")
288
print(f"CMake build in: {build_dir}")
289
print(f"Installation in: {install_dir}")
290

291
# Create directories if needed
292
mkdir_p(build_dir)
293
mkdir_p(install_dir)
294

295
# Change directory temporarily
296
with push_dir(build_dir):
297
    print(f"Now in: {os.getcwd()}")
298
    # Perform build operations
299
print(f"Back in: {os.getcwd()}")
300
```
301

302
### Platform Configuration
303

304
```python
305
from skbuild.constants import skbuild_plat_name, set_skbuild_plat_name
306

307
# Get current platform
308
current_platform = skbuild_plat_name()
309
print(f"Current platform: {current_platform}")
310

311
# Override for cross-compilation
312
set_skbuild_plat_name("linux-aarch64")
313
cross_platform = skbuild_plat_name()
314
print(f"Cross-compile platform: {cross_platform}")
315
```
316

317
### Path Manipulation
318

319
```python
320
from skbuild.utils import to_platform_path, to_unix_path
321

322
# Convert paths for current platform
323
unix_path = "src/native/lib/module.cpp"
324
platform_path = to_platform_path(unix_path)
325
print(f"Platform path: {platform_path}")
326

327
# Convert to Unix format for CMake
328
windows_path = r"src\native\lib\module.cpp"
329
unix_format = to_unix_path(windows_path)
330
print(f"Unix path: {unix_format}")
331
```
332

333
### CMake Version Checking
334

335
```python
336
from skbuild.constants import get_cmake_version, CMAKE_DEFAULT_EXECUTABLE
337
from packaging.version import Version
338

339
# Check CMake version
340
cmake_version = get_cmake_version(CMAKE_DEFAULT_EXECUTABLE)
341
print(f"CMake version: {cmake_version}")
342

343
# Version comparison
344
min_version = Version("3.15.0")
345
if cmake_version >= min_version:
346
    print("CMake version is sufficient")
347
else:
348
    print(f"CMake {min_version} or later required")
349
```
350

351
### Module Discovery
352

353
```python
354
from skbuild.utils import PythonModuleFinder
355

356
# Find Python modules in package
357
finder = PythonModuleFinder()
358
modules = finder.find_all_modules()
359

360
for package, module, file_path in modules:
361
    print(f"Package: {package}, Module: {module}, File: {file_path}")
362
```