0
# Architecture Management
1

2
Cibuildwheel provides comprehensive architecture support with automatic detection, cross-compilation capabilities, and architecture-specific build configuration.
3

4
## Capabilities
5

6
### Architecture Enumeration
7

8
Complete enumeration of all supported CPU architectures across platforms.
9

10
```python { .api }
11
class Architecture(StrEnum):
12
    # Cross-platform architectures
13
    x86_64 = "x86_64"
14
    
15
    # Linux-specific architectures  
16
    i686 = "i686"
17
    aarch64 = "aarch64"
18
    ppc64le = "ppc64le"
19
    s390x = "s390x"
20
    armv7l = "armv7l"
21
    riscv64 = "riscv64"
22
    
23
    # macOS-specific architectures
24
    universal2 = "universal2"
25
    arm64 = "arm64"
26
    
27
    # Windows-specific architectures
28
    x86 = "x86"
29
    AMD64 = "AMD64"
30
    ARM64 = "ARM64"
31
    
32
    # WebAssembly architecture
33
    wasm32 = "wasm32"
34
    
35
    # Android architecture
36
    arm64_v8a = "arm64_v8a"
37
    
38
    # iOS architectures
39
    arm64_iphoneos = "arm64_iphoneos"
40
    arm64_iphonesimulator = "arm64_iphonesimulator"
41
    x86_64_iphonesimulator = "x86_64_iphonesimulator"
42
```
43

44
### Architecture Configuration Parsing
45

46
Parse architecture specifications from configuration strings.
47

48
```python { .api }
49
@staticmethod
50
def parse_config(config: str, platform: PlatformName) -> set[Architecture]:
51
    """
52
    Parse architecture configuration string for a specific platform.
53
    
54
    Args:
55
        config: Architecture specification string (e.g., "x86_64,aarch64" or "auto")
56
        platform: Target platform name
57
        
58
    Returns:
59
        Set of Architecture enums matching the specification
60
        
61
    Raises:
62
        ConfigurationError: If architecture specification is invalid
63
    """
64
```
65

66
### Native Architecture Detection
67

68
Detect the native architecture of the current system.
69

70
```python { .api }
71
@staticmethod  
72
def native_arch(platform: PlatformName) -> Architecture | None:
73
    """
74
    Get the native architecture for the specified platform.
75
    
76
    Args:
77
        platform: Target platform name
78
        
79
    Returns:
80
        Native Architecture for the platform, or None if not determinable
81
    """
82
```
83

84
### Automatic Architecture Selection
85

86
Get architecture sets based on automatic selection criteria.
87

88
```python { .api }
89
@staticmethod
90
def auto_archs(platform: PlatformName) -> set[Architecture]:
91
    """
92
    Get the set of architectures that would be built by default ('auto').
93
    
94
    Args:
95
        platform: Target platform name
96
        
97
    Returns:
98
        Set of architectures for automatic builds on this platform
99
    """
100

101
@staticmethod
102
def all_archs(platform: PlatformName) -> set[Architecture]:
103
    """
104
    Get all supported architectures for a platform.
105
    
106
    Args:
107
        platform: Target platform name
108
        
109
    Returns:
110
        Set of all supported architectures for this platform
111
    """
112

113
@staticmethod
114
def bitness_archs(platform: PlatformName, bitness: Literal["64", "32"]) -> set[Architecture]:
115
    """
116
    Get architectures by bit width for a platform.
117
    
118
    Args:
119
        platform: Target platform name
120
        bitness: Either "64" for 64-bit or "32" for 32-bit architectures
121
        
122
    Returns:
123
        Set of architectures matching the specified bit width
124
    """
125
```
126

127
### Architecture Translation
128

129
Convert architecture names between different platform naming conventions.
130

131
```python { .api }
132
def arch_synonym(arch: str, from_platform: PlatformName, to_platform: PlatformName) -> str | None:
133
    """
134
    Translate architecture name from one platform's convention to another's.
135
    
136
    Args:
137
        arch: Architecture name in source platform's convention
138
        from_platform: Source platform
139
        to_platform: Target platform
140
        
141
    Returns:
142
        Architecture name in target platform's convention, or None if no translation exists
143
    """
144
```
145

146
### Architecture Validation
147

148
Validate that architectures are supported on the target platform.
149

150
```python { .api }
151
def allowed_architectures_check(platform: PlatformName, architectures: set[Architecture]) -> None:
152
    """
153
    Validate that all specified architectures are supported on the platform.
154
    
155
    Args:
156
        platform: Target platform name
157
        architectures: Set of architectures to validate
158
        
159
    Raises:
160
        ValueError: If any architecture is not supported on the platform
161
    """
162
```
163

164
## Architecture Support by Platform
165

166
### Linux Architectures
167

168
- **x86_64**: Primary 64-bit Intel/AMD architecture
169
- **i686**: 32-bit Intel/AMD architecture  
170
- **aarch64**: 64-bit ARM architecture (ARMv8)
171
- **ppc64le**: 64-bit PowerPC Little Endian
172
- **s390x**: IBM System z (s390x) 64-bit
173
- **armv7l**: 32-bit ARM architecture (experimental, Ubuntu-based)
174
- **riscv64**: RISC-V 64-bit architecture (experimental)
175

176
### macOS Architectures
177

178
- **x86_64**: Intel-based Macs (64-bit)
179
- **arm64**: Apple Silicon Macs (M1, M2, etc.)
180
- **universal2**: Universal binary containing both x86_64 and arm64
181

182
### Windows Architectures
183

184
- **AMD64**: 64-bit Windows (x86_64 equivalent)
185
- **x86**: 32-bit Windows
186
- **ARM64**: Windows on ARM 64-bit (experimental)
187

188
### WebAssembly Architectures
189

190
- **wasm32**: WebAssembly 32-bit target for Pyodide
191

192
### Mobile Architectures
193

194
- **arm64_v8a**: Android 64-bit ARM
195
- **arm64_iphoneos**: iOS devices (ARM64)
196
- **arm64_iphonesimulator**: iOS Simulator on Apple Silicon
197
- **x86_64_iphonesimulator**: iOS Simulator on Intel Macs
198

199
## Configuration Examples
200

201
### Architecture Selection
202

203
```python
204
# Configuration string parsing
205
from cibuildwheel.architecture import Architecture
206

207
# Parse specific architectures
208
archs = Architecture.parse_config("x86_64,aarch64", "linux")
209
# Returns: {Architecture.x86_64, Architecture.aarch64}
210

211
# Parse automatic selection
212
archs = Architecture.parse_config("auto", "linux") 
213
# Returns: {Architecture.x86_64} (on x86_64 host)
214

215
# Parse all architectures
216
archs = Architecture.parse_config("all", "linux")
217
# Returns: {Architecture.x86_64, Architecture.i686, Architecture.aarch64, ...}
218
```
219

220
### Platform-Specific Defaults
221

222
```python
223
# Get default architectures for each platform
224
linux_auto = Architecture.auto_archs("linux")       # {x86_64} on x86_64 host
225
macos_auto = Architecture.auto_archs("macos")        # {x86_64} on Intel, {arm64} on Apple Silicon
226
windows_auto = Architecture.auto_archs("windows")   # {AMD64} on 64-bit, {x86} on 32-bit
227
```
228

229
### Cross-Compilation Setup
230

231
```python
232
# Linux cross-compilation (requires emulation)
233
CIBW_ARCHS_LINUX = "x86_64 aarch64 ppc64le"
234

235
# macOS universal binaries
236
CIBW_ARCHS_MACOS = "universal2"
237

238
# Windows cross-compilation
239
CIBW_ARCHS_WINDOWS = "AMD64 ARM64"
240
```
241

242
### Architecture Validation
243

244
```python
245
from cibuildwheel.architecture import allowed_architectures_check, Architecture
246

247
# Validate architecture support
248
try:
249
    allowed_architectures_check("linux", {Architecture.x86_64, Architecture.aarch64})
250
    # Success - both architectures supported on Linux
251
except ValueError as e:
252
    print(f"Architecture validation failed: {e}")
253

254
# This would raise an error
255
try:
256
    allowed_architectures_check("windows", {Architecture.aarch64})
257
    # ValueError - aarch64 not supported on Windows (use ARM64 instead)
258
except ValueError:
259
    pass
260
```
261

262
### Architecture Translation
263

264
```python
265
from cibuildwheel.architecture import arch_synonym
266

267
# Translate between platform conventions
268
windows_arch = arch_synonym("x86_64", "linux", "windows")
269
# Returns: "AMD64"
270

271
linux_arch = arch_synonym("AMD64", "windows", "linux") 
272
# Returns: "x86_64"
273

274
ios_arch = arch_synonym("arm64", "macos", "ios")
275
# Returns: "arm64_iphoneos"
276
```
277

278
## Advanced Architecture Features
279

280
### Emulation Support
281

282
Cibuildwheel supports cross-compilation through emulation on Linux:
283

284
- **QEMU/binfmt_misc**: Automatic emulation of foreign architectures
285
- **Docker Buildx**: Multi-architecture container builds
286
- **Performance**: Emulated builds are slower but provide full compatibility
287

288
### Universal Binaries (macOS)
289

290
The `universal2` architecture creates fat binaries containing both Intel and Apple Silicon code:
291

292
```python
293
# Build universal binaries
294
CIBW_ARCHS_MACOS = "universal2"
295

296
# Or build separate architectures and combine later
297
CIBW_ARCHS_MACOS = "x86_64 arm64"
298
```
299

300
### Architecture-Specific Configuration
301

302
Different configurations can be applied per architecture:
303

304
```toml
305
[tool.cibuildwheel.linux]
306
archs = ["x86_64", "aarch64"]
307

308
[tool.cibuildwheel.windows]  
309
archs = ["AMD64"]
310
skip = ["*-win32"]  # Skip 32-bit builds
311

312
[tool.cibuildwheel.macos]
313
archs = ["universal2"]
314
```