PyInstaller GUI Wrapper - User Manual

English

1. Introduction

The PyInstaller GUI Wrapper is a desktop application that provides a graphical user interface (GUI) for PyInstaller, a popular tool for converting Python scripts into standalone executable applications. This wrapper aims to simplify the build process, especially for projects adhering to a specific directory structure, and offers features like automatic version information injection.

2. Prerequisites

Before using the PyInstaller GUI Wrapper, ensure you have the following installed:

Python 3.x: The wrapper is a Python application itself.
PyInstaller: This is the core tool used for building executables. Install it via pip:
```
pip install pyinstaller
```
Git (Recommended): While optional, Git is required if you want the wrapper to automatically extract version information (tags, commit hashes, branch names) from your project's Git repository and inject it into your build.

3. Launching the Application

If you have the source code, you can run the PyInstaller GUI Wrapper from your terminal by navigating to its root directory and executing:

python -m pyinstallerguiwrapper

If you have a compiled executable of the wrapper, simply run that executable.

4. Main Interface Overview

The main window of the PyInstaller GUI Wrapper is divided into several sections:

Project Directory:
- Main Project Directory: An entry field (read-only) showing the path to the selected project.
- Browse...: A button to open a dialog to select the root directory of the Python project you wish to build.
Derived Paths (Automatic):
- This section displays the paths that the wrapper automatically attempts to find based on your project directory selection and standard conventions. It helps verify if your project structure is recognized correctly.
- Script Found: Shows the path to the detected __main__.py file.
- Spec File Found: Shows the path to the detected projectname.spec file.
- Icon Found: Shows the path to the detected projectname.ico (or platform-equivalent) file.
- Status messages like "N/A" or "NOT FOUND!" will indicate if a file is not present or could not be located.
Options Tabs:
- Basic Options (from Spec/GUI):
  - App Name: The name of your application. This can be derived from the project name, loaded from an existing .spec file, or manually entered.
  - Icon File: Path to the application icon. Can be auto-detected, loaded from a spec, or selected manually using "Browse...". The "Clear" button removes the selection.
  - Single File (One Executable): Checkbox corresponding to PyInstaller's --onefile option. Creates a single executable file.
  - Windowed (No Console): Checkbox corresponding to PyInstaller's --windowed (or --noconsole) option. For GUI applications that should not open a console window.
- Additional Files (from Spec/GUI):
  - Files/Folders to Include: A listbox displaying files or folders to be added to your application bundle.
  - Add File...: Opens a dialog to select an individual file to include.
  - Add Folder...: Opens a dialog to select an entire folder to include.
  - Remove Selected: Removes the highlighted item from the list.
  - When adding files/folders, you'll be prompted for the destination path within the bundle (e.g., . for the root, data/ for a subfolder). Source paths are stored relative to the project root.
Build Log: A text area that displays real-time output and log messages from the PyInstaller build process and from the wrapper itself.
Build Executable: The main action button to start the build process. It is disabled until a valid project directory with the essential files is selected.

5. Workflow: Building Your Python Project

5.1. Selecting Your Project

Click the "Browse..." button in the "Project Directory" section.

Navigate to and select the root directory of the Python project you want to package.

Expected Project Structure: The wrapper works best with projects structured as follows:

YourProjectRoot/
├── yourprojectroot/      # Source code subfolder (lowercase project name)
│   ├── __init__.py
│   ├── __main__.py     # Main entry point for your application
│   └── ... (other .py files and sub-packages)
├── yourprojectroot.spec  # PyInstaller spec file (optional, will be generated/overwritten)
└── yourprojectroot.ico   # Application icon (optional, platform extensions vary)

Once selected, the "Derived Paths" section will update, showing which of the expected files were found. If essential files like __main__.py or the .spec file (if you intend to use an existing one that is then modified by the GUI) are not found, the "Build Executable" button may remain disabled.

5.2. Automatic Version File Generation (`_version.py`)

If the selected project directory (YourProjectRoot) is a Git repository:

The wrapper will attempt to extract version information (latest tag, commit hash, current branch, and dirty status if any uncommitted changes exist).
It will then automatically create or overwrite a file named _version.py inside your project's source subfolder (e.g., YourProjectRoot/yourprojectroot/_version.py).
This _version.py file will contain:
- Variables like __version__, GIT_COMMIT_HASH, GIT_BRANCH, BUILD_TIMESTAMP, and IS_GIT_REPO.
- A helper function get_version_string(format_string=None) that you can call from your application's code to get a formatted string of this version information.
- Example of format_string placeholders: {{version}}, {{tag}}, {{commit_short}}, {{branch}}, {{dirty}}, {{timestamp}}.
If the project directory is not a Git repository, or if Git commands fail, _version.py will still be created but will contain default "unknown" values.

To use this in your application, import _version and call _version.get_version_string() or access the variables directly. See the README.md for an example.

5.3. Configuring Build Options

Basic Options:
- Review and set the App Name.
- Select an Icon File if desired (this overrides any auto-detected icon or icon from a loaded spec).
- Choose between Single File (one-file build) or a directory build (one-dir, by unchecking "Single File"). One-dir is often more stable for GUI applications.
- Select Windowed (No Console) for GUI applications. Uncheck it for console-based applications.
Additional Files:
- Use "Add File..." or "Add Folder..." to include any necessary data files, assets, or non-Python dependencies.
- You will be prompted for the destination path within the application bundle. For example, if you add assets/image.png and specify the destination as images, it will be available in your bundled app at images/image.png.
- Paths are relative to the .spec file (which is in your project root).

Note: If a .spec file was found in your project root, its options are loaded into the GUI. Any changes you make in the GUI will be used to regenerate and overwrite this .spec file before the build starts.

5.4. Starting the Build

Once you have selected your project and configured the options, click the "Build Executable" button.
The wrapper will:
- Generate/update the _version.py file in your target project's source folder.
- Generate/update the .spec file in your project root based on the current GUI settings.
- Execute PyInstaller in a separate thread.
The Build Log will show real-time output from PyInstaller.
Upon completion (or failure), a message box will appear, and the build log will contain the final status.

5.5. Locating the Executable

If the build is successful, the bundled application will be located in a subfolder named _dist (by default) within your selected project directory (e.g., YourProjectRoot/_dist/YourAppName/).
Temporary build files will be in a _build subfolder.

6. Tips and Troubleshooting

"NOT FOUND!" in Derived Paths: Double-check your project's folder structure and file naming against the expected conventions. Ensure the __main__.py and (if you're relying on an existing one) projectname.spec files are correctly placed.
Build Fails / Executable Doesn't Run:
1. Check the Build Log: Look for errors or warnings from PyInstaller.
2. Console Mode for Debugging: If your executable doesn't start, temporarily edit the generated .spec file (e.g., yourprojectroot.spec) and change console=False to console=True in the EXE() block. Then, rebuild by running pyinstaller yourprojectroot.spec --clean from the command line in your project root. When you run the executable, a console window will appear and show any Python errors.
3. Hidden Imports: Some Python libraries use dynamic imports that PyInstaller might miss. You may need to add them to the hiddenimports list in your .spec file or via a hook file.
Git Information Not Injected: Ensure Git is installed and accessible in your system's PATH on the machine where you are running the PyInstaller GUI Wrapper. Also, ensure the project directory you selected is indeed a Git repository.

9.4 KiB Raw Permalink Blame History