0
# Build Commands
1

2
Build commands provide setuptools-compatible integration for creating executables and managing the freezing process. The primary command is `build_exe`, which handles module discovery, dependency resolution, and executable creation with extensive configuration options.
3

4
## Capabilities
5

6
### build_exe Command
7

8
The core build command that creates executables from Python scripts by analyzing dependencies, collecting required modules, and assembling the final distribution.
9

10
```python { .api }
11
class build_exe(Command):
12
    """Build executables from Python scripts."""
13
    
14
    description = "build executables from Python scripts"
15
    
16
    def initialize_options(self) -> None:
17
        """Initialize all command options to default values."""
18
    
19
    def finalize_options(self) -> None:
20
        """Validate and finalize option values before execution."""
21
    
22
    def run(self) -> None:
23
        """Execute the build process using Freezer."""
24
    
25
    def add_to_path(self, name: str) -> None:
26
        """Add source directory to sys.path for module discovery."""
27
    
28
    def build_extension(
29
        self, 
30
        name: str, 
31
        module_name: str | None = None
32
    ) -> None:
33
        """Build C extensions during the freezing process."""
34
    
35
    def set_source_location(self, name: str, *path_parts: str) -> None:
36
        """Set source locations from environment variables."""
37
    
38
    def has_executables(self) -> bool:
39
        """Check if distribution has executables defined."""
40
```
41

42
### Build Configuration Options
43

44
Comprehensive options for controlling the build process, module inclusion/exclusion, optimization, and output formatting.
45

46
```python { .api }
47
# Key build options (user_options)
48
build_exe: str           # Build directory for executables
49
includes: list[str]      # Modules to explicitly include
50
excludes: list[str]      # Modules to explicitly exclude  
51
packages: list[str]      # Packages to include with all submodules
52
replace_paths: list[str] # Path replacement mappings
53
optimize: int           # Bytecode optimization level (0, 1, 2)
54
compress: bool          # Compress Python bytecode in zip
55
zip_includes: list[str] # Files to include in zip archive
56
zip_include_packages: list[str] # Packages to store in zip
57
include_files: list[str] # Additional files to copy to build directory
58
include_msvcr: bool     # Include Microsoft Visual C++ runtime (Windows)
59
bin_includes: list[str] # Binary files to include in build
60
bin_excludes: list[str] # Binary files to exclude from build
61
bin_path_includes: list[str] # Binary search paths
62
bin_path_excludes: list[str] # Binary search paths to exclude
63
```
64

65
### Advanced Build Options
66

67
Options for fine-tuning the build process, handling edge cases, and integrating with development workflows.
68

69
```python { .api }
70
# Advanced configuration options
71
no_compress: bool            # Disable compression
72
include_msvcr_version: str   # Specific MSVCR version to include  
73
zip_exclude_packages: list[str] # Packages to exclude from zip
74
constants_modules: list[str]    # Constants module definitions
75
zip_filename: str            # Custom zip filename
76
metadata: dict              # Custom metadata for frozen app
77
path: list[str]             # Module search paths
78
build_lib: str              # Library build directory
79
silent: bool                # Suppress build output
80
init_script: str            # Default initialization script
81
```
82

83
### Usage Examples
84

85
```python
86
# Basic setup.py with build_exe
87
from cx_Freeze import setup, Executable
88

89
setup(
90
    name="MyApp",
91
    version="1.0",
92
    executables=[Executable("main.py")],
93
    options={
94
        "build_exe": {
95
            "build_exe": "dist",
96
            "includes": ["tkinter", "sqlite3"],
97
            "excludes": ["unittest", "test"],
98
            "packages": ["requests", "numpy"],
99
            "include_files": [
100
                ("data/", "data/"),
101
                "config.ini"
102
            ],
103
            "optimize": 2,
104
            "compress": True
105
        }
106
    }
107
)
108

109
# Command-line usage
110
# python setup.py build_exe
111
# python setup.py build_exe --build-exe=custom_dist --includes=pandas
112
```
113

114
### Path and Module Management
115

116
Control over module discovery, path replacement, and binary inclusion for complex applications with specific requirements.
117

118
```python { .api }
119
# Path replacement format
120
replace_paths = [
121
    "original_path=replacement_path",
122
    "/usr/local/lib=/app/lib"
123
]
124

125
# File inclusion formats  
126
include_files = [
127
    "source_file",                    # Copy to build root
128
    ("source_file", "dest_file"),     # Copy with rename
129
    ("source_dir/", "dest_dir/"),     # Copy directory
130
]
131

132
# Binary handling
133
bin_includes = ["libspecial.so", "custom.dll"]
134
bin_excludes = ["libc.so*", "kernel32.dll"]
135
bin_path_includes = ["/opt/custom/lib"]
136
bin_path_excludes = ["/usr/lib/python*/lib-dynload"]
137
```
138

139
### Build Process Flow
140

141
The build_exe command follows a structured process that can be customized at various stages.
142

143
```python { .api }
144
# Internal build process methods
145
def _get_executables(self) -> list[Executable]:
146
    """Get list of executables to build."""
147

148
def _create_constants_module(self) -> ConstantsModule:
149
    """Create constants module for frozen application."""
150

151
def _get_freezer_options(self) -> dict:
152
    """Prepare options for Freezer initialization."""
153

154
# Integration points
155
def get_sub_commands(self) -> list[str]:
156
    """Get list of sub-commands to run."""
157

158
def get_source_files(self) -> list[str]:
159
    """Get list of source files being processed."""
160
```
161

162
### Platform-Specific Behavior
163

164
Build options and behavior adapt to the target platform with automatic handling of platform-specific requirements.
165

166
**Windows:**
167
- MSVCR runtime inclusion options
168
- DLL dependency resolution
169
- Resource compilation for icons/manifests
170
- Registry integration for file associations
171

172
**macOS:**
173
- Framework bundling
174
- Library path fixing (@rpath/@loader_path)
175
- Code signing preparation
176
- .app bundle structure creation
177

178
**Linux:**
179
- Shared library dependency resolution
180
- RPATH configuration
181
- Desktop file generation
182
- AppImage preparation
183

184
### Error Handling and Validation
185

186
```python { .api }
187
# Build-time validation
188
class OptionError(Exception):
189
    """Raised for invalid build configuration."""
190

191
class SetupError(Exception):
192
    """Raised for setup script configuration errors."""
193

194
# Common validation scenarios:
195
# - Invalid build directory permissions
196
# - Missing required modules or packages
197
# - Conflicting include/exclude specifications
198
# - Platform-specific option validation
199
# - Executable script file validation
200
```
201

202
### Integration with install Commands
203

204
Build commands integrate with installation commands for complete deployment workflows.
205

206
```python { .api }
207
# Related installation commands
208
class install(Install):
209
    """Extended install command with executable support."""
210

211
class install_exe(Command):
212
    """Install executables built by build_exe."""
213
    
214
    def get_inputs(self) -> list[str]:
215
        """Get list of files to install."""
216
    
217
    def get_outputs(self) -> list[str]:
218
        """Get list of installed files."""
219
```