128 lines
9.4 KiB
Markdown
128 lines
9.4 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
1. Click the **"Browse..."** button in the "Project Directory" section.
|
|
2. 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)
|
|
```
|
|
3. 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:
|
|
|
|
1. The wrapper will attempt to extract version information (latest tag, commit hash, current branch, and dirty status if any uncommitted changes exist).
|
|
2. It will then automatically create or overwrite a file named `_version.py` inside your project's source subfolder (e.g., `YourProjectRoot/yourprojectroot/_version.py`).
|
|
3. 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}}`.
|
|
4. 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
|
|
|
|
1. **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.
|
|
2. **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
|
|
|
|
1. Once you have selected your project and configured the options, click the **"Build Executable"** button.
|
|
2. 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.
|
|
3. The **Build Log** will show real-time output from PyInstaller.
|
|
4. 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.
|
|
|
|
--- |