PyAppExec

<div align="center"> <img src="docs/logo-256.png" alt="PyAppExec logo" width="128" height="128"> </div>

PyAppExec is a cross-platform bootstrapper that prepares a Python application for end users. It locates (or installs) a suitable Python interpreter, provisions an isolated virtual environment, downloads any third-party tooling you bundle, installs Python dependencies, and finally launches your target script - all driven by a simple .ini file specification. For a friendlier setup flow, PyAppExec ships a companion installer with a graphical interface that auto-detects your project layout, copies the launcher into place, generates a tailored .ini you can fine-tune, and produces ready-to-ship launcher folders for Windows/Linux or a branded .app bundle with your icon on macOS.

<div align="center"> <img src="resources/screenshots/pyappexec.gif" alt="PyAppExec launcher screencast" width="720"> </div>

• Overview
• Key Features
• How It Works
• Repository Layout
• Getting Started
  • Prerequisites
  • Build
  • Run
• Configuration
  • Main section
  • Requirements section
  • Example
• Bundling External Artifacts
• Sample Application
• Development Notes
• Troubleshooting
• Contributing
• License
• Acknowledgements

Overview

Many Python applications require users to install Python, set up virtual environments, download extra outside dependencies, and install Python packages before they can run the app. PyAppExec automates those steps so you can distribute a native binary launcher alongside your Python project. Ship the PyAppExec binary, ship an .ini configuration that describes what the launcher should do, and PyAppExec takes care of the rest.

While PyInstaller, cx_Freeze and similar tools are excellent when you need a completely self-contained binary, PyAppExec deliberately lightens the shipped package, relegating the heavier dependency downloads to the end user’s machine during the first run. Unlike these “freezer” tools that bundle an entire Python runtime and all dependencies into a monolithic executable, PyAppExec keeps your Python project intact and simply orchestrates interpreter provisioning, virtual environments, and external tooling on the user’s machine. That makes updates faster (swap out your Python sources without rebuilding a frozen binary), reduces download size, and keeps the runtime transparent for power users who still want to inspect or modify the Python code.

Key Features

• Detects the highest priority Python interpreter on the PATH and validates its version.
• Allows per-platform .ini sections so Windows, macOS, and Linux can point at platform-specific scripts, download URLs, and tooling.
• On Linux, optionally installs Python via apt, dnf, or pacman if a suitable interpreter is not found.
• Creates or reuses a per-project virtual environment and keeps a lightweight state file to avoid redundant pip install runs.
• Installs Python package dependencies from a configurable requirements file inside the virtual environment.
• Downloads and, when possible, installs external tools, using integrity checks to avoid re-downloading unchanged files.
• Launches the target Python entry point after the environment is ready, with stdout/stderr feedback in the terminal.
• Accepts optional command-line arguments and environment overrides from the .ini.
• Ships with an optional GUI front-end that surfaces progress, embedded terminal output, and error dialogs.
• Includes a GUI installer plus packaging script that auto-detects project structure, generates a starter .ini for you to customize, and produces ready-to-share artifacts (launcher folders for Windows/Linux and a branded .app on macOS).
• Emits structured logs via spdlog so you can tail progress or integrate with external log collectors.
• Embeds helper Python scripts via GLib resources so the launcher has zero runtime script dependencies.

How It Works

1. PyAppExec reads pyappexec.ini and selects the [<OS>:main] and [<OS>:requirements] sections that match the current platform (Linux, MacOS, Windows).
2. It resolves relative paths against the directory that contains the .ini file.
3. If no suitable Python interpreter is found, PyAppExec can attempt an installation via common package managers (on Linux) or fall back to the configured download URL so you can prompt users to install it manually.
4. A virtual environment is created (or reused) at the configured location.
5. Python dependencies from requirements.txt (or whichever file you point to) are installed inside that environment. A signature file prevents redundant installs when the requirements file has not changed.
6. For each external requirement defined in the .ini file, PyAppExec checks whether it is already present and satisfies the minimum version. Missing dependencies are downloaded to the distrib/ directory or installed via a custom command.
7. Finally, the target Python script is invoked using the virtual environment's interpreter.

Repository Layout

.
├── CMakeLists.txt          # CMake build configuration for the C++ launcher
├── main.cpp                # Entry point that drives the CLI/GUI bootstrapper
├── include/                # Public headers shared between the CLI and GUI layers
├── lib/                    # Core launcher implementation (AppBootstrapper, utils, etc.)
├── gui/                    # Qt6 widgets for the optional front-end (MainWindow, GuiRunner)
├── resources/              # GLib resource manifest plus embedded Python helper scripts
├── scripts/                # Source copies of the embedded helper scripts
├── LICENSE / README.md     # Project metadata and documentation

Getting Started

Prerequisites

To build the launcher you need:

• A C++20 toolchain (GCC 11+, Clang 13+, or MSVC 19.30+).
• CMake 3.16 or newer.
• pkg-config and the development headers for gio-2.0 (part of GLib) — these provide glib-compile-resources and the GIO runtime used to embed scripts. On macOS install them with brew install glib libffi zlib.
• Qt 6 (Widgets module) headers and libraries for the optional GUI front-end.
• spdlog (header-only logging library) for structured logging output.
• Boost with the Process headers and the Filesystem/System libraries (Boost.Process depends on the compiled boost_filesystem + boost_system pair on Linux).
• curl (Linux/macOS) or the Windows URLMon APIs (already part of Win32) for downloading requirement archives.

Build

Linux

Install the toolchain and development headers via your package manager before running CMake. Example commands:

• Debian-based (Ubuntu, Mint, Pop!_OS):

  sudo apt update
  sudo apt install build-essential cmake pkg-config libglib2.0-dev qt6-base-dev libspdlog-dev libboost-dev libboost-filesystem-dev libboost-system-dev libcurl4-openssl-dev
  

  If cmake reports Could not find a package configuration file provided by "boost_filesystem", it means the libboost-filesystem-dev package is missing; install it alongside libboost-dev so Boost.Process can link against the filesystem/system libraries.

• Fedora-based (Fedora, RHEL, CentOS Stream):

  sudo dnf install @development-tools cmake pkgconf-pkg-config glib2-devel qt6-qtbase-devel spdlog-devel boost-devel libcurl-devel
  

• Arch-based (Arch, Manjaro, EndeavourOS):

  sudo pacman -S --needed base-devel cmake pkgconf glib2 qt6-base spdlog boost curl
  

After installing the dependencies, build with:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

macOS (Homebrew)

1. Install the dependencies:

   brew install glib libffi zlib boost qt spdlog
   

   Homebrew's pkg-config should expose gio-2.0 after those installs; if it does not, export PKG_CONFIG_PATH="/opt/homebrew/opt/libffi/lib/pkgconfig:/opt/homebrew/lib/pkgconfig:/opt/homebrew/share/pkgconfig:$PKG_CONFIG_PATH" (adjust the prefixes if needed) and rerun pkg-config --modversion gio-2.0 to confirm it resolves to the Homebrew install.
2. Build:

   cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build --parallel
   

   Or run scripts/build_macos.sh to apply the PKG_CONFIG_PATH tweak automatically and build in one step.

Windows (MSVC + vcpkg)

1. Install Visual Studio 2022 (Desktop development with C++) or the standalone Build Tools so cl.exe, the Windows SDK, and CMake integration are available.
2. Bootstrap vcpkg and install the dependencies:

   git clone https://github.com/microsoft/vcpkg.git C:\dev\vcpkg
   C:\dev\vcpkg\bootstrap-vcpkg.bat
   C:\dev\vcpkg\vcpkg.exe install qtbase:x64-windows spdlog:x64-windows
   

3. Configure the project from a “x64 Native Tools Command Prompt for VS” (or Developer PowerShell) so MSVC is on PATH:

   cmake -S . -B build `
         -DCMAKE_BUILD_TYPE=Release `
         -DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake `
         -DVCPKG_TARGET_TRIPLET=x64-windows
   cmake --build build --parallel
   

   If CMake still complains that Qt6 was not found, confirm that qtbase:x64-windows was installed and that the same vcpkg root is passed via CMAKE_TOOLCHAIN_FILE. Setting VCPKG_ROOT=C:\dev\vcpkg globally also works. If you run the PowerShell helper (scripts/build_windows.ps1) from the Developer shell, first relax the session p