0
# Command Line Tools
1
2
Cython provides three main command line tools for compiling, building, and debugging Cython code. These tools offer complete control over the compilation process and support various output formats and optimization levels.
3
4
## Capabilities
5
6
### cython - Cython Compiler
7
8
The main Cython compiler that converts .pyx files to C/C++ source code.
9
10
```bash { .api }
11
cython [options] sourcefile.pyx
12
13
Options:
14
-o FILE, --output-file FILE Output file name
15
-D, --output-dir DIR Output directory
16
-3 Compile for Python 3
17
-2 Compile for Python 2
18
--cplus Generate C++ code
19
-X DIRECTIVE Set compiler directive
20
-E, --directive DIRECTIVE Set compiler directive (alternative form)
21
-s, --option OPTION Set compiler option
22
-p, --embed-pos-in-filename Embed source position in filename
23
-z, --pre-import MODULE Pre-import module
24
--cleanup LEVEL Cleanup intermediate files (0-3)
25
-w, --working DIR Working directory
26
-v, --verbose Verbose output
27
-l, --include-dir DIR Add include directory
28
-I DIR Add include directory (alternative)
29
--gdb Generate debugging information
30
--gdb-outdir DIR GDB debugging output directory
31
-a, --annotate Generate annotated HTML output
32
--annotate-coverage COVERAGE Use coverage data for annotation
33
-f, --force Force recompilation
34
--timestamps Only compile newer sources
35
-q, --quiet Quiet operation
36
--fast-fail Stop on first error
37
--warning-errors Treat warnings as errors
38
--Werror Treat warnings as errors (alternative)
39
-M Generate dependency file
40
--depfile FILE Dependency output file
41
```
42
43
### cythonize - Build Tool
44
45
High-level build tool that compiles .pyx files into extension modules ready for installation.
46
47
```bash { .api }
48
cythonize [options] sources...
49
50
Positional arguments:
51
sources Source files (.pyx, .py) or glob patterns
52
53
Options:
54
-b, --build Build extension modules
55
-i, --inplace Build extensions in-place
56
-j N, --parallel N Parallel compilation (N processes)
57
-f, --force Force recompilation
58
-q, --quiet Quiet operation
59
-k, --keep-going Continue despite errors
60
-X DIRECTIVE Set compiler directive
61
--lenient Lenient error handling
62
--no-docstrings Remove docstrings
63
-M Generate dependency files
64
--depfile Dependency file template
65
-s OPTION Set compiler option
66
--annotate Generate annotated HTML
67
-3 Compile for Python 3
68
-2 Compile for Python 2
69
--cplus Generate C++ code
70
--fast-fail Stop on first error
71
--verbose Verbose output
72
-h, --help Show help
73
```
74
75
### cygdb - Cython Debugger
76
77
GDB-based debugger for Cython code that allows debugging both Python and C-level code.
78
79
```bash { .api }
80
cygdb [options] [path-to-project-directory] [gdb-args...]
81
82
Positional arguments:
83
path-to-project-directory Path to project with cython_debug/ directory
84
gdb-args Additional arguments passed to GDB
85
86
Options:
87
--gdb-executable GDB GDB executable to use (default: gdb)
88
--verbose Verbose output
89
-h, --help Show help
90
```
91
92
## Usage Examples
93
94
### Basic Compilation
95
96
```bash
97
# Compile a single .pyx file to C
98
cython my_module.pyx
99
100
# Compile for Python 3 with C++ output
101
cython -3 --cplus my_module.pyx -o my_module.cpp
102
103
# Generate annotated HTML for performance analysis
104
cython -a my_module.pyx
105
```
106
107
### Advanced Compilation Options
108
109
```bash
110
# Compile with specific directives
111
cython -X boundscheck=False -X wraparound=False my_module.pyx
112
113
# Include debugging information
114
cython --gdb my_module.pyx
115
116
# Compile with custom include directories
117
cython -I /usr/local/include -I ./headers my_module.pyx
118
119
# Generate dependency files
120
cython -M --depfile my_module.dep my_module.pyx
121
```
122
123
### Building Extensions with cythonize
124
125
```bash
126
# Build extension module in-place
127
cythonize -i my_module.pyx
128
129
# Build with parallel compilation
130
cythonize -j 4 -b src/*.pyx
131
132
# Build with specific Python version
133
cythonize -3 -b my_module.pyx
134
135
# Build C++ extensions
136
cythonize --cplus -b *.pyx
137
```
138
139
### Advanced Build Configuration
140
141
```bash
142
# Force rebuild with annotations
143
cythonize -f --annotate -b my_module.pyx
144
145
# Build with compiler directives
146
cythonize -X language_level=3 -X boundscheck=False -b *.pyx
147
148
# Build with custom options and keep going on errors
149
cythonize -k -s -j 8 -b src/**/*.pyx
150
151
# Quiet build with dependency tracking
152
cythonize -q -M -b my_package/*.pyx
153
```
154
155
### Debugging with cygdb
156
157
```bash
158
# Debug in current directory (requires cython_debug/ folder)
159
cygdb
160
161
# Debug specific project
162
cygdb /path/to/my/project
163
164
# Debug with custom GDB executable
165
cygdb --gdb-executable gdb-multiarch
166
167
# Debug with additional GDB arguments
168
cygdb . --args python my_script.py arg1 arg2
169
```
170
171
### Workflow Examples
172
173
#### Development Workflow
174
175
```bash
176
# 1. Write Cython code in my_module.pyx
177
# 2. Build with debugging and annotations
178
cythonize -i --gdb --annotate my_module.pyx
179
180
# 3. Test the module
181
python -c "import my_module; print(my_module.test_function())"
182
183
# 4. Debug if needed
184
cygdb
185
186
# 5. Optimize based on annotations
187
# Open my_module.html in browser to see performance bottlenecks
188
```
189
190
#### Production Build
191
192
```bash
193
# Compile with optimizations for production
194
cythonize -X boundscheck=False \
195
-X wraparound=False \
196
-X cdivision=True \
197
-X language_level=3 \
198
-j 8 -b src/*.pyx
199
```
200
201
#### Cross-compilation
202
203
```bash
204
# Set environment variables for cross-compilation
205
export CC=arm-linux-gnueabihf-gcc
206
export CXX=arm-linux-gnueabihf-g++
207
208
# Compile with custom include paths
209
cythonize -I /usr/arm-linux-gnueabihf/include \
210
-b my_module.pyx
211
```
212
213
### Integration with Make/Build Systems
214
215
#### Makefile Integration
216
217
```makefile
218
# Makefile example
219
CYTHON = cython
220
CYTHONIZE = cythonize
221
222
%.c: %.pyx
223
$(CYTHON) -3 $< -o $@
224
225
build: src/*.pyx
226
$(CYTHONIZE) -3 -b $^
227
228
debug: src/*.pyx
229
$(CYTHONIZE) -3 --gdb --annotate -i $^
230
231
clean:
232
rm -f src/*.c src/*.cpp src/*.html src/*.so
233
```
234
235
#### CMake Integration
236
237
```cmake
238
# CMakeLists.txt example
239
find_program(CYTHON_EXECUTABLE cython)
240
241
function(add_cython_module module_name pyx_file)
242
get_filename_component(pyx_file_we ${pyx_file} NAME_WE)
243
set(c_file "${CMAKE_CURRENT_BINARY_DIR}/${pyx_file_we}.c")
244
245
add_custom_command(
246
OUTPUT ${c_file}
247
COMMAND ${CYTHON_EXECUTABLE} -3 ${pyx_file} -o ${c_file}
248
DEPENDS ${pyx_file}
249
)
250
251
add_library(${module_name} MODULE ${c_file})
252
endfunction()
253
```
254
255
### Environment Variables
256
257
Common environment variables that affect the command line tools:
258
259
```bash
260
# Compiler selection
261
export CC=clang
262
export CXX=clang++
263
264
# Python configuration
265
export PYTHON_CONFIG=python3-config
266
267
# Build flags
268
export CFLAGS="-O3 -march=native"
269
export CXXFLAGS="-O3 -march=native"
270
271
# Include paths
272
export CPATH="/usr/local/include:/opt/include"
273
274
# Library paths
275
export LIBRARY_PATH="/usr/local/lib:/opt/lib"
276
```