0
# Exception Handling
1

2
Exception classes for error handling during CMake configuration, building, and installation processes. Provides specific error types for different failure scenarios in the scikit-build workflow.
3

4
## Capabilities
5

6
### Base Exception
7

8
Base exception class for all scikit-build related errors, providing a common interface for error handling in the build process.
9

10
```python { .api }
11
class SKBuildError(RuntimeError):
12
    """
13
    Base exception for all scikit-build errors.
14
    
15
    Raised when an error occurs during project configuration, building,
16
    or installation that is specific to scikit-build operations.
17
    
18
    Inherits from RuntimeError to maintain compatibility with standard
19
    Python exception handling patterns.
20
    """
21
```
22

23
### File Installation Errors
24

25
Exception for errors related to file installation and deployment during the build process.
26

27
```python { .api }
28
class SKBuildInvalidFileInstallationError(SKBuildError):
29
    """
30
    Exception raised when a file is being installed into an invalid location.
31
    
32
    This error occurs when CMake or the build process attempts to install
33
    files to locations that are not permitted or expected, such as:
34
    - Installing outside the designated installation directory
35
    - Overwriting system files
36
    - Installing to read-only locations
37
    - Path traversal attempts in installation paths
38
    
39
    Inherits from SKBuildError.
40
    """
41
```
42

43
### Generator Detection Errors
44

45
Exception for errors related to CMake generator detection and selection.
46

47
```python { .api }
48
class SKBuildGeneratorNotFoundError(SKBuildError):
49
    """
50
    Exception raised when no suitable CMake generator is found for the platform.
51
    
52
    This error occurs when scikit-build cannot find or select an appropriate
53
    CMake generator for the current platform and build environment. Common
54
    scenarios include:
55
    - No compatible build tools installed (Make, Ninja, Visual Studio, etc.)
56
    - Requested generator not available on the platform
57
    - Generator compatibility test failures
58
    - Missing dependencies for the selected generator
59
    
60
    Inherits from SKBuildError.
61
    """
62
```
63

64
## Usage Examples
65

66
### Basic Error Handling
67

68
```python
69
from skbuild import setup
70
from skbuild.exceptions import SKBuildError, SKBuildGeneratorNotFoundError
71

72
try:
73
    setup(
74
        name="my-extension",
75
        cmake_source_dir="src",
76
        cmake_args=["-G", "Ninja"],  # Force Ninja generator
77
    )
78
except SKBuildGeneratorNotFoundError as e:
79
    print(f"Generator error: {e}")
80
    print("Please install Ninja build system or use a different generator")
81
    sys.exit(1)
82
except SKBuildError as e:
83
    print(f"Build error: {e}")
84
    sys.exit(1)
85
```
86

87
### Specific Exception Handling
88

89
```python
90
from skbuild.exceptions import (
91
    SKBuildError, 
92
    SKBuildInvalidFileInstallationError,
93
    SKBuildGeneratorNotFoundError
94
)
95
from skbuild.cmaker import CMaker
96

97
try:
98
    cmaker = CMaker()
99
    cmaker.configure(generator_name="Unix Makefiles")
100
    cmaker.make()
101
    installed_files = cmaker.install()
102
    
103
except SKBuildGeneratorNotFoundError:
104
    print("No suitable build system found.")
105
    print("Please install make, ninja, or other build tools.")
106
    
107
except SKBuildInvalidFileInstallationError as e:
108
    print(f"Invalid file installation: {e}")
109
    print("Check CMake install targets and file permissions.")
110
    
111
except SKBuildError as e:
112
    print(f"General scikit-build error: {e}")
113
    print("Check CMakeLists.txt and build configuration.")
114
```
115

116
### Error Context and Debugging
117

118
```python
119
import traceback
120
from skbuild import setup
121
from skbuild.exceptions import SKBuildError
122

123
try:
124
    setup(
125
        name="problematic-extension",
126
        cmake_source_dir="src",
127
        cmake_args=[
128
            "-DCMAKE_BUILD_TYPE=Debug",
129
            "-DCMAKE_VERBOSE_MAKEFILE=ON"  # Enable verbose output for debugging
130
        ]
131
    )
132
except SKBuildError as e:
133
    print(f"Error during build: {e}")
134
    print("\nFull traceback:")
135
    traceback.print_exc()
136
    
137
    # Additional debugging information
138
    print("\nDebugging tips:")
139
    print("1. Check that CMakeLists.txt exists in the source directory")
140
    print("2. Verify CMake version compatibility") 
141
    print("3. Check for missing dependencies or build tools")
142
    print("4. Review CMake error messages in build output")
143
```
144

145
### Conditional Error Handling
146

147
```python
148
from skbuild.exceptions import SKBuildError
149
from skbuild.constants import get_cmake_version, CMAKE_DEFAULT_EXECUTABLE
150
from packaging.version import Version
151
import sys
152

153
def safe_setup(**kwargs):
154
    """Setup with comprehensive error handling."""
155
    try:
156
        # Check CMake version before attempting build
157
        cmake_version = get_cmake_version(CMAKE_DEFAULT_EXECUTABLE)
158
        min_version = Version("3.12.0")
159
        
160
        if cmake_version < min_version:
161
            raise SKBuildError(
162
                f"CMake {min_version} or later required, found {cmake_version}"
163
            )
164
        
165
        from skbuild import setup
166
        return setup(**kwargs)
167
        
168
    except FileNotFoundError:
169
        print("Error: CMake not found. Please install CMake.")
170
        sys.exit(1)
171
        
172
    except SKBuildError as e:
173
        print(f"Build failed: {e}")
174
        
175
        # Provide helpful error messages based on error content
176
        error_msg = str(e).lower()
177
        if "generator" in error_msg:
178
            print("Tip: Try installing build tools (make, ninja, visual studio)")
179
        elif "cmake" in error_msg and "version" in error_msg:
180
            print("Tip: Update CMake to a newer version")
181
        elif "permission" in error_msg:
182
            print("Tip: Check file permissions and installation directories")
183
            
184
        sys.exit(1)
185

186
# Usage
187
safe_setup(
188
    name="my-package",
189
    cmake_source_dir="native",
190
    packages=["my_package"]
191
)
192
```
193

194
### Custom Error Handling
195

196
```python
197
from skbuild.exceptions import SKBuildError
198

199
class CustomBuildError(SKBuildError):
200
    """Custom exception for project-specific build errors."""
201
    pass
202

203
def validate_build_environment():
204
    """Validate build environment before setup."""
205
    import os
206
    import shutil
207
    
208
    # Check for required tools
209
    if not shutil.which("cmake"):
210
        raise CustomBuildError("CMake not found in PATH")
211
        
212
    if not os.path.exists("CMakeLists.txt"):
213
        raise CustomBuildError("CMakeLists.txt not found in project root")
214
        
215
    # Check for required dependencies
216
    required_libs = ["libssl-dev", "libffi-dev"]  # Example
217
    # ... dependency checking logic ...
218

219
try:
220
    validate_build_environment()
221
    
222
    from skbuild import setup
223
    setup(name="validated-package")
224
    
225
except CustomBuildError as e:
226
    print(f"Environment validation failed: {e}")
227
    sys.exit(1)
228
except SKBuildError as e:
229
    print(f"Build error: {e}")
230
    sys.exit(1)
231
```