0
# Build System
1

2
The Cython build system provides tools for converting .pyx files into compiled extension modules. The core function `cythonize` handles the compilation process, while additional utilities support setuptools integration, parallel compilation, and advanced build configuration.
3

4
## Capabilities
5

6
### Core Build Function
7

8
The main entry point for building Cython extensions from source files.
9

10
```python { .api }
11
def cythonize(module_list, exclude=None, nthreads=0, aliases=None, 
12
              quiet=False, force=None, language=None, 
13
              exclude_failures=False, show_all_warnings=False, **options):
14
    """Convert .pyx files to Extension objects for compilation.
15
    
16
    Args:
17
        module_list: List of .pyx files, glob patterns, or Extension objects
18
        exclude: List of file patterns to exclude from compilation
19
        nthreads: Number of parallel compilation threads (0 = CPU count)
20
        aliases: Dict mapping import names to file paths
21
        quiet: Suppress compilation output messages
22
        force: Force recompilation even if files haven't changed (None = auto-detect)
23
        language: Target language ('c' or 'c++')
24
        exclude_failures: Continue compilation despite individual file failures
25
        show_all_warnings: Show all compiler warnings including normally suppressed ones
26
        **options: Additional compiler options and directives
27
    
28
    Returns:
29
        List of Extension objects ready for distutils/setuptools
30
    """
31
```
32

33
### Distutils Integration
34

35
Classes for integrating Cython compilation with Python's distutils and setuptools.
36

37
```python { .api }
38
class build_ext:
39
    """Enhanced build_ext command with Cython support.
40
    
41
    Extends distutils.command.build_ext.build_ext to automatically
42
    compile .pyx files and handle Cython-specific build requirements.
43
    """
44

45
class Extension:
46
    """Extension class with Cython-specific features.
47
    
48
    Extends distutils.extension.Extension with support for Cython
49
    directives, include directories, and compilation options.
50
    """
51
```
52

53
## Usage Examples
54

55
### Basic setuptools Integration
56

57
```python
58
from setuptools import setup
59
from Cython.Build import cythonize
60

61
setup(
62
    name="my_package",
63
    ext_modules=cythonize("src/*.pyx")
64
)
65
```
66

67
### Advanced Build Configuration
68

69
```python
70
from setuptools import setup, Extension
71
from Cython.Build import cythonize
72
import numpy
73

74
# Define extensions with specific options
75
extensions = [
76
    Extension(
77
        "my_module.fast_math",
78
        ["my_module/fast_math.pyx"],
79
        include_dirs=[numpy.get_include()],
80
        define_macros=[("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")],
81
        extra_compile_args=["-O3"],
82
    )
83
]
84

85
setup(
86
    name="my_package", 
87
    ext_modules=cythonize(
88
        extensions,
89
        compiler_directives={
90
            'language_level': 3,
91
            'boundscheck': False,
92
            'wraparound': False,
93
            'cdivision': True,
94
        }
95
    )
96
)
97
```
98

99
### Parallel Compilation
100

101
```python
102
from setuptools import setup
103
from Cython.Build import cythonize
104
import multiprocessing
105

106
setup(
107
    name="my_package",
108
    ext_modules=cythonize(
109
        "src/*.pyx",
110
        nthreads=multiprocessing.cpu_count(),  # Use all CPU cores
111
        quiet=False,  # Show compilation progress
112
        force=True,   # Force recompilation
113
    )
114
)
115
```
116

117
### Conditional Compilation
118

119
```python
120
from setuptools import setup
121
from Cython.Build import cythonize
122
import os
123

124
# Use different compiler directives for debug vs release
125
debug_mode = os.environ.get('DEBUG', '0') == '1'
126

127
compiler_directives = {
128
    'language_level': 3,
129
    'boundscheck': debug_mode,
130
    'wraparound': debug_mode, 
131
    'cdivision': not debug_mode,
132
    'profile': debug_mode,
133
    'linetrace': debug_mode,
134
}
135

136
setup(
137
    name="my_package",
138
    ext_modules=cythonize(
139
        "src/*.pyx",
140
        compiler_directives=compiler_directives,
141
        gdb_debug=debug_mode,
142
    )
143
)
144
```
145

146
### Language Selection
147

148
```python
149
from setuptools import setup
150
from Cython.Build import cythonize
151

152
# Compile to C++
153
setup(
154
    name="my_cpp_package",
155
    ext_modules=cythonize(
156
        "src/*.pyx",
157
        language="c++",
158
        compiler_directives={'language_level': 3}
159
    )
160
)
161
```
162

163
### Build with NumPy Integration
164

165
```python
166
from setuptools import setup
167
from Cython.Build import cythonize
168
import numpy
169

170
setup(
171
    name="numeric_package",
172
    ext_modules=cythonize([
173
        Extension(
174
            "numeric_package.algorithms",
175
            ["numeric_package/algorithms.pyx"],
176
            include_dirs=[numpy.get_include()],
177
        )
178
    ]),
179
    install_requires=["numpy"]
180
)
181
```
182

183
### Excluding Files and Error Handling
184

185
```python
186
from setuptools import setup
187
from Cython.Build import cythonize
188

189
setup(
190
    name="my_package",
191
    ext_modules=cythonize(
192
        "src/**/*.pyx",
193
        exclude=["src/tests/*.pyx", "src/experimental/*.pyx"],
194
        exclude_failures=True,  # Continue despite individual file failures
195
        quiet=True,
196
    )
197
)
198
```
199

200
### Using Cython Distutils Directly
201

202
```python
203
from distutils.core import setup
204
from Cython.Distutils import build_ext
205
from Cython.Distutils.extension import Extension
206

207
setup(
208
    name="legacy_package",
209
    cmdclass={'build_ext': build_ext},
210
    ext_modules=[
211
        Extension("my_module", ["my_module.pyx"])
212
    ]
213
)
214
```