Building the Executable

Relevant source files

The following files were used as context for generating this wiki page:

• build.py
• build.sh
• build.bat
• scripts/install.sh
• scripts/install.ps1
• main.py
• logo.py

The build system for cursor-free-vip is designed to package the Python application into a single, standalone executable for Windows, macOS, and Linux. This process is primarily managed by a core Python script, build.py, which utilizes PyInstaller. This core script is then invoked by platform-specific shell scripts (build.sh for Linux/macOS and build.bat for Windows) that handle environment setup and dependency installation.

The end goal is to create a distributable artifact that users can download and run without needing a Python interpreter or any of the project's dependencies installed on their system. The installation scripts (install.sh and install.ps1) further automate this by fetching the correct executable from the project's GitHub releases and running it.

Build Process Overview

The build process is initiated by running the appropriate script for the host operating system. The general flow involves setting up a virtual environment, installing dependencies, and then invoking the main build script.

This diagram illustrates the high-level flow from a developer running a build script to a user receiving the executable.

Core Build Logic (build.py)

The central component of the build system is build.py. It uses the PyInstaller library to bundle the Python application into a single executable file.

Sources: build.py

Key Steps

1. Clean Environment: The script starts by cleaning the screen and removing the build/ directory to ensure a fresh build without any cached artifacts.
   Sources: build.py:47-52
2. Load Version: It loads environment variables from the .env file to get the project version, which is used in the output filename. The default is 1.0.0 if not specified.
   Sources: build.py:55-56, logo.py:10-12
3. Determine OS and Output Name: The script detects the operating system (Windows, Linux, or mac) to construct the final executable name. The naming convention is CursorFreeVIP_{version}_{os_type}{extension}.
   Sources: build.py:65-76
4. Execute PyInstaller: It runs the PyInstaller command using a build.spec file. This file contains the detailed configuration for PyInstaller.
   Sources: build.py:79
5. User Feedback: During the build, a LoadingAnimation class provides a simple spinner in the console to indicate that the process is running.
   Sources: build.py:14-33, build.py:62-63
6. Verification: After the build command completes, it checks if the expected output file was created in the dist/ directory and reports success or failure.
   Sources: build.py:83-88

The following flowchart details the logic within build.py.

Output Artifacts

The build process generates a single executable file in the dist/ directory. The name is dynamically generated based on the version and operating system.

OS	os_type	Extension (ext)	Example Filename (v1.0.0)
Windows	windows	.exe	CursorFreeVIP_1.0.0_windows.exe
Linux	linux	(none)	CursorFreeVIP_1.0.0_linux
macOS	mac	(none)	CursorFreeVIP_1.0.0_mac

Sources: build.py:65-76

Build Orchestration Scripts

Platform-specific scripts are provided to simplify the build process by automating environment setup and dependency installation.

Linux/macOS (build.sh)

This script prepares the environment on Unix-like systems.

• Dependency Check: For Debian-based systems, it checks for python3, python3-pip, and python3-venv and attempts to install them using apt-get if they are missing.
• Virtual Environment: It creates a Python virtual environment in a venv directory and activates it.
• Install Dependencies: It upgrades pip and installs all required packages from requirements.txt.
• Run Build: It executes python3 build.py to start the core build process.
• Cleanup: After the build, it deactivates and removes the venv directory.

Sources: build.sh

Windows (build.bat)

This batch script handles the build process on Windows.

• Privilege Handling: It checks for administrator privileges. If not present, it requests elevation to create the virtual environment. It then re-runs itself with normal user privileges for the subsequent steps.
• Virtual Environment: It creates a venv if one doesn't exist and activates it.
• Install Dependencies: It iterates through requirements.txt and installs any missing packages.
• Run Build: It calls python build.py to create the executable.

Sources: build.bat

Installation and Distribution

Once the executables are built and uploaded to GitHub Releases, users can run installation scripts that automate the download and execution process.

install.sh (Linux/macOS) & install.ps1 (Windows)

Both scripts perform a similar set of actions tailored to their respective platforms:

1. Get Latest Version: They query the GitHub API to find the latest release tag.
2. Detect OS/Architecture: They determine the user's operating system and architecture (e.g., mac_arm64, linux_x64, windows) to select the correct build artifact.
3. Construct Download URL: A URL is formed pointing to the specific executable in the GitHub release assets.
4. Download: The script downloads the executable to the user's "Downloads" folder.
5. Execute: It makes the downloaded file executable (on Linux/macOS) and runs it, requesting administrator/sudo privileges if necessary.

The following sequence diagram shows the interactions during the installation process.