Skip to content

windows_setup.md

Latest commit

 

History

History
232 lines (168 loc) · 6.12 KB

windows_setup.md

File metadata and controls

232 lines (168 loc) · 6.12 KB
Raw

Windows Development Environment Setup Guide

This guide provides step-by-step instructions for setting up the developer and contributor environment for AmplifyP on Windows. It covers installing prerequisites, setting up Python virtual environments, running the application with hot-reload, executing unit and end-to-end (E2E) tests, and compiling release packages.

1. Prerequisites

Before setting up the project, ensure the following software is installed on your Windows machine:

A. Python (3.12 or Higher)

AmplifyP requires Python 3.12 or higher.

  • Installation via Winget: Open PowerShell or Command Prompt and run: 
    winget install Python.Python.3.12
  • Manual Installation: Download and run the installer from the official Python Website.

Important

During the Python installation process, ensure the checkbox for "Add Python to PATH" (or similar) is ticked. This is necessary to access Python from the command line.

B. Git

Required for cloning the repository and managing version control.

  • Installation via Winget: 
    winget install Git.Git
  • Manual Installation: Download and install Git from Git for Windows.

C. Inno Setup (Optional - for compiling the installer)

Required only if you wish to build the standalone installer executable (.exe).

  • Installation via Winget: 
    winget install JRSoftware.InnoSetup
  • Installation via Chocolatey: 
    choco install innosetup -y

2. Cloning the Repository

Open PowerShell, Command Prompt, or Git Bash, and navigate to the directory where you want to store the project. Run:

git clone https://github.com/fangfufu/AmplifyP.git
cd AmplifyP

3. Creating and Activating the Virtual Environment

Set up a Python virtual environment under .venv at the root of the repository. Follow the instructions for your preferred terminal shell:

PowerShell

# Create the virtual environment
python -m venv .venv

# Activate the virtual environment
.venv\Scripts\Activate.ps1

Note

If you receive an execution policy error (e.g. Script execution is disabled on this system), run the following command to allow running scripts in the current process:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

Command Prompt (cmd.exe)

:: Create the virtual environment
python -m venv .venv

:: Activate the virtual environment
.venv\Scripts\activate.bat

Git Bash

# Create the virtual environment
python -m venv .venv

# Activate the virtual environment
source .venv/Scripts/activate

4. Installing Dependencies

With the virtual environment activated, install the package in editable mode along with development and end-to-end testing dependencies:

pip install -e ".[dev,e2e]"

5. Running the Application

Running the Python Script Directly

To launch the graphical user interface (GUI) from source:

python src/main.py

To launch the web version locally at port 34521:

python src/main.py --web

Running with Hot-Reload (Flet CLI)

To enable hot-reload (so that UI changes are applied automatically when files are saved), run the application using the Flet CLI:

  • Desktop application: 
    flet run -r src/main.py
  • Web application: 
    flet run -w -r src/main.py
  • Web application on a specific port (e.g. port 34521): 
    flet run -w -r -p 34521 src/main.py

6. Verification and Code Quality

To verify your changes and maintain high code quality, use the following tools:

A. Pre-commit Verification (prek)

Before committing your work, run the quality checks using prek. This ensures that your code complies with formatting, linting, and type-checking rules:

prek run --all-files

This runs:

  • pre-commit-hooks housekeeping checks (YAML validation, trailing whitespace, end-of-file newlines, JSON formatting, and more).
  • yamlfmt for formatting configuration YAML files.
  • yamllint for YAML linting.
  • ruff for linting and code formatting checks.
  • mypy for strict static type-checking.
  • pyright for additional static type-checking.
  • pytest for the fast test suite (E2E and CI-only tests are excluded via the default markers).
  • vulture for detecting unused code.
  • typos for identifying spelling errors.
  • mdformat for consistent markdown formatting.

B. Running Tests

We use pytest for unit, integration, and browser tests.

1. Unit and Integration Tests

To run the fast, non-GUI tests:

pytest

2. End-to-End (E2E) Browser Tests

To run the Playwright browser automation tests that verify the web interface's behaviour:

# Ensure playwright browser binaries are installed
playwright install

# Run the E2E tests
pytest -m e2e

7. Packaging and Building (Windows Releases)

To package the application and generate release assets on Windows, you can run the build_windows.ps1 script located at the root of the repository. This script automates generating the Git SHA, building the Flet binary, archiving the build as a ZIP file, and compiling the setup installer using Inno Setup.

Open PowerShell and run:

.\build_windows.ps1

Note

An Android SDK or toolchain is not required when building for Windows. The build script automatically skips Flutter Doctor Android checks and temporarily disables Android requirements in the Flutter configuration.

Output Artefacts

After the script runs successfully, the following files and directories will be created:

  • build\AmplifyP: The compiled Flet Windows application folder.
  • amplifyp-windows-<version>.zip: A ZIP archive of the application directory.
  • amplifyp-windows-setup-<version>.exe: The standalone Windows installation wizard (only if Inno Setup's iscc compiler is available on the system PATH or found in a supported standard installation directory).