0
# Build System Integration
1

2
PEP 517 build backend support and integration with modern Python packaging workflows. SIP provides seamless integration with pip, build tools, and CI/CD systems through standardized Python packaging interfaces.
3

4
## Capabilities
5

6
### PEP 517 Build Backend
7

8
SIP implements the PEP 517 build backend interface, enabling integration with modern Python packaging tools.
9

10
```python { .api }
11
def build_sdist(sdist_directory, config_settings=None):
12
    """
13
    PEP 517 hook for building source distributions.
14
    
15
    Args:
16
        sdist_directory (str): Target directory for source distribution
17
        config_settings (dict, optional): Build configuration settings
18
        
19
    Returns:
20
        str: Filename of created source distribution
21
        
22
    Note:
23
        config_settings are currently ignored pending frontend support.
24
    """
25
    pass
26

27
def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
28
    """
29
    PEP 517 hook for building wheels.
30
    
31
    Args:
32
        wheel_directory (str): Target directory for wheel
33
        config_settings (dict, optional): Build configuration settings
34
        metadata_directory (str, optional): Directory containing prepared metadata
35
        
36
    Returns:
37
        str: Filename of created wheel
38
        
39
    Note:
40
        config_settings are currently ignored pending frontend support.
41
    """
42
    pass
43
```
44

45
### Build System Configuration
46

47
Configure SIP as build backend in pyproject.toml:
48

49
```toml
50
[build-system]
51
requires = ["sip"]
52
build-backend = "sipbuild.api"
53
```
54

55
### Factory Pattern Integration
56

57
SIP supports custom project and builder factories for extensibility:
58

59
```python { .api }
60
class CustomProject(AbstractProject):
61
    """Custom project implementation."""
62
    pass
63

64
class CustomBuilder(AbstractBuilder):
65
    """Custom builder implementation."""
66
    pass
67
```
68

69
**Configuration in pyproject.toml:**
70
```toml
71
[tool.sip.project]
72
project-factory = "mypackage:CustomProject"
73
builder-factory = "mypackage:CustomBuilder"
74
```
75

76
## Usage Examples
77

78
### Standard Package Build
79

80
**pyproject.toml:**
81
```toml
82
[build-system]
83
requires = ["sip", "setuptools"]
84
build-backend = "sipbuild.api"
85

86
[project]
87
name = "mypackage"
88
version = "1.0.0"
89
description = "Python bindings for MyLib"
90
requires-python = ">=3.5"
91

92
[tool.sip.project]
93
build-dir = "build"
94

95
[tool.sip.bindings.mymodule]
96
sip-files = ["mymodule.sip"]
97
include-dirs = ["/usr/include/mylib"]
98
libraries = ["mylib"]
99
```
100

101
**Build commands:**
102
```bash
103
# Build wheel with pip
104
pip wheel .
105

106
# Build with build tool
107
python -m build
108

109
# Install directly
110
pip install .
111
```
112

113
### Custom Build Process
114

115
```python
116
# custom_build.py
117
from sipbuild import AbstractProject, AbstractBuilder
118

119
class MyProject(AbstractProject):
120
    def setup(self):
121
        # Custom setup logic
122
        super().setup()
123
        print("Setting up custom project")
124
    
125
    def build(self):
126
        # Custom build logic
127
        print("Building with custom process")
128
        super().build()
129

130
class MyBuilder(AbstractBuilder):
131
    def build(self):
132
        # Custom builder logic
133
        print("Using custom builder")
134
        super().build()
135
```
136

137
**pyproject.toml:**
138
```toml
139
[build-system]
140
requires = ["sip"]
141
build-backend = "sipbuild.api"
142

143
[tool.sip.project]
144
project-factory = "custom_build:MyProject"
145
builder-factory = "custom_build:MyBuilder"
146
```
147

148
### CI/CD Integration
149

150
**GitHub Actions example:**
151
```yaml
152
name: Build and Test
153
on: [push, pull_request]
154

155
jobs:
156
  build:
157
    runs-on: ubuntu-latest
158
    steps:
159
    - uses: actions/checkout@v2
160
    
161
    - name: Set up Python
162
      uses: actions/setup-python@v2
163
      with:
164
        python-version: '3.9'
165
    
166
    - name: Install dependencies
167
      run: |
168
        pip install build sip
169
    
170
    - name: Build package
171
      run: python -m build
172
    
173
    - name: Test installation
174
      run: |
175
        pip install dist/*.whl
176
        python -c "import mymodule; print('Success!')"
177
```
178

179
### Multi-Platform Builds
180

181
**pyproject.toml with platform-specific configuration:**
182
```toml
183
[tool.sip.project]
184
build-dir = "build"
185

186
# Windows-specific settings
187
[tool.sip.project.win32]
188
include-dirs = ["C:/MyLib/include"]
189
library-dirs = ["C:/MyLib/lib"]
190

191
# Linux-specific settings  
192
[tool.sip.project.linux]
193
include-dirs = ["/usr/include/mylib"]
194
library-dirs = ["/usr/lib"]
195

196
# macOS-specific settings
197
[tool.sip.project.darwin]
198
include-dirs = ["/usr/local/include/mylib"]
199
library-dirs = ["/usr/local/lib"]
200
```
201

202
## Build Pipeline
203

204
### Standard Build Process
205

206
1. **Configuration**: Load pyproject.toml and apply settings
207
2. **Bootstrap**: Create project and builder instances
208
3. **Generation**: Process .sip files into C/C++ source
209
4. **Compilation**: Compile generated source into extension modules
210
5. **Packaging**: Create wheel or sdist with proper metadata
211

212
### Error Handling
213

214
Build process errors are handled through SIP's standard exception system:
215

216
```python
217
from sipbuild import handle_exception
218

219
try:
220
    # Build process
221
    project.build_wheel(wheel_directory)
222
except Exception as e:
223
    # Standard error handling and user-friendly messages
224
    handle_exception(e)
225
```
226

227
### Build Artifacts
228

229
SIP generates several types of build artifacts:
230

231
- **Extension modules** (.so/.pyd files) - Compiled binding code
232
- **sip module** - Runtime support module
233
- **Type stubs** (.pyi files) - Type information for IDEs
234
- **Documentation** - API documentation and usage examples
235
- **Metadata** - Package information and dependencies
236

237
## Integration with Package Managers
238

239
### pip Integration
240

241
```bash
242
# Install from source with pip
243
pip install .
244

245
# Install in development mode
246
pip install -e .
247

248
# Build wheel and install
249
pip wheel . && pip install *.whl
250
```
251

252
### conda Integration
253

254
**conda recipe example:**
255
```yaml
256
package:
257
  name: mypackage
258
  version: {{ environ.get('GIT_DESCRIBE_TAG', 'dev') }}
259

260
source:
261
  path: ..
262

263
build:
264
  script: {{ PYTHON }} -m pip install . -vv
265
  number: 0
266

267
requirements:
268
  build:
269
    - python
270
    - pip
271
    - sip
272
  run:
273
    - python
274

275
test:
276
  imports:
277
    - mymodule
278
```
279

280
### setuptools Compatibility
281

282
SIP maintains compatibility with setuptools-based workflows:
283

284
```python
285
# setup.py (legacy compatibility)
286
from setuptools import setup
287
from sipbuild import Project
288

289
# Use SIP project configuration
290
project = Project()
291
setup(
292
    name=project.name,
293
    version=project.version,
294
    ext_modules=project.get_bindings_modules()
295
)
296
```
297

298
This integration approach ensures SIP projects work seamlessly with existing Python packaging infrastructure while providing modern PEP 517 compliance.