0
# CMake Interface
1

2
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.
3

4
## Capabilities
5

6
### CMaker Class
7

8
Main interface class for interacting with CMake executable, providing methods for configuration, building, and installation of CMake projects.
9

10
```python { .api }
11
class CMaker:
12
    def __init__(self, cmake_executable: str = CMAKE_DEFAULT_EXECUTABLE) -> None:
13
        """
14
        Initialize CMaker with path to CMake executable.
15
        
16
        Parameters:
17
        - cmake_executable: Path to cmake executable (default: "cmake")
18
        """
19
```
20

21
### Project Configuration
22

23
Configure CMake project with specified parameters, handling generator selection, source directory setup, and build configuration.
24

25
```python { .api }
26
def configure(
27
    self, 
28
    clargs: Sequence[str] = (), 
29
    generator_name: str | None = None, 
30
    skip_generator_test: bool = False, 
31
    cmake_source_dir: str = ".", 
32
    cmake_install_dir: str = "", 
33
    languages: Sequence[str] = ("C", "CXX"), 
34
    cleanup: bool = True
35
) -> dict[str, str]:
36
    """
37
    Configure CMake project with specified parameters.
38
    
39
    Parameters:
40
    - clargs: Additional command-line arguments for CMake
41
    - generator_name: CMake generator to use (auto-detected if None)
42
    - skip_generator_test: Skip generator compatibility testing
43
    - cmake_source_dir: Directory containing CMakeLists.txt
44
    - cmake_install_dir: Installation directory for CMake
45
    - languages: Programming languages to enable in CMake
46
    - cleanup: Clean build directory before configuration
47
    
48
    Returns:
49
    Dictionary of CMake cache variables and their values
50
    
51
    Raises:
52
    SKBuildError: If configuration fails
53
    SKBuildGeneratorNotFoundError: If no suitable generator found
54
    """
55
```
56

57
### Project Building
58

59
Build CMake project using the configured generator with support for different build configurations and parallel builds.
60

61
```python { .api }
62
def make(
63
    self, 
64
    clargs: Sequence[str] = (), 
65
    config: str = "Release", 
66
    source_dir: str = ".", 
67
    install_target: str = "install", 
68
    env: Mapping[str, str] | None = None
69
) -> None:
70
    """
71
    Build CMake project using configured generator.
72
    
73
    Parameters:
74
    - clargs: Additional command-line arguments for build
75
    - config: Build configuration (Release, Debug, etc.)
76
    - source_dir: Source directory for build
77
    - install_target: CMake target to build and install  
78
    - env: Environment variables for build process
79
    
80
    Raises:
81
    SKBuildError: If build fails
82
    """
83
```
84

85
### Project Installation
86

87
Install built CMake project and return list of installed files for package management.
88

89
```python { .api }
90
def install(self) -> list[str]:
91
    """
92
    Install built CMake project.
93
    
94
    Installs the built project using CMake and returns list of
95
    files that were installed for package management.
96
    
97
    Returns:
98
    List of installed file paths
99
    
100
    Raises:
101
    SKBuildError: If installation fails
102
    """
103
```
104

105
### Cache Management
106

107
Static methods for retrieving cached CMake configuration values from previous builds.
108

109
```python { .api }
110
@staticmethod
111
def get_cached(variable_name: str) -> str | None:
112
    """
113
    Retrieve cached CMake variable value.
114
    
115
    Parameters:
116
    - variable_name: Name of CMake cache variable
117
    
118
    Returns:
119
    Variable value if found, None otherwise
120
    """
121

122
@classmethod  
123
def get_cached_generator_name(cls) -> str | None:
124
    """
125
    Return cached CMake generator name from previous build.
126
    
127
    Returns:
128
    Generator name if cached, None otherwise
129
    """
130

131
def get_cached_generator_env(self) -> dict[str, str] | None:
132
    """
133
    Return environment variables for cached generator.
134
    
135
    Returns:
136
    Dictionary of environment variables if available, None otherwise
137
    """
138
```
139

140
### Python Integration
141

142
Static methods for detecting Python configuration and integration with CMake builds.
143

144
```python { .api }
145
@staticmethod
146
def get_python_version() -> str:
147
    """
148
    Return current Python version string.
149
    
150
    Returns:
151
    Python version in format "major.minor"
152
    """
153

154
@staticmethod
155
def get_python_include_dir(python_version: str) -> str | None:
156
    """
157
    Return Python include directory path for given version.
158
    
159
    Parameters:
160
    - python_version: Python version string
161
    
162
    Returns:
163
    Path to Python include directory, None if not found
164
    """
165

166
@staticmethod
167
def get_python_library(python_version: str) -> str | None:
168
    """
169
    Return Python library path for given version.
170
    
171
    Parameters:
172
    - python_version: Python version string
173
    
174
    Returns:
175
    Path to Python library file, None if not found
176
    """
177

178
@staticmethod
179
def check_for_bad_installs() -> None:
180
    """
181
    Check for problematic Python installations.
182
    
183
    Validates Python installation and warns about known
184
    problematic configurations that may affect building.
185
    
186
    Raises:
187
    SKBuildError: If critical installation problems detected
188
    """
189
```
190

191
### Version Detection
192

193
Utility functions for CMake version detection and validation.
194

195
```python { .api }
196
def get_cmake_version(cmake_executable: str = CMAKE_DEFAULT_EXECUTABLE) -> str:
197
    """
198
    Execute CMake to extract version information.
199
    
200
    Parameters:
201
    - cmake_executable: Path to cmake executable
202
    
203
    Returns:
204
    CMake version string
205
    
206
    Raises:
207
    SKBuildError: If cmake executable not found or fails
208
    """
209
```
210

211
### Argument Utilities
212

213
Helper functions for processing CMake arguments and cache variables.
214

215
```python { .api }
216
def pop_arg(
217
    arg: str, 
218
    args: Sequence[str], 
219
    default: str | None = None
220
) -> tuple[list[str], str | None]:
221
    """
222
    Remove and return argument from argument list.
223
    
224
    Pops an argument from an argument list and returns the new list
225
    and the value of the argument if present, or default otherwise.
226
    
227
    Parameters:
228
    - arg: Argument name to find and remove
229
    - args: List of arguments to search
230
    - default: Default value if argument not found
231
    
232
    Returns:
233
    Tuple of (remaining_arguments, argument_value)
234
    """
235

236
def has_cmake_cache_arg(
237
    cmake_args: list[str], 
238
    arg_name: str, 
239
    arg_value: str | None = None
240
) -> bool:
241
    """
242
    Check if CMake cache argument exists in argument list.
243
    
244
    Return True if -D<arg_name>:TYPE=<arg_value> is found in cmake_args.
245
    If arg_value is None, return True only if -D<arg_name>: is found in the list.
246
    
247
    Parameters:
248
    - cmake_args: List of CMake arguments  
249
    - arg_name: Cache variable name to check
250
    - arg_value: Optional specific value to match
251
    
252
    Returns:
253
    True if argument found, False otherwise
254
    """
255
```
256

257
## Usage Examples
258

259
### Basic CMake Operations
260

261
```python
262
from skbuild.cmaker import CMaker
263
from skbuild.constants import CMAKE_DEFAULT_EXECUTABLE
264

265
# Initialize CMaker
266
cmaker = CMaker(CMAKE_DEFAULT_EXECUTABLE)
267

268
# Configure project
269
config_vars = cmaker.configure(
270
    clargs=["-DCMAKE_BUILD_TYPE=Release"],
271
    cmake_source_dir="src",
272
    languages=["C", "CXX"]
273
)
274

275
# Build project  
276
cmaker.make(config="Release", install_target="install")
277

278
# Install and get file list
279
installed_files = cmaker.install()
280
print(f"Installed {len(installed_files)} files")
281
```
282

283
### Advanced Configuration
284

285
```python
286
from skbuild.cmaker import CMaker, get_cmake_version
287
import os
288

289
# Check CMake version
290
cmake_exe = "/usr/local/bin/cmake"
291
version = get_cmake_version(cmake_exe)
292
print(f"Using CMake version: {version}")
293

294
# Initialize with custom executable
295
cmaker = CMaker(cmake_exe)
296

297
# Configure with custom environment
298
env_vars = {"CC": "gcc-9", "CXX": "g++-9"}
299
config_vars = cmaker.configure(
300
    clargs=[
301
        "-DCMAKE_BUILD_TYPE=Debug",
302
        "-DENABLE_TESTING=ON",
303
        f"-DPYTHON_EXECUTABLE={sys.executable}"
304
    ],
305
    generator_name="Unix Makefiles",
306
    cmake_source_dir="native",
307
    languages=["C", "CXX", "Fortran"]
308
)
309

310
# Build with parallel jobs
311
cmaker.make(
312
    clargs=["-j", "4"],
313
    config="Debug", 
314
    env=env_vars
315
)
316
```
317

318
### Cache Variable Access
319

320
```python
321
from skbuild.cmaker import CMaker
322

323
# Check cached values from previous builds
324
generator = CMaker.get_cached_generator_name()
325
if generator:
326
    print(f"Using cached generator: {generator}")
327

328
python_version = CMaker.get_python_version()
329
include_dir = CMaker.get_python_include_dir(python_version)
330
python_lib = CMaker.get_python_library(python_version)
331

332
print(f"Python {python_version}")
333
print(f"Include dir: {include_dir}")
334
print(f"Library: {python_lib}")
335
```