0
# Distribution Commands
1

2
Platform-specific distribution commands create native installers and packages from frozen executables. These commands build upon the core build_exe functionality to produce distributable formats appropriate for each operating system.
3

4
## Capabilities
5

6
### Windows Distribution Commands
7

8
#### MSI Installer Creation
9

10
Creates Microsoft Installer (.msi) packages with complete Windows integration including shortcuts, registry entries, and uninstall support.
11

12
```python { .api }
13
class bdist_msi(Command):
14
    """Create Microsoft Installer binary distributions."""
15
    
16
    def initialize_options(self) -> None:
17
        """Initialize MSI-specific options."""
18
    
19
    def finalize_options(self) -> None:
20
        """Validate MSI configuration and platform compatibility."""
21
    
22
    def run(self) -> None:
23
        """Create MSI installer package."""
24
    
25
    def add_config(self) -> None:
26
        """Add MSI database configuration."""
27
    
28
    def add_properties(self) -> None:
29
        """Add MSI properties from package metadata."""
30
    
31
    def add_files(self) -> None:
32
        """Add files to MSI database."""
33
    
34
    def add_ui(self) -> None:
35
        """Create complete MSI user interface."""
36
    
37
    # Dialog creation methods
38
    def add_cancel_dialog(self) -> None: ...
39
    def add_exit_dialog(self) -> None: ...
40
    def add_progress_dialog(self) -> None: ...
41
    def add_welcome_dialog(self) -> None: ...
42
```
43

44
#### MSI Configuration Options
45

46
```python { .api }
47
# MSI package options
48
target_name: str              # MSI filename
49
target_version: str           # Product version
50
product_code: str             # MSI product GUID
51
upgrade_code: str             # MSI upgrade GUID
52
initial_target_dir: str       # Default installation directory
53
add_to_path: bool             # Add to system PATH
54
all_users: bool              # Install for all users vs current user
55
install_icon: str             # Shortcut icon file
56
license_file: str             # License text file
57
launch_on_finish: bool        # Launch application after install
58
summary_data: dict            # MSI summary information
59
directories: dict             # Custom directory structure
60
environment_variables: dict    # Environment variables to set
61
extensions: list             # File association extensions
62
```
63

64
### macOS Distribution Commands
65

66
#### DMG Disk Image Creation
67

68
Creates Mac disk images (.dmg) containing application bundles with customizable appearance and licensing.
69

70
```python { .api }
71
class bdist_dmg(Command):
72
    """Create Mac DMG disk image distributions."""
73
    
74
    def initialize_options(self) -> None:
75
        """Initialize DMG-specific options."""
76
    
77
    def finalize_options(self) -> None:
78
        """Validate DMG configuration."""
79
    
80
    def finalize_dmgbuild_options(self) -> None:
81
        """Set dmgbuild-specific defaults."""
82
    
83
    def run(self) -> None:
84
        """Create DMG disk image."""
85
    
86
    def build_dmg(self) -> None:
87
        """Execute DMG creation process."""
88
```
89

90
#### DMG Configuration Options
91

92
```python { .api }
93
# DMG volume settings
94
volume_label: str             # Volume name
95
applications_shortcut: bool   # Create Applications folder shortcut
96
format: str                   # Image format (UDZO, UDBZ, etc.)
97
filesystem: str               # Filesystem type (HFS+, APFS)
98
size: str                     # Volume size
99

100
# Visual customization
101
background: str               # Background image path
102
icon_locations: dict          # Icon positions {filename: (x, y)}
103
window_rect: tuple           # Finder window dimensions (x, y, width, height)
104
default_view: str            # Default Finder view mode
105
show_status_bar: bool        # Show Finder status bar
106
show_sidebar: bool           # Show Finder sidebar
107
sidebar_width: int           # Sidebar width in pixels
108

109
# License agreement
110
license: dict                # License with language support
111
                            # {"default-language": "en", "licenses": {"en": "text"}}
112
```
113

114
#### App Bundle Creation
115

116
Creates Mac application bundles (.app) with proper structure, metadata, and code signing support.
117

118
```python { .api }
119
class bdist_mac(Command):
120
    """Create Mac application bundle distributions."""
121
    
122
    def initialize_options(self) -> None:
123
        """Initialize Mac app bundle options."""
124
    
125
    def finalize_options(self) -> None:
126
        """Validate and set bundle paths."""
127
    
128
    def run(self) -> None:
129
        """Create complete app bundle."""
130
    
131
    def create_plist(self) -> None:
132
        """Generate Contents/Info.plist file."""
133
    
134
    def set_absolute_reference_paths(self, path: str | None = None) -> None:
135
        """Set absolute library paths using install_name_tool."""
136
    
137
    def find_qt_menu_nib(self) -> None:
138
        """Locate Qt menu resources."""
139
    
140
    def prepare_qt_app(self) -> None:
141
        """Configure Qt application resources."""
142
    
143
    # Code signing methods
144
    def _codesign(self) -> None:
145
        """Sign the complete application bundle."""
146
    
147
    def _codesign_file(self, filename: str) -> None:
148
        """Sign individual files within bundle."""
149
    
150
    def _verify_signature(self) -> None:
151
        """Verify code signature validity."""
152
```
153

154
#### App Bundle Configuration Options
155

156
```python { .api }
157
# Bundle structure
158
bundle_name: str              # Application bundle name (.app)
159
iconfile: str                 # Application icon (.icns)
160
custom_info_plist: str        # Custom Info.plist template
161
plist_items: dict            # Additional Info.plist entries
162

163
# Framework and resource inclusion
164
include_frameworks: list      # Frameworks to bundle
165
include_resources: list       # Additional resources to include
166

167
# Code signing
168
codesign_identity: str        # Code signing identity
169
codesign_entitlements: str    # Entitlements file path
170
codesign_deep: bool          # Deep code signing
171
codesign_timestamp: bool     # Include secure timestamp
172

173
# Qt support
174
qt_menu_nib: str             # Path to Qt menu.nib
175
```
176

177
### Linux Distribution Commands
178

179
#### AppImage Creation
180

181
Creates portable AppImage executables that run on most Linux distributions without installation.
182

183
```python { .api }
184
class bdist_appimage(Command):
185
    """Create Linux AppImage distributions."""
186
    
187
    def initialize_options(self) -> None:
188
        """Initialize AppImage options."""
189
    
190
    def finalize_options(self) -> None:
191
        """Validate Linux platform and get appimagetool."""
192
    
193
    def run(self) -> None:
194
        """Create AppImage package."""
195
    
196
    def save_as_file(
197
        self, 
198
        data: str, 
199
        outfile: str, 
200
        mode: str = "r"
201
    ) -> None:
202
        """Save file with proper permissions."""
203
    
204
    def warn_delayed(self, msg: str) -> None:
205
        """Queue warning messages."""
206
    
207
    def warnings(self) -> None:
208
        """Display all queued warnings."""
209
    
210
    def _get_appimagekit(self) -> None:
211
        """Download appimagetool if needed."""
212
```
213

214
#### RPM Package Creation
215

216
Creates Red Hat Package Manager (.rpm) distributions for Red Hat, SUSE, and other RPM-based Linux distributions.
217

218
```python { .api }
219
class bdist_rpm(Command):
220
    """Create RPM binary distributions."""
221
    
222
    def initialize_options(self) -> None:
223
        """Initialize RPM options."""
224
    
225
    def finalize_options(self) -> None:
226
        """Validate RPM configuration and tools."""
227
    
228
    def finalize_package_data(self) -> None:
229
        """Set RPM metadata defaults."""
230
    
231
    def run(self) -> None:
232
        """Create RPM package."""
233
    
234
    def _make_spec_file(self) -> list[str]:
235
        """Generate RPM spec file."""
236
    
237
    def _format_changelog(self, changelog: str) -> list[str]:
238
        """Format changelog entries correctly."""
239
```
240

241
#### RPM Configuration Options
242

243
```python { .api }
244
# RPM metadata
245
group: str                    # RPM group classification
246
vendor: str                   # Package vendor
247
packager: str                 # Package maintainer
248
release: str                  # Release number
249
serial: int                   # Package serial number
250

251
# Dependencies
252
provides: list[str]           # Capabilities this package provides
253
requires: list[str]           # Required dependencies
254
conflicts: list[str]          # Conflicting packages
255
build_requires: list[str]     # Build-time dependencies
256
obsoletes: list[str]          # Packages this obsoletes
257

258
# Build configuration
259
rpm_base: str                 # RPM build directory
260
spec_only: bool              # Generate spec file only
261
keep_temp: bool              # Keep temporary files
262
no_autoreq: bool             # Disable automatic requirement generation
263

264
# Scripts and documentation
265
prep_script: str             # %prep script
266
build_script: str            # %build script  
267
install_script: str          # %install script
268
clean_script: str            # %clean script
269
pre_install: str             # %pre script
270
post_install: str            # %post script
271
pre_uninstall: str           # %preun script
272
post_uninstall: str          # %postun script
273
doc_files: list[str]         # Documentation files
274
changelog: str               # Package changelog
275
icon: str                    # Package icon
276
```
277

278
#### DEB Package Creation
279

280
Creates Debian (.deb) packages by converting RPM packages using the alien tool.
281

282
```python { .api }
283
class bdist_deb(Command):
284
    """Create DEB distributions by converting RPM."""
285
    
286
    def initialize_options(self) -> None:
287
        """Initialize basic options."""
288
    
289
    def finalize_options(self) -> None:
290
        """Check for required tools (alien, fakeroot)."""
291
    
292
    def run(self) -> None:
293
        """Convert RPM to DEB format."""
294
```
295

296
### Usage Examples
297

298
```python
299
from cx_Freeze import setup, Executable
300

301
# Multi-platform setup with distribution commands
302
setup(
303
    name="MyApp",
304
    version="1.0.0",
305
    description="My Application",
306
    executables=[
307
        Executable("main.py", base="gui", icon="app.ico")
308
    ],
309
    options={
310
        "build_exe": {
311
            "packages": ["tkinter"],
312
            "include_files": [("data/", "data/")]
313
        },
314
        "bdist_msi": {
315
            "target_name": "MyApp-1.0.0",
316
            "add_to_path": True,
317
            "install_icon": "app.ico",
318
            "license_file": "LICENSE.txt"
319
        },
320
        "bdist_dmg": {
321
            "volume_label": "MyApp Installer",
322
            "applications_shortcut": True,
323
            "background": "dmg_background.png"
324
        },
325
        "bdist_mac": {
326
            "bundle_name": "MyApp.app",
327
            "iconfile": "app.icns",
328
            "codesign_identity": "Developer ID Application: Your Name"
329
        }
330
    }
331
)
332

333
# Command-line usage
334
# python setup.py bdist_msi
335
# python setup.py bdist_dmg  
336
# python setup.py bdist_mac
337
# python setup.py bdist_rpm
338
# python setup.py bdist_appimage
339
```
340

341
### Platform-Specific Requirements
342

343
Each distribution command has specific system requirements and dependencies.
344

345
**Windows (bdist_msi):**
346
- Windows SDK or Visual Studio
347
- MSI database tools
348
- Optional: Code signing certificate
349

350
**macOS (bdist_dmg, bdist_mac):**
351
- Xcode command line tools
352
- dmgbuild package (for DMG creation)
353
- Optional: Apple Developer certificate for code signing
354

355
**Linux (bdist_rpm, bdist_deb, bdist_appimage):**
356
- rpm-build package (for RPM)
357
- alien and fakeroot (for DEB)
358
- appimagetool (for AppImage, auto-downloaded)
359
- Optional: GPG key for package signing
360

361
### Error Handling
362

363
```python { .api }
364
# Platform validation
365
class PlatformError(Exception):
366
    """Raised for platform-specific errors."""
367

368
# Tool requirements
369
class ExecError(Exception):
370
    """Raised when external tools are missing or fail."""
371

372
# Configuration validation  
373
class OptionError(Exception):
374
    """Raised for invalid distribution options."""
375
```