0
# Nuitka
1

2
Nuitka is a Python compiler that translates Python modules into C programs, providing seamless compatibility with CPython while optimizing performance. It supports all Python constructs and executes both compiled and uncompiled code together, offering acceleration capabilities and standalone distribution for Python applications.
3

4
## Package Information
5

6
- **Package Name**: Nuitka
7
- **Language**: Python
8
- **Installation**: `pip install Nuitka`
9

10
## Core Imports
11

12
```python
13
import nuitka
14
```
15

16
For command-line usage:
17
```bash
18
nuitka --help
19
```
20

21
For programmatic usage:
22
```python
23
from nuitka import MainControl, Options
24
from nuitka.Version import getNuitkaVersion, getNuitkaVersionTuple
25
from nuitka.plugins.Plugins import activatePlugins
26
from nuitka.utils.Utils import getOS, getArchitecture
27
```
28

29
## Basic Usage
30

31
### Command Line Compilation
32

33
```python
34
# Compile a Python script to standalone executable
35
nuitka --standalone myapp.py
36

37
# Compile as extension module
38
nuitka --module mymodule.py
39

40
# Run with Nuitka optimization
41
nuitka-run script.py
42
```
43

44
### Distutils Integration
45

46
```python
47
from setuptools import setup
48

49
setup(
50
    name="mypackage",
51
    build_with_nuitka=True,
52
    # other setup parameters
53
)
54
```
55

56
### Basic Programmatic Usage
57

58
```python
59
from nuitka import MainControl, Options
60
from nuitka.Version import getNuitkaVersion, getNuitkaVersionTuple
61

62
# Get version information
63
version = getNuitkaVersion()
64
version_tuple = getNuitkaVersionTuple()
65
print(f"Nuitka version: {version}")
66
print(f"Version tuple: {version_tuple}")
67

68
# Parse options and compile (advanced usage)
69
Options.parseArgs()
70
MainControl.main()
71
```
72

73
## Architecture
74

75
Nuitka's architecture consists of several key components:
76

77
- **MainControl**: Orchestrates the compilation process from Python to C to executable
78
- **Options**: Command-line argument parsing and configuration management
79
- **Tree Processing**: AST transformation and optimization of Python source code
80
- **Code Generation**: Converts optimized Python AST into C source code
81
- **Build System**: SCons integration for compiling generated C code
82
- **Plugin System**: Extensible framework for handling special cases and third-party packages
83
- **Utilities**: File operations, process execution, and cross-platform compatibility
84

85
This design enables Nuitka to handle the complete Python language specification while providing optimization opportunities and maintaining full CPython compatibility.
86

87
## Capabilities
88

89
### Command Line Interface
90

91
Primary command-line tools for compiling Python code including the main compiler, run mode, and commercial decryption utilities.
92

93
```python { .api }
94
# Console scripts available after installation
95
nuitka         # Main compiler command
96
nuitka-run     # Run Python scripts with compilation  
97
nuitka-decrypt # Commercial plugin decryption
98
```
99

100
[Command Line Interface](./cli.md)
101

102
### Core Compilation API
103

104
Core compiler functions for orchestrating the Python to C compilation process, including main control flow and tree compilation.
105

106
```python { .api }
107
def main():
108
    """Main compiler entry point and orchestration."""
109

110
def compileTree():
111
    """Compile Python source tree to C code."""
112

113
def makeSourceDirectory():
114
    """Create and prepare source output directory."""
115
```
116

117
[Core Compilation](./core-compilation.md)
118

119
### Configuration & Options
120

121
Configuration management and command-line option parsing for controlling compilation behavior and output modes.
122

123
```python { .api }
124
def parseArgs():
125
    """Parse and validate command line arguments."""
126

127
def isVerbose() -> bool:
128
    """Check if verbose output mode is enabled."""
129

130
def shallMakeModule() -> bool:
131
    """Check if compiling as extension module."""
132

133
def shallMakeExe() -> bool:
134
    """Check if creating executable output."""
135
```
136

137
[Configuration & Options](./configuration.md)
138

139
### Version Information
140

141
Version detection and compatibility checking for the Nuitka compiler and target Python environments.
142

143
```python { .api }
144
def getNuitkaVersion() -> str:
145
    """Get current Nuitka version string."""
146

147
def getNuitkaVersionTuple() -> tuple:
148
    """Get version as tuple (major, minor, patch)."""
149

150
def getSupportedPythonVersions() -> list:
151
    """Get list of supported Python versions."""
152
```
153

154
[Version Information](./version.md)
155

156
### Distutils Integration
157

158
Setup.py integration for seamless Python package compilation with distutils and setuptools build systems.
159

160
```python { .api }
161
def setupNuitkaDistutilsCommands(dist, keyword, value):
162
    """Configure distutils integration for Nuitka."""
163

164
class build:
165
    """Custom build command with Nuitka support."""
166

167
class bdist_nuitka:
168
    """Binary distribution command class."""
169
```
170

171
[Distutils Integration](./distutils.md)
172

173
### Plugin System
174

175
Extensible plugin framework for handling third-party packages, data files, and special compilation cases through base classes and lifecycle hooks.
176

177
```python { .api }
178
class NuitkaPluginBase:
179
    """Base class for all Nuitka plugins."""
180

181
class NuitkaYamlPluginBase:
182
    """Base class for YAML-configured plugins."""
183

184
class Plugins:
185
    """Plugin management and coordination system."""
186
```
187

188
[Plugin System](./plugins.md)
189

190
### Utility Functions
191

192
Cross-platform utilities for file operations, process execution, and system compatibility during the compilation process.
193

194
```python { .api }
195
# File operations utilities
196
def getFileList(directory: str) -> list:
197
    """Get list of files in directory."""
198

199
# Process execution utilities  
200
def executeCommand(command: list) -> int:
201
    """Execute external command."""
202

203
# Distribution detection
204
def getDistributionInfo(package: str) -> dict:
205
    """Get package distribution information."""
206
```
207

208
[Utility Functions](./utilities.md)
209

210
## Error Handling
211

212
Nuitka provides comprehensive error handling throughout the compilation process:
213

214
- **Syntax Errors**: Python syntax validation before compilation
215
- **Import Errors**: Module resolution and dependency checking  
216
- **Compilation Errors**: C compiler integration error reporting
217
- **Plugin Errors**: Plugin loading and execution error handling
218
- **Runtime Errors**: Preserved Python exception semantics in compiled code
219

220
All errors maintain Python's standard exception hierarchy and provide detailed diagnostic information for debugging compilation issues.
221

222
## Types
223

224
```python { .api }
225
# Version information types
226
VersionTuple = tuple[int, int, int]
227

228
# Plugin lifecycle types  
229
PluginPhase = str  # 'onModuleDiscovered', 'onDataFiles', etc.
230

231
# Compilation mode types
232
CompilationMode = str  # 'standalone', 'module', 'package'
233

234
# Option configuration types
235
OptionDict = dict[str, Any]
236
```