Skip to content

developer.md

Latest commit

 

History

History
172 lines (132 loc) · 6.37 KB

developer.md

File metadata and controls

172 lines (132 loc) · 6.37 KB
Raw

ARS WireWorks — Developer Guide

Local development setup on Windows, macOS, and Linux (spec §14.4). For the cross-platform build and signing pipeline, see docs/release.md.

Prerequisites

  • Python 3.11 or newer (spec §11).
  • Git.
  • A C/C++ toolchain and SWIG — PyNEC ships no wheels and compiles from source. The per-OS sections below cover installing these.

Getting the source

git clone https://github.com/skip17331/wireworks.git
cd wireworks

Setting up a development environment

Install the per-OS prerequisites first (see below), then use a virtual environment, install the developer requirements, and install the package in editable mode:

python -m venv .venv
# activate the environment, then:
pip install -r requirements-dev.txt
# PyNEC ships only an sdist and its setup.py imports numpy at build time
# without declaring it as a build requirement, so build it out-of-band first:
# install numpy plus the setuptools backend, then build PyNEC with build
# isolation disabled so the build can import numpy. (Versions match the pins
# in pyproject.toml.)
pip install "numpy==2.2.1" setuptools wheel
pip install --no-build-isolation "PyNEC==1.7.3.4"
pip install -e .

Why the extra PyNEC step? A plain pip install -e . builds PyNEC in an isolated environment that has no numpy, and PyNEC's setup.py fails on import numpy. Building it first, without isolation, sidesteps that. Once PyNEC is installed the editable install finds it already satisfied and does not rebuild it.

Windows

  1. C/C++ toolchain and SWIG — PyNEC compiles from source. Install the Microsoft C++ Build Tools (the "Desktop development with C++" workload), and SWIG — for example with Chocolatey: choco install swig. SWIG must be on PATH.
  2. GTK runtime for weasyprint — weasyprint's PDF path needs the GTK libraries, which Windows does not ship. Install the GTK3 runtime (the weasyprint documentation links a current installer). Without it the app still runs and still produces PDFs — it falls back to the reportlab renderer — but the weasyprint path is unavailable.
  3. PySide6 bundles the Qt runtime, so no further system libraries are needed.

Create the virtual environment with py -3 -m venv .venv and activate it with .venv\Scripts\activate, then install as above.

macOS

  1. C/C++ toolchain — install the Xcode Command Line Tools with xcode-select --install. PyNEC compiles from source against them.

  2. SWIG and the weasyprint libraries — via Homebrew:

    brew install swig pango

    swig builds PyNEC; pango pulls in cairo, glib, and gdk-pixbuf — the runtime libraries weasyprint needs.

  3. On Apple Silicon, Homebrew installs under /opt/homebrew. If weasyprint cannot find its libraries, point the loader at them: export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib.

  4. PySide6 bundles the Qt frameworks, so no further system libraries are needed.

Create and activate the virtual environment, then install as above.

Linux

On Debian, Ubuntu, and derivatives, install the system libraries the app needs at build and run time before setting up the virtual environment:

sudo apt install \
    swig python3-dev build-essential \
    libpango-1.0-0 libpangocairo-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 \
    libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
    libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xinerama0 \
    libxcb-xkb1 libxkbcommon-x11-0 libegl1
  • swig, python3-dev, build-essential — PyNEC has no wheels and compiles from source via SWIG when pip install runs.
  • libpango-*, libcairo2, libgdk-pixbuf-2.0-0 — runtime libraries for weasyprint (the primary PDF path).
  • libxcb-*, libxkbcommon-x11-0, libegl1 — runtime libraries for Qt's xcb platform plugin. PySide6 bundles the plugin but not these. Without libxcb-cursor0 in particular, the app aborts at startup with "Could not load the Qt platform plugin xcb".

These mirror system_requires / system_runtime_requires in pyproject.toml ([tool.briefcase.app.wireworks.linux.system]); keep the two lists in sync. On non-Debian distributions the package names differ — see your distro's equivalents.

Running from source

With the environment active and the package installed in editable mode, the wireworks console script is on PATH:

wireworks

Equivalently, python -m ars_wireworks runs the same entry point.

Or, from inside the wireworks directory, use the launcher script — it uses the project's virtual environment without your having to activate it. Run ./run.sh on Linux and macOS, or run.bat on Windows.

On Linux, ./install-desktop.sh adds ARS WireWorks to your application menu — a desktop entry pointing at this checkout. ./uninstall-desktop.sh removes it again.

Running the tests

pytest

The Qt tests run headless: tests/conftest.py sets QT_QPA_PLATFORM=offscreen so the suite needs no display. To watch a particular test in a real window, override it — QT_QPA_PLATFORM=xcb pytest -k <name> on Linux (cocoa on macOS, windows on Windows).

Project layout

Source lives under src/ars_wireworks/, organized into the strict architectural layers from spec §10. Each layer may depend only on the layers above it.

Package Layer Responsibility
model (a) Input model dataclasses
cards (b) NEC card-deck generator
solver (c) Solver interface and NecppSolver
results (d) Results dataclasses, plotting, export, build sheets
teaching (e) Lessons, glossary, materials reference data
ui (f) PySide6 user interface

Coding guidelines

Filesystem hygiene (spec §11):

  • Use pathlib.Path for all paths; never concatenate path separators.
  • Use platformdirs for all user data, cache, and config locations.
  • No hardcoded OS-specific paths.
  • All repository text files are LF (enforced by .gitattributes).

Contributing content

Two style guides cover the non-code contributions (spec §14.13) — read the relevant one before editing:

  • docs/teaching-style-guide.md — lessons, the glossary, info-icon text, engine-choice notes, and validation messages.
  • docs/buildsheet-style-guide.md — the build-sheet templates and the reportlab renderer.