⚠️ Clean-Room / Educational

This project is educational and Open Source. No code is copied from other emulators. Implementation based solely on technical documentation and permitted tests.

Build Infrastructure and Generation of Executables

Date:2025-12-18 StepID:0095 State: Verified

Summary

A complete build and packaging infrastructure has been created to generate executables independent of the Viboy Color emulator. Implemented a master build script that detects the operating system and uses PyInstaller to generate portable binaries. Furthermore, they created Base configurations for professional installers on Windows (Inno Setup), Linux (.deb) and macOS (py2app). The Windows executable was successfully generated with a size of 27.81 MB.

Hardware Concept

This step is not directly related to the Game Boy hardware emulation, but rather to thedistribution and packagingof the emulator software. However, it is a step critical to make the project accessible to end users without installing Python nor dependencies manually.

PyInstalleris a tool that "freezes" Python applications into executables independent. It works by analyzing the code, detecting all dependencies (modules, libraries, data files) and packaging them together with the Python interpreter into a single binary. This allows you to distribute Python applications as if they were native applications.

For an emulator like Viboy Color, which depends on pygame-ce and other modules, PyInstaller automatically includes all the necessary DLLs and resources, creating a completely executable standalone that can run on any Windows machine without prior installations.

Implementation

A modular build system was created that supports multiple platforms and prepares the project for professional distribution.

Components created/modified

  • requirements.txt: Added PyInstaller as a development dependency
  • tools/build_release.py: Master build script with OS detection and PyInstaller execution
  • installers/windows_setup.iss: Configuring Inno Setup to create Windows installer
  • installers/linux/debian/DEBIAN/: Structure to create .deb package
  • installers/macos/setup.py: Configuring py2app to create bundle .app
  • installers/README.md: Complete documentation of the packaging process

Design decisions

1. Windowed mode (--noconsole): It was chosen to create executables without a console to a more professional experience. The user will not see the black terminal behind the window of the emulator. This is especially important on Windows where GUI applications traditionally They do not show console.

2. onefile mode: A single executable file was generated instead of a folder with multiple files. This simplifies the distribution, although it slightly increases the processing time. startup (PyInstaller extracts the files to a temporary directory when running).

3. Inclusion of assets: PyInstaller was configured to include the `assets/` folder inside the executable using `--add-data`. This allows the emulator to access icons and resources graphics without depending on external files.

4. Automatic OS detection: The script automatically detects the system operational and adjust PyInstaller parameters accordingly. On Windows it generates `.exe`, on Linux a binary without an extension, and on macOS a `.app` bundle.

5. Installer structure: Templates were created for all three systems main operating systems, although it can only be compiled on the corresponding OS. This prepares the project for future cross-platform distributions.

Affected Files

  • requirements.txt- Added pyinstaller>=6.0.0
  • tools/build_release.py- Master build script (new, 280 lines)
  • installers/windows_setup.iss- Inno Setup (new)
  • installers/linux/debian/DEBIAN/control- .deb package metadata (new)
  • installers/linux/debian/DEBIAN/postinst- Post-installation script (new)
  • installers/linux/debian/DEBIAN/postrm- Post-removal script (new)
  • installers/macos/setup.py- py2app configuration (new)
  • installers/README.md- Installer documentation (new)
  • release/ViboyColor.exe- Generated executable (29.16 MB)

Tests and Verification

Verification was performed by successfully executing the build script and generating of the executable.

Build Execution

  • Command executed: python tools/build_release.py
  • Around: Windows 11, Python 3.13.5
  • Result: ✅ Build completed successfully
  • Generated executable: release/ViboyColor.exe(29.16MB)

Validations carried out

  • ✅ PyInstaller correctly detected all dependencies (pygame-ce, numpy, etc.)
  • ✅ Icon included correctly (using .png as fallback)
  • ✅ The assets folder was packaged correctly
  • ✅ The executable was automatically moved to the folderrelease/
  • ✅ The size of the executable is reasonable (27.81 MB) for an application with pygame and all its dependencies

Executable structure

PyInstaller generated a self-contained executable that includes:

  • Python 3.13.5 Interpreter
  • pygame-ce library with all its DLLs
  • Standard Python modules required
  • Emulator source code (src/)
  • assets/ resources

Note: The executable has not yet been tested by running a ROM, but the structure and the build process were successful. The complete functional test will be performed in one step later when it is validated that the executable can load and run ROMs correctly.

Sources consulted

Educational Integrity

What I Understand Now

  • PyInstaller: It is a "freezing" tool that analyzes Python code, detects transitive dependencies and packages everything into an executable. Use a bootloader which extracts the files to a temporary directory and runs the application.
  • onefile vs onedir mode: Onefile creates a single file but has overhead extraction at the beginning. Onedir is faster but requires distributing an entire folder.
  • Dependency detection: PyInstaller analyzes the imports and searches for modules in sys.path, automatically including libraries like pygame and its native DLLs.
  • Cross-platform installers: Each OS has its standard tool (Inno Setup for Windows, dpkg for Debian, py2app for macOS). Installers add metadata, shortcuts and uninstallers.

What remains to be confirmed

  • Executable functionality: It has not yet been tested that the generated .exe can load and run ROMs correctly. This requires a full functional test.
  • Performance: Onefile mode has extraction overhead. If the performance is critical, onedir mode might need to be evaluated.
  • Antivirus false positives: PyInstaller sometimes generates false positives. If this occurs in distribution, it may be necessary to sign the executable with a certificate of code.
  • Version Compatibility: The executable is tied to the Python version and used libraries. Future changes to dependencies will require regenerating the executable.

Hypotheses and Assumptions

It is assumed that the executable will work correctly because PyInstaller included all the detected dependencies. However, some dynamic dependencies (loaded with importlib or __import__) may not be detected automatically. If there are runtime problems, you will need to add custom PyInstaller hooks or use --hidden-import.

Next Steps

  • [ ] Test the generated executable by running a test ROM
  • [ ] Verify that the assets are loaded correctly from the executable
  • [ ] Create a Windows installer using Inno Setup (requires installing Inno Setup)
  • [ ] Document the distribution and release process
  • [ ] Consider signing the executable with a code certificate to avoid false positives
  • [ ] Evaluate whether onedir mode offers better performance than onefile
  • [ ] Prepare builds for Linux and macOS when you have access to those systems