0
# CMake
1
2
CMake is an open-source, cross-platform family of tools designed to build, test and package software. This Python distribution provides a convenient way to install CMake via pip and execute CMake commands through Python wrapper functions.
3
4
## Package Information
5
6
- **Package Name**: cmake
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install cmake`
10
11
## Core Imports
12
13
```python
14
import cmake
15
```
16
17
For accessing constants:
18
19
```python
20
from cmake import CMAKE_BIN_DIR, CMAKE_DATA, CMAKE_DOC_DIR, CMAKE_SHARE_DIR
21
```
22
23
For accessing command functions:
24
25
```python
26
from cmake import cmake, cpack, ctest, ccmake
27
```
28
29
## Basic Usage
30
31
```python
32
import cmake
33
import sys
34
35
# Execute cmake directly (equivalent to running cmake command-line tool)
36
# This will execute cmake with any command-line arguments provided to the script
37
cmake.cmake()
38
39
# Execute other CMake tools
40
cmake.cpack() # Package generation tool
41
cmake.ctest() # Testing tool
42
cmake.ccmake() # GUI configuration tool
43
44
# Access CMake installation paths
45
print(f"CMake binary directory: {cmake.CMAKE_BIN_DIR}")
46
print(f"CMake data directory: {cmake.CMAKE_DATA}")
47
print(f"CMake documentation directory: {cmake.CMAKE_DOC_DIR}")
48
print(f"CMake share directory: {cmake.CMAKE_SHARE_DIR}")
49
```
50
51
## Architecture
52
53
The cmake package provides Python wrapper functions that execute the corresponding native CMake binaries. The package automatically locates the CMake installation within the Python package and provides path constants for accessing different components of the CMake installation.
54
55
## Capabilities
56
57
### Command Execution Functions
58
59
These functions execute the corresponding CMake command-line tools, passing through all command-line arguments from `sys.argv[1:]`. Each function replaces the current process with the CMake binary (on Unix-like systems) or exits with the binary's return code (on Windows).
60
61
```python { .api }
62
def cmake():
63
"""
64
Execute the cmake binary with command-line arguments.
65
66
This function does not return normally - it either replaces the current
67
process with cmake (Unix) or raises SystemExit with cmake's exit code (Windows).
68
69
Returns:
70
NoReturn: Function does not return normally
71
"""
72
73
def cpack():
74
"""
75
Execute the cpack (CMake packaging) binary with command-line arguments.
76
77
This function does not return normally - it either replaces the current
78
process with cpack (Unix) or raises SystemExit with cpack's exit code (Windows).
79
80
Returns:
81
NoReturn: Function does not return normally
82
"""
83
84
def ctest():
85
"""
86
Execute the ctest (CMake testing) binary with command-line arguments.
87
88
This function does not return normally - it either replaces the current
89
process with ctest (Unix) or raises SystemExit with ctest's exit code (Windows).
90
91
Returns:
92
NoReturn: Function does not return normally
93
"""
94
95
def ccmake():
96
"""
97
Execute the ccmake (CMake GUI) binary with command-line arguments.
98
99
This function does not return normally - it either replaces the current
100
process with ccmake (Unix) or raises SystemExit with ccmake's exit code (Windows).
101
102
Returns:
103
NoReturn: Function does not return normally
104
"""
105
```
106
107
### Path Constants
108
109
These constants provide access to the CMake installation paths within the Python package.
110
111
```python { .api }
112
CMAKE_BIN_DIR: str
113
"""
114
Path to the CMake binary directory containing cmake, cpack, ctest, and ccmake executables.
115
116
Type: str
117
"""
118
119
CMAKE_DATA: str
120
"""
121
Path to the base CMake data directory. This is the root directory of the CMake installation
122
within the Python package.
123
124
Type: str
125
"""
126
127
CMAKE_DOC_DIR: str
128
"""
129
Path to the CMake documentation directory containing CMake help files and documentation.
130
131
Type: str
132
"""
133
134
CMAKE_SHARE_DIR: str
135
"""
136
Path to the CMake share directory containing modules, templates, and other shared resources.
137
138
Type: str
139
"""
140
141
__version__: str
142
"""
143
The version of the cmake package.
144
145
Type: str
146
"""
147
```
148
149
## Usage Examples
150
151
### Running CMake Commands
152
153
```python
154
# In a script that needs to run cmake
155
import cmake
156
import sys
157
158
# Add cmake arguments to sys.argv before calling
159
sys.argv = ['script.py', '--version']
160
cmake.cmake() # Executes: cmake --version
161
```
162
163
### Accessing CMake Installation Paths
164
165
```python
166
import cmake
167
import os
168
169
# Get path to cmake binary
170
cmake_binary = os.path.join(cmake.CMAKE_BIN_DIR, 'cmake')
171
172
# Access CMake modules directory
173
cmake_modules = os.path.join(cmake.CMAKE_SHARE_DIR, 'cmake', 'Modules')
174
175
# Check if documentation exists
176
doc_exists = os.path.exists(cmake.CMAKE_DOC_DIR)
177
```
178
179
### Using as Command-Line Module
180
181
The package can also be executed as a module:
182
183
```bash
184
python -m cmake --version
185
```
186
187
This is equivalent to calling `cmake.cmake()` directly.
188
189
## Console Scripts
190
191
When installed, the package provides console scripts that can be executed directly from the command line:
192
193
- `cmake` - Executes the cmake binary
194
- `cpack` - Executes the cpack binary
195
- `ctest` - Executes the ctest binary
196
- `ccmake` - Executes the ccmake binary
197
198
These scripts are automatically installed when the package is installed via pip and are equivalent to calling the corresponding Python functions.
199
200
## Error Handling
201
202
All command execution functions (`cmake`, `cpack`, `ctest`, `ccmake`) handle errors by:
203
204
1. **Exit codes**: The functions exit with the same exit code as the underlying CMake binary
205
2. **SystemExit**: On Windows, functions raise `SystemExit` with the binary's return code
206
3. **Process replacement**: On Unix-like systems, functions replace the current process with the CMake binary using `os.execl`
207
208
No custom exceptions are raised by the package itself - all error handling is delegated to the underlying CMake binaries.
209
210
## Platform Support
211
212
The package works across all platforms supported by CMake:
213
214
- **Windows**: Uses `subprocess.call` and `SystemExit` for command execution
215
- **Unix-like systems** (Linux, macOS): Uses `os.execl` for efficient process replacement
216
- **All platforms**: Path constants work consistently across operating systems