build.py

Build utilities for creating distributable Pyloid applications using PyInstaller with advanced optimization features.

Overview

Pyloid provides two main build utilities:

pyinstaller: Enhanced PyInstaller wrapper with rich terminal interface
optimize: Post-build optimization to reduce application size

These utilities work together to create optimized, distributable Pyloid applications for all platforms.

Building Applications

pyinstaller

Builds a PyInstaller application for Pyloid with rich terminal interface and real-time progress monitoring.

For complete PyInstaller options, see the official PyInstaller documentation.

from pyloid_builder.pyinstaller import pyinstaller

########## Usage ##########

# Basic build
pyinstaller('main.py', ['--onedir', '--windowed'])

# Advanced build with multiple options
pyinstaller(
    'main.py',
    [
        '--name=MyApp',
        '--onedir',
        '--windowed',
        '--icon=icon.ico',
        '--add-data=assets:assets',
    ]
)

Parameters

Prop

Type

Returns

NoneExecutes PyInstaller and displays build progress.

Optimizing Builds

optimize

Optimizes PyInstaller build output by removing unnecessary files based on spec file patterns to reduce application size.

This function only works with --onedir builds, not --onefile builds.

For detailed optimization options, see the optimize API documentation.

from pyloid_builder.optimize import optimize

########## Usage ##########

# Basic optimization
optimize('./dist/MyApp/_internal', './build/windows_optimize.spec')

# Platform-specific optimization
import platform
if platform.system() == 'Windows':
    optimize('./dist/MyApp/_internal', './build/windows_optimize.spec')
elif platform.system() == 'Darwin':
    optimize('./dist/MyApp.app', './build/macos_optimize.spec')
else:
    optimize('./dist/MyApp/_internal', './build/linux_optimize.spec')

Parameters

Prop

Type

Returns

NoneRemoves files according to spec patterns and displays optimization results.

Build Scripts

Basic Build Script

from pyloid_builder.pyinstaller import pyinstaller
from pyloid.utils import get_platform

# Configuration
main_script = './src-pyloid/main.py'
name = 'pyloid-app'
dist_path = './dist'
work_path = './build'

# Platform-specific icon
if get_platform() == 'windows':
    icon = './src-pyloid/icons/icon.ico'
elif get_platform() == 'macos':
    icon = './src-pyloid/icons/icon.icns'
else:
    icon = './src-pyloid/icons/icon.png'

if __name__ == '__main__':
    # Build with PyInstaller
    pyinstaller(
        main_script,
        [
            f'--name={name}',
            f'--distpath={dist_path}',
            f'--workpath={work_path}',
            '--clean',
            '--noconfirm',
            '--onedir',
            '--windowed',
            '--add-data=./src-pyloid/icons/:./src-pyloid/icons/',
            '--add-data=./dist-front/:./dist-front/',
            f'--icon={icon}',
        ],
    )

Build with Optimization

from pyloid_builder.pyinstaller import pyinstaller
from pyloid_builder.optimize import optimize
from pyloid.utils import get_platform

# Configuration
main_script = './src-pyloid/main.py'
name = 'pyloid-app'
dist_path = './dist'
work_path = './build'

# Platform-specific settings
if get_platform() == 'windows':
    icon = './src-pyloid/icons/icon.ico'
    optimize_spec = './src-pyloid/build/windows_optimize.spec'
    internal_path = f'{dist_path}/{name}/_internal'
elif get_platform() == 'macos':
    icon = './src-pyloid/icons/icon.icns'
    optimize_spec = './src-pyloid/build/macos_optimize.spec'
    internal_path = f'{dist_path}/{name}.app'
else:  # linux
    icon = './src-pyloid/icons/icon.png'
    optimize_spec = './src-pyloid/build/linux_optimize.spec'
    internal_path = f'{dist_path}/{name}/_internal'

if __name__ == '__main__':
    # Step 1: Build with PyInstaller
    pyinstaller(
        main_script,
        [
            f'--name={name}',
            f'--distpath={dist_path}',
            f'--workpath={work_path}',
            '--clean',
            '--noconfirm',
            '--onedir',
            '--windowed',
            '--add-data=./src-pyloid/icons/:./src-pyloid/icons/',
            '--add-data=./dist-front/:./dist-front/',
            f'--icon={icon}',
        ],
    )

    # Step 2: Optimize the build
    optimize(internal_path, optimize_spec)

    print(f"✅ {name} built and optimized successfully!")

Build Options

Common PyInstaller Options

Option	Description
`--onedir`	Create a single directory bundle (recommended)
`--windowed`	Create a windowed application (no console)
`--console`	Create a console application
`--icon=file.ico`	Set application icon
`--name=AppName`	Set application name
`--clean`	Clean cache and temporary files
`--noconfirm`	Replace output directory without confirmation
`--add-data=src:dst`	Add additional data files
`--hidden-import=module`	Include hidden imports

Spec File Format

Optimization uses spec files that define which files to remove. Create platform-specific spec files:

windows_optimize.spec:

PySide6/translations/*.qm
PySide6/translations/qtwebengine_locales/*.pak
!PySide6/translations/qtwebengine_locales/en-US.pak
PySide6/qml
PySide6/Qt63D*
PySide6/Qt6Charts*
PySide6/Qt6DataVisualization*
# ... etc

macos_optimize.spec:

Contents/Frameworks/PySide6/Qt/lib/Qt3D*
Contents/Frameworks/PySide6/Qt/lib/QtCharts*
Contents/Resources/PySide6/Qt/qml
Contents/Resources/PySide6/Qt/translations
# ... etc

Common Optimization Targets

Category	Examples	Purpose
Qt Components	`Qt63D`, `Qt6Charts`, `Qt6Multimedia*`	Remove unused Qt libraries
Translations	`.qm`, `qtwebengine_locales/.pak`	Keep only essential locales
QML Files	`qml/`	Remove if not using QML
Debug Files	`.pdb`, `_debug.*`	Remove debug symbols
Python StdLib	`tcl/`, `tk/`, `test_*`	Remove unused standard library parts

Platform-Specific Considerations

Windows:

Target: dist/AppName/_internal/
Remove: Qt DLLs, debug files, unused translations

macOS:

Target: dist/AppName.app/
Remove: Framework libraries, QML resources, translations

Linux:

Target: dist/AppName/_internal/
Similar to Windows but may include additional system libraries

Running Builds

npm run build

Troubleshooting

PyInstaller Issues

Build fails with import errors:

Use --hidden-import to include missing modules
Check that all dependencies are installed in the build environment

Application won't start:

Ensure all data files are included with --add-data
Check that the main script path is correct
Verify that required DLLs/.so files are not removed during optimization

Large bundle size:

Use the optimize function with appropriate spec files
Review included packages and remove unnecessary ones

Icon not showing:

Ensure the icon path is correct and the file exists
Use platform-appropriate icon formats (.ico for Windows, .icns for macOS, .png for Linux)

Optimization Issues

Optimization removes required files:

Check spec file patterns - use exclude patterns (!) to protect important files
Test the application after optimization to ensure it still works
Start with minimal optimization and gradually add more patterns

Spec file not found:

Ensure spec files exist in the correct location
Check file paths in your build script
Use absolute paths if relative paths cause issues

Optimization takes too long:

Large applications may take time to scan
Consider excluding large directories from scanning
Use more specific patterns instead of broad wildcards

Application crashes after optimization:

Some Qt libraries might be required even if not directly used
Check for missing dependencies in error logs
Adjust spec file to be less aggressive

Platform-Specific Issues

Windows:

Ensure Visual C++ redistributables are handled correctly
Check that all required DLLs are preserved
Icon format must be .ico

macOS:

Code signing may be required for distribution
Ensure app bundle structure is maintained
Check Info.plist requirements

Linux:

System libraries may need to be included
Check for missing .so files
Ensure proper permissions on executable

build.py

On this page