0
# Executable Configuration
1

2
The Executable class defines the configuration for creating standalone executables from Python scripts. It supports extensive customization including base executable types, icons, metadata, and platform-specific options.
3

4
## Capabilities
5

6
### Executable Creation
7

8
Creates an executable configuration with comprehensive options for customizing the generated executable's behavior, appearance, and metadata.
9

10
```python { .api }
11
class Executable:
12
    def __init__(
13
        self,
14
        script: str | Path,
15
        init_script: str | Path | None = None,
16
        base: str | Path | None = None,
17
        target_name: str | None = None,
18
        icon: str | Path | None = None,
19
        shortcut_name: str | None = None,
20
        shortcut_dir: str | Path | None = None,
21
        copyright: str | None = None,
22
        trademarks: str | None = None,
23
        manifest: str | Path | None = None,
24
        uac_admin: bool = False,
25
        uac_uiaccess: bool = False,
26
    ):
27
        """
28
        Create an executable configuration.
29

30
        Parameters:
31
        - script: Path to the main Python script to freeze
32
        - init_script: Initialization script executed before main script
33
        - base: Base executable type ("console", "gui", "service") or custom path
34
        - target_name: Name of the generated executable (without extension)
35
        - icon: Path to icon file (auto-detects .ico/.icns/.png/.svg extension)
36
        - shortcut_name: Name for MSI package shortcuts (Windows only)
37
        - shortcut_dir: Directory for MSI shortcuts (Windows only)
38
        - copyright: Copyright string for version resource (Windows only)
39
        - trademarks: Trademarks string for version resource (Windows only)
40
        - manifest: Path to XML manifest file (Windows only)
41
        - uac_admin: Request elevation privileges (Windows only)
42
        - uac_uiaccess: Bypass UI control restrictions (Windows only)
43
        """
44
```
45

46
### Base Executable Types
47

48
The base parameter determines the type of executable to create, with platform-specific behavior and automatic fallbacks.
49

50
```python { .api }
51
# Base types (built-in)
52
base = "console"     # Console application (default)
53
base = "gui"         # GUI application (Windows/macOS)
54
base = "service"     # Windows service (Windows only)
55

56
# Custom base (absolute path)
57
base = "/path/to/custom/base"
58
```
59

60
### Properties and Methods
61

62
Access and modify executable configuration through properties that handle validation and platform-specific logic.
63

64
```python { .api }
65
# Key properties
66
@property
67
def base(self) -> Path:
68
    """Path to the base executable template."""
69

70
@property  
71
def icon(self) -> Path | None:
72
    """Path to icon file with automatic extension detection."""
73

74
@property
75
def init_script(self) -> Path:
76
    """Path to initialization script."""
77

78
@property
79
def main_script(self) -> Path:
80
    """Path to main Python script."""
81

82
@property
83
def target_name(self) -> str:
84
    """Final executable name with platform extension."""
85

86
@property
87
def init_module_name(self) -> str:
88
    """Name of init module in zip file."""
89

90
@property
91
def main_module_name(self) -> str:
92
    """Name of main module in zip file."""
93

94
# Representation
95
def __repr__(self) -> str:
96
    """String representation showing script path."""
97
```
98

99
### Usage Examples
100

101
```python
102
from cx_Freeze import Executable
103

104
# Basic console application
105
exe = Executable("main.py")
106

107
# GUI application with icon
108
exe = Executable(
109
    script="gui_app.py",
110
    base="gui",
111
    icon="app_icon",  # Will search for .ico/.icns/.png/.svg
112
    target_name="MyApplication"
113
)
114

115
# Windows service with metadata
116
exe = Executable(
117
    script="service.py",
118
    base="service",
119
    target_name="MyService",
120
    copyright="© 2024 My Company",
121
    trademarks="MyApp™",
122
    uac_admin=True
123
)
124

125
# Custom initialization
126
exe = Executable(
127
    script="main.py",
128
    init_script="custom_init.py",
129
    base="console"
130
)
131
```
132

133
### Validation
134

135
Executable configurations are validated automatically and can be validated explicitly for setup distributions.
136

137
```python { .api }
138
def validate_executables(
139
    dist: Distribution, 
140
    attr: str, 
141
    value: list[Executable | dict | str]
142
) -> None:
143
    """
144
    Validate executables attribute for setup() function.
145

146
    Parameters:
147
    - dist: setuptools Distribution object
148
    - attr: Attribute name being validated
149
    - value: List of Executable objects, dictionaries, or script strings
150

151
    Raises:
152
    - SetupError: If validation fails
153

154
    Notes:
155
    - Accepts Executable objects, dictionaries (converted to Executable), or strings (script paths)
156
    - Automatically converts and normalizes input formats
157
    - Called automatically by setup() function
158
    """
159
```
160

161
### Platform-Specific Behavior
162

163
Base executable selection and features vary by platform with automatic fallbacks for unsupported options.
164

165
**Windows/MinGW:**
166
- Supports all base types: console, gui, service
167
- Icon files: .ico preferred, .png/.svg supported
168
- Manifest and UAC options available
169
- Version resource metadata (copyright, trademarks)
170

171
**macOS:**
172
- GUI base creates .app bundle structure
173
- Service/gui bases fall back to console on non-Windows
174
- Icon files: .icns preferred, .png/.svg supported
175
- App bundle metadata integration
176

177
**Linux:**
178
- All bases default to console executable
179
- Icon files: .png/.svg supported
180
- Desktop integration through distribution commands
181

182
### Error Handling
183

184
```python { .api }
185
# Common exceptions during executable configuration
186
class OptionError(Exception):
187
    """Raised for invalid executable configuration options."""
188

189
# Example error conditions:
190
# - Base executable not found
191
# - Invalid target_name (contains path separators)  
192
# - Icon file not found
193
# - Invalid init_script path
194
```
195

196
### Executable Validation
197

198
Validates executable configurations to ensure they meet cx_Freeze requirements.
199

200
```python { .api }
201
def validate_executables(dist: Distribution, attr: str, value) -> None:
202
    """
203
    Verify that value is a valid executables attribute.
204
    
205
    Parameters:
206
    - dist: setuptools Distribution object
207
    - attr: Attribute name being validated
208
    - value: Executables list to validate (Executable objects, dicts, or strings)
209
    
210
    Raises:
211
    - SetupError: If executables list is invalid or contains unsupported types
212
    
213
    Accepts:
214
    - List of Executable objects
215
    - List of dictionaries with executable configuration
216
    - List of script paths as strings
217
    """
218
```