Development Environment Setup
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the necessary steps and components for setting up a local development environment for the cursor-free-vip project. It covers dependency installation, configuration management, and the build process for creating distributable executables. The setup is designed to be cross-platform, with specific scripts for Windows, macOS, and Linux.
The core of the development workflow involves installing Python dependencies, understanding the application's configuration structure managed by config.py, and using the provided build scripts (build.py, build.sh, build.bat) to package the application with PyInstaller.
1. Prerequisites and Dependencies
The project relies on Python and a set of external libraries. The build scripts for Linux and Windows also specify the need for a Python virtual environment.
1.1. System Dependencies
The build scripts check for the following system-level tools:
- Python 3: The primary programming language.
- pip: The package installer for Python.
- venv: For creating isolated Python environments.
Sources: build.sh:8-18
1.2. Python Libraries
All required Python libraries are listed in the requirements.txt file. The build scripts (build.sh, build.bat) automatically install these dependencies into a virtual environment.
| Library | Description |
|---|---|
requests | Used for making HTTP requests, primarily to check for new versions and interact with APIs. |
colorama | Enables colored terminal text for better user interface feedback. |
python-dotenv | Manages environment variables, used in logo.py and build.py to load the application version. |
pyinstaller | Packages the Python application and its dependencies into a single executable file. |
arabic_reshaper | Used in main.py to correctly render Arabic text in the terminal. |
python-bidi | Works with arabic_reshaper for bidirectional text display, essential for Arabic language support. |
pywin32 | (Windows-only) Provides access to Windows APIs, used for checking admin privileges and path discovery. |
Sources: requirements.txt, main.py:14-19, build.sh:31-35, build.bat:37-42
2. Configuration Management
Application settings are managed through a config.ini file, which is automatically generated and maintained by the config.py module.
2.1. Configuration File Location
The config.ini file is created in a hidden directory within the user's "Documents" folder:
- Path:
<User Documents>/.cursor-free-vip/config.ini
The get_user_documents_path() function in config.py and other modules determines the location of the Documents folder across Windows, macOS, and Linux. If the directory cannot be created, it falls back to a temporary directory.
Sources: config.py:23-39, totally_reset_cursor.py:29-45
2.2. Configuration Setup Flow
The setup_config function in config.py initializes the configuration. If config.ini does not exist, it is created with default values. If it exists, the function ensures all necessary sections and options are present, adding any that are missing.
This diagram illustrates the logic for setting up the configuration file.
Sources: config.py:20-213
2.3. Key Configuration Sections
The config.ini file is structured into several sections to manage different aspects of the application.
| Section | Key | Description | Default Value (Example) |
|---|---|---|---|
| Browser | default_browser | The default web browser to use for automation tasks. | chrome |
chrome_path | Path to the Chrome executable. | Platform-specific default | |
| Timing | page_load_wait | Time range to wait for a page to load. | 0.1-0.8 |
max_timeout | Maximum timeout for certain operations. | 160 | |
| Utils | enabled_update_check | If True, the application checks for new versions on startup. | True |
| WindowsPaths | storage_path | (Windows) Path to Cursor's storage.json file. | %APPDATA%\Cursor\User\globalStorage\storage.json |
cursor_path | (Windows) Path to Cursor's application resources. | %LOCALAPPDATA%\Programs\Cursor\resources\app | |
| MacPaths | storage_path | (macOS) Path to Cursor's storage.json file. | ~/Library/Application Support/Cursor/User/globalStorage/storage.json |
| LinuxPaths | storage_path | (Linux) Path to Cursor's storage.json file. | ~/.config/cursor/User/globalStorage/storage.json |
Sources: config.py:58-213
3. Build Process
The project uses PyInstaller to package the Python scripts into a single executable. The build process is orchestrated by build.py and initiated by platform-specific shell scripts (build.sh for Linux/macOS, build.bat for Windows).
The general flow is as follows:
- A platform-specific script (
build.shorbuild.bat) is executed. - The script sets up a Python virtual environment (
venv). - It installs the dependencies from
requirements.txt. - It calls
python build.pyto run the PyInstaller build process. build.pycleans the previous build cache, reads the version from the.envfile, and executes thepyinstallercommand usingbuild.spec.- The final executable is placed in the
dist/directory with a platform-specific name.
This flowchart shows the high-level build process.
3.1. Build Output
The executable's name is dynamically generated based on the version and operating system. The naming convention is: CursorFreeVIP_{version}_{os_type}.
{version}is read from the.envfile.{os_type}is determined aswindows,linux, ormac.
Sources: build.py:70-78
4. Automated Installation
The repository provides automated installation scripts for a user-friendly setup. These scripts fetch the latest release from GitHub and run it.
4.1. Installation Flow
The install.sh (for Linux/macOS) and install.ps1 (for Windows) scripts perform the following actions:
- Check for Latest Version: They query the GitHub API to find the tag name of the latest release.
- Determine Asset Name: They construct the expected asset filename based on the OS and system architecture (e.g.,
CursorFreeVIP_{version}_windows.exeorCursorFreeVIP_{version}_linux_x64). - Download: The script downloads the corresponding executable from the GitHub release assets to the user's "Downloads" folder.
- Execute: The downloaded executable is made runnable (if necessary) and then executed.
The sequence diagram below illustrates this process.
Sources: scripts/install.sh, scripts/install.ps1
5. Conclusion
Setting up the development environment for cursor-free-vip involves standard Python practices, including virtual environments and dependency management via requirements.txt. The project is structured for cross-platform compatibility, with dedicated scripts for building and installing on Windows, macOS, and Linux. The centralized configuration in config.py allows for easy management of application paths and behavior, while the build.py script standardizes the process of creating distributable executables with PyInstaller.