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