0
# Core Compilation
1

2
The core compilation API provides programmatic access to Nuitka's Python-to-C compilation pipeline. These functions orchestrate the transformation of Python source code through AST processing, optimization, C code generation, and binary compilation.
3

4
## Capabilities
5

6
### Main Control Flow
7

8
Primary entry point and orchestration functions for the compilation process.
9

10
```python { .api }
11
def main():
12
    """
13
    Main compiler entry point and orchestration.
14
    
15
    Coordinates the complete compilation pipeline from argument parsing
16
    through final binary generation. Handles initialization, plugin 
17
    loading, and cleanup.
18
    
19
    Returns:
20
        None: Exits with appropriate status code
21
        
22
    Raises:
23
        SystemExit: On compilation errors or completion
24
    """
25
```
26

27
**Usage Example:**
28

29
```python
30
from nuitka import MainControl, Options
31

32
# Configure compilation options
33
Options.parseArgs()  # Parse command line or set programmatically
34

35
# Execute compilation process
36
MainControl.main()
37
```
38

39
### Tree Compilation
40

41
Core functions for compiling Python source trees into optimized C code.
42

43
```python { .api }
44
def compileTree() -> tuple[bool, dict]:
45
    """
46
    Compile Python source tree to C code.
47
    
48
    Processes the Python AST, applies optimizations, and generates
49
    corresponding C source code. Handles module dependencies and
50
    cross-module optimization.
51
    
52
    Returns:
53
        tuple[bool, dict]: (compilation_success, scons_options_dict)
54
        
55
    Raises:
56
        CompilationError: On syntax or semantic errors
57
        ImportError: On unresolvable module dependencies
58
    """
59

60
def _createMainModule():
61
    """
62
    Create and process main module tree.
63
    
64
    Creates the main module object and builds its compilation tree,
65
    handling imports and dependencies.
66
    
67
    Returns:
68
        Module: Main module object with processed tree
69
        
70
    Raises:
71
        ImportError: On module creation failures
72
    """
73

74
def buildMainModuleTree(source_code: str = None):
75
    """
76
    Build main module compilation tree.
77
    
78
    Constructs the abstract syntax tree for the main module,
79
    applying initial transformations and optimizations.
80
    
81
    Args:
82
        source_code (str): Optional source code override
83
        
84
    Returns:
85
        Module: Built module tree object
86
    """
87

88
def optimizeModules(filename: str):
89
    """
90
    Optimize compiled modules.
91
    
92
    Applies cross-module optimizations and performs
93
    dead code elimination on compiled modules.
94
    
95
    Args:
96
        filename (str): Main script filename
97
        
98
    Returns:
99
        None: Modifies modules in-place
100
    """
101

102
def dumpTreeXML() -> str:
103
    """
104
    Export compilation tree as XML for debugging.
105
    
106
    Generates detailed XML representation of the internal compilation
107
    tree structure for debugging and analysis purposes.
108
    
109
    Returns:
110
        str: XML representation of compilation tree
111
    """
112
```
113

114
**Usage Example:**
115

116
```python
117
from nuitka import MainControl
118

119
# Compile the parsed source tree
120
success = MainControl.compileTree()
121

122
if success:
123
    print("Compilation successful")
124
else:
125
    print("Compilation failed")
126

127
# Optional: Export tree for debugging
128
xml_output = MainControl.dumpTreeXML()
129
with open("debug_tree.xml", "w") as f:
130
    f.write(xml_output)
131
```
132

133
### Source Directory Management
134

135
Functions for managing compilation output directories and source file organization.
136

137
```python { .api }
138
def makeSourceDirectory() -> str:
139
    """
140
    Create and prepare source output directory.
141
    
142
    Sets up the build directory structure, creates necessary subdirectories,
143
    and prepares the environment for C source code generation.
144
    
145
    Returns:
146
        str: Path to created source directory
147
        
148
    Raises:
149
        OSError: On directory creation failures
150
        PermissionError: On insufficient filesystem permissions
151
    """
152
```
153

154
**Usage Example:**
155

156
```python
157
from nuitka import MainControl
158

159
# Create and prepare build directory
160
source_dir = MainControl.makeSourceDirectory()
161
print(f"Build directory created at: {source_dir}")
162
```
163

164
### Build Backend Integration
165

166
Interface with the SCons build system for compiling generated C code to binaries.
167

168
```python { .api }
169
def runSconsBackend() -> tuple[bool, dict]:
170
    """
171
    Execute SCons build backend for compilation.
172
    
173
    Invokes the SCons build system to compile generated C source code
174
    into final executables or extension modules. Handles compiler
175
    configuration, linking, and optimization.
176
    
177
    Returns:
178
        tuple[bool, dict]: (build_success, build_info_dict)
179
        
180
    Raises:
181
        BuildError: On compilation or linking failures
182
        EnvironmentError: On missing build tools
183
    """
184
```
185

186
**Usage Example:**
187

188
```python
189
from nuitka import MainControl
190

191
# After C code generation, compile to binary
192
exit_code = MainControl.runSconsBackend()
193

194
if exit_code == 0:
195
    print("Build successful")
196
else:
197
    print(f"Build failed with exit code: {exit_code}")
198
```
199

200
## Compilation Pipeline
201

202
### Complete Compilation Workflow
203

204
Example of using the core compilation API for programmatic compilation:
205

206
```python
207
from nuitka import MainControl, Options
208
from nuitka.Tracing import my_print
209
import sys
210

211
def compile_python_file(source_file, output_mode="standalone"):
212
    """
213
    Compile a Python file using the core API.
214
    
215
    Args:
216
        source_file (str): Path to Python source file
217
        output_mode (str): Compilation mode ('standalone', 'module', 'package')
218
    
219
    Returns:
220
        bool: True if compilation successful
221
    """
222
    try:
223
        # Configure compilation options programmatically
224
        sys.argv = [
225
            "nuitka",
226
            f"--{output_mode}",
227
            "--verbose",
228
            source_file
229
        ]
230
        
231
        # Parse arguments
232
        Options.parseArgs()
233
        Options.commentArgs()
234
        
235
        # Execute compilation pipeline
236
        MainControl.main()
237
        
238
        return True
239
        
240
    except SystemExit as e:
241
        return e.code == 0
242
    except Exception as e:
243
        my_print(f"Compilation error: {e}")
244
        return False
245

246
# Usage
247
success = compile_python_file("myapp.py", "standalone")
248
```
249

250
### Advanced Compilation Control
251

252
Fine-grained control over compilation phases:
253

254
```python
255
from nuitka import MainControl, Options
256
from nuitka.plugins.Plugins import activatePlugins
257
from nuitka.importing.Importing import addMainScriptDirectory
258

259
def advanced_compilation(source_file, plugins=None, includes=None):
260
    """
261
    Advanced compilation with custom configuration.
262
    
263
    Args:
264
        source_file (str): Source file to compile
265
        plugins (list): Plugin names to activate
266
        includes (list): Additional modules to include
267
    """
268
    # Initialize compilation environment
269
    Options.parseArgs()
270
    
271
    # Activate specified plugins
272
    if plugins:
273
        for plugin in plugins:
274
            # Plugin activation logic here
275
            pass
276
    
277
    activatePlugins()
278
    
279
    # Add source directory to import path
280
    addMainScriptDirectory()
281
    
282
    # Prepare build environment
283
    source_dir = MainControl.makeSourceDirectory()
284
    print(f"Using build directory: {source_dir}")
285
    
286
    # Compile source tree
287
    success = MainControl.compileTree()
288
    
289
    if success:
290
        # Generate debug information if needed
291
        xml_debug = MainControl.dumpTreeXML()
292
        
293
        # Execute build backend
294
        build_result = MainControl.runSconsBackend()
295
        
296
        return build_result == 0
297
    
298
    return False
299
```
300

301
## Error Handling
302

303
### Compilation Exceptions
304

305
Handle various compilation error scenarios:
306

307
```python
308
from nuitka import MainControl
309
from nuitka.Errors import NuitkaError
310

311
try:
312
    MainControl.main()
313
    
314
except NuitkaError as e:
315
    print(f"Nuitka compilation error: {e}")
316
    
317
except ImportError as e:
318
    print(f"Module import error: {e}")
319
    print("Consider using --include-module or --include-package")
320
    
321
except OSError as e:
322
    print(f"File system error: {e}")
323
    print("Check file permissions and disk space")
324
    
325
except SystemExit as e:
326
    if e.code == 0:
327
        print("Compilation completed successfully")
328
    else:
329
        print(f"Compilation failed with exit code: {e.code}")
330
```
331

332
### Build System Integration
333

334
Handle SCons build backend errors:
335

336
```python
337
from nuitka import MainControl
338

339
def safe_build():
340
    """Safely execute build with comprehensive error handling."""
341
    try:
342
        exit_code = MainControl.runSconsBackend()
343
        
344
        if exit_code == 0:
345
            return True
346
            
347
        # Handle specific build failures
348
        if exit_code == 1:
349
            print("Compiler error - check C compiler installation")
350
        elif exit_code == 2:
351
            print("Linker error - check library dependencies")
352
        else:
353
            print(f"Build failed with code {exit_code}")
354
            
355
        return False
356
        
357
    except EnvironmentError as e:
358
        print(f"Build environment error: {e}")
359
        print("Ensure C compiler and build tools are installed")
360
        return False
361
```
362

363
## Integration with Options
364

365
### Programmatic Option Setting
366

367
Configure compilation options programmatically:
368

369
```python
370
from nuitka import Options
371
import sys
372

373
# Method 1: Modify sys.argv before parsing
374
sys.argv = [
375
    "nuitka",
376
    "--standalone",
377
    "--plugin-enable=numpy",
378
    "--include-package=requests",
379
    "myapp.py"
380
]
381

382
Options.parseArgs()
383

384
# Method 2: Direct option manipulation (internal API)
385
# Note: This approach requires understanding internal option structure
386
```
387

388
### Option Validation
389

390
Validate and comment on parsed options:
391

392
```python
393
from nuitka import Options
394

395
# Parse command line arguments
396
Options.parseArgs()
397

398
# Validate and process options
399
Options.commentArgs()
400

401
# Check compilation mode
402
if Options.shallMakeModule():
403
    print("Compiling as extension module")
404
elif Options.shallMakeExe():
405
    print("Compiling as executable")
406
```
407

408
## Performance Considerations
409

410
### Memory Management
411

412
Optimize memory usage during compilation:
413

414
```python
415
import gc
416
from nuitka import MainControl
417

418
def memory_efficient_compilation():
419
    """Perform compilation with memory optimization."""
420
    try:
421
        # Enable garbage collection
422
        gc.enable()
423
        
424
        # Create source directory
425
        MainControl.makeSourceDirectory()
426
        
427
        # Explicit garbage collection before heavy processing
428
        gc.collect()
429
        
430
        # Compile tree
431
        success = MainControl.compileTree()
432
        
433
        if success:
434
            # Another GC pass before build
435
            gc.collect()
436
            
437
            # Execute build
438
            return MainControl.runSconsBackend() == 0
439
            
440
    finally:
441
        # Cleanup
442
        gc.collect()
443
        
444
    return False
445
```
446

447
### Parallel Processing
448

449
The core compilation API integrates with Nuitka's parallel processing capabilities through the Options system rather than direct API calls.
450

451
## Types
452

453
```python { .api }
454
# Compilation result types
455
CompilationResult = bool
456
BuildResult = int
457
SourceDirectory = str
458

459
# Error types
460
CompilationError = Exception
461
BuildError = Exception
462
NuitkaError = Exception
463
```