Command-Line Tools

def main() -> None:
    """Entry point for cxfreeze command line tool."""

def prepare_parser() -> argparse.ArgumentParser:
    """Create and configure argument parser."""

# Script and target configuration
--script NAME              # Python file to freeze (required)
--target-name NAME          # Executable filename  
--target-dir DIR           # Build directory for output
--base NAME                # Base type: console, gui, service
--init-script NAME         # Startup initialization script

# Visual customization
--icon NAME                # Icon file path (auto-detects extension)
--manifest NAME            # XML manifest file (Windows)

# Windows metadata
--copyright TEXT           # Copyright string
--trademarks TEXT          # Trademarks string
--uac-admin               # Request elevation privileges
--uac-uiaccess            # Bypass UI control restrictions

# MSI installer options  
--shortcut-name NAME       # Shortcut name for MSI packages
--shortcut-dir DIR         # Shortcut directory for MSI packages

# Direct script freezing
cxfreeze --script main.py --target-dir dist

# Command-based execution
cxfreeze build_exe --includes tkinter --excludes unittest
cxfreeze bdist_msi --target-name MyApp

# Available commands
cxfreeze build          # Build executables (implies build_exe)
cxfreeze build_exe      # Build executables explicitly
cxfreeze bdist_msi      # Create MSI installer (Windows)
cxfreeze bdist_dmg      # Create DMG image (macOS)
cxfreeze bdist_mac      # Create app bundle (macOS)
cxfreeze bdist_rpm      # Create RPM package (Linux)
cxfreeze bdist_deb      # Create DEB package (Linux)
cxfreeze bdist_appimage # Create AppImage (Linux)

# Development options
--debug                    # Enable debug information
--verbose, -v             # Verbose output
--help                    # Show help information
--version                 # Show version information

# Integration options
# Options from pyproject.toml are automatically loaded
# Additional command-specific options passed to underlying commands

# Basic console application
cxfreeze --script main.py --target-dir dist

# GUI application with icon
cxfreeze --script gui_app.py --base gui --icon app --target-dir build

# Windows service with metadata
cxfreeze --script service.py --base service --copyright "© 2024 Company" --uac-admin

# Custom initialization and naming
cxfreeze --script main.py --init-script custom_init --target-name MyApp

# Direct MSI creation
cxfreeze bdist_msi --target-name MyApp-1.0 --shortcut-name "My Application"

# Build with additional options
cxfreeze build_exe --includes requests,numpy --excludes unittest,test --target-dir dist

# Deprecated → Modern equivalent
--install-dir DIR       → --build-exe DIR
--exclude-modules LIST  → --excludes LIST  
--include-modules LIST  → --includes LIST
-c, --compress         → (removed, use setup.py options)
-O, -OO               → --optimize=1, --optimize=2
-z                    → --zip-includes
--default-path        → --path
-s, --silent          → --silent

def main() -> None:
    """Entry point for cxfreeze-quickstart command line tool."""

class SetupWriter:
    """Interactive setup script generator."""
    
    def populate_from_command_line(self) -> None:
        """Interactive configuration through prompts."""
    
    def write(self) -> None:
        """Generate setup.py file from configuration."""
    
    def get_value(
        self, 
        label: str, 
        default: str = "", 
        separator: str = ": "
    ) -> str:
        """Get user input with default value."""
    
    def get_boolean_value(
        self, 
        label: str, 
        default: bool = False
    ) -> bool:
        """Get yes/no input from user."""

# Configuration properties
class SetupWriter:
    bases: ClassVar[dict[str, str]] = {
        "C": "console",
        "G": "gui", 
        "S": "service",
    }
    
    # User configuration
    name: str                    # Project name
    description: str             # Project description  
    script: str                  # Main Python script
    version: str                 # Project version
    executable_name: str         # Target executable name
    setup_file_name: str         # Output setup.py filename
    base_code: str              # Base type code (C/G/S)
    
    @property
    def base(self) -> str:
        """Get base name from code."""
    
    @property  
    def default_executable_name(self) -> str:
        """Generate default executable name from script."""

# Run interactive configuration
cxfreeze-quickstart

# Example interaction:
# Project name: MyApp
# Version [1.0]: 1.0.0  
# Description: My Python Application
# Python file to make executable from: main.py
# Executable file name [main]: MyApp
# (C) console application, (G) GUI application, or (S) service [C]: G
# Save setup script to [setup.py]: setup.py
# Run this now [n]: y

# Example generated setup.py
from cx_Freeze import setup, Executable

# Dependencies are automatically detected, but it might need
# fine tuning.
build_options = {'packages': [], 'excludes': []}

base = 'gui'

executables = [
    Executable('main.py', base=base, target_name='MyApp')
]

setup(name='MyApp',
      version='1.0.0',
      description='My Python Application',
      options={'build_exe': build_options},
      executables=executables)

# Configuration loading from pyproject.toml
def get_pyproject_tool_data() -> dict:
    """Load cx_Freeze configuration from pyproject.toml."""

[tool.cxfreeze]
executables = [
    {script = "main.py", base = "gui", target_name = "MyApp"}
]

[tool.cxfreeze.build_exe]
packages = ["tkinter", "requests"]
excludes = ["unittest", "test"]
include_files = [
    {source = "data/", dest = "data/"},
    "config.ini"
]

# Environment variable support
export DISTUTILS_DEBUG=1           # Enable debug mode
export CXFREEZE_SILENCE_WARNINGS=1 # Suppress warnings

# CI/CD integration
cxfreeze --script main.py --target-dir dist --silent
cxfreeze bdist_msi --target-name MyApp-$VERSION

# Shell completion and help
cxfreeze --help                     # General help
cxfreeze build_exe --help          # Command-specific help
cxfreeze --version                  # Version information

# Common CLI errors and handling
class OptionError(Exception):
    """Invalid command-line option configuration."""

class SetupError(Exception):  
    """Setup script or configuration errors."""

# Debug output control
--debug                            # Enable debug mode
--verbose                          # Verbose output
DISTUTILS_DEBUG=1                  # Environment debug flag