HOW TO BUILD ChromIQ

====================

These steps produce a self-contained ChromIQ bundle for your platform:

- macOS → dist/ChromIQ.app (Steps 1-6 below)

- Linux → dist/ChromIQ/ChromIQ (see "Building on Linux (beta)" below)

- Windows → dist/ChromIQ/ChromIQ.exe (similar to Linux; uses ChromIQWin.spec)

Steps 1-3 are cross-platform. Steps 4, 4b, 5, and 6 below are macOS-specific

(they build with ChromIQ.spec, re-sign the .app bundle, and zip a .app).

Linux users should follow Steps 1-3, then jump to the Linux section.

Prerequisites (macOS)

---------------------

- macOS (Apple Silicon or Intel)

- Python 3.11 – 3.14 (python3 from Homebrew or python.org)

- Git (to clone the repo)

- The ChromIQ source code (git clone …)

- No Xcode required

Step 1 — Create and activate a virtual environment

---------------------------------------------------

Open Terminal and navigate to the ChromIQ project folder.

cd /path/to/ChromIQ

python3 -m venv .venv

source .venv/bin/activate

You should now see (.venv) at the start of your prompt.

Step 2 — Install dependencies

------------------------------

pip install -r requirements.txt

This installs PyQt6, Pillow, PyYAML, and PyInstaller inside the venv.

IMPORTANT: Always use python -m PyInstaller (not the bare pyinstaller

command) so that PyInstaller uses the same Python environment where the

packages are installed.

Step 3 — Generate the app icons (only needed once, or after the icon changes)

------------------------------------------------------------------------------

ChromIQ.spec expects assets/app_icon.icns (macOS) and ChromIQWin.spec

expects assets/app_icon.ico (Windows). Both are derived from the source

PNG assets/app_icon.png by one cross-platform script:

python scripts/build_icons.py

This uses Pillow (already installed by Step 2) and works on macOS, Linux,

and Windows alike — no sips / iconutil / ImageMagick / icnsutil needed.

Step 4 — Build the app (macOS)

--------------------------------

python -m PyInstaller ChromIQ.spec

PyInstaller prints progress to the terminal. The build takes about 15-30

seconds on Apple Silicon and a bit longer on Intel.

The finished app is at:

dist/ChromIQ.app

Step 4b — Re-sign the bundle (macOS, required for distribution)

-----------------------------------------------------------------

After building, run a deep ad-hoc re-sign so macOS correctly resolves the

bundle when the app is downloaded from the internet:

codesign --deep --force --sign - dist/ChromIQ.app

Without this step the app works when run from the project folder but crashes

on launch after being downloaded (macOS enforces stricter bundle integrity

checks on quarantined apps, and PyInstaller's per-binary signatures need to

be unified into one consistent ad-hoc signature across the whole bundle).

Step 5 — Test the app (macOS)

-------------------------------

Double-click dist/ChromIQ.app in Finder, or run from Terminal:

open dist/ChromIQ.app

If macOS says "unidentified developer", right-click the app → Open → Open.

This only needs to be done once per Mac.

Step 6 — Distribute the app (macOS)

-------------------------------------

You can zip the app for sharing:

cd dist

zip -r ChromIQ.zip ChromIQ.app

Or drag ChromIQ.app straight into a DMG with Disk Utility → New Image from Folder.

Rebuilding after code changes

------------------------------

Just repeat Step 4. PyInstaller detects what changed and only rebuilds the

affected parts (incremental rebuild).

To force a completely clean rebuild from scratch (e.g. after adding new asset

files or changing the spec):

rm -rf build dist

python -m PyInstaller ChromIQ.spec

Building on Linux (beta)

-------------------------

The same source tree builds on Debian/Ubuntu and other glibc Linux distros.

Prerequisites (Debian/Ubuntu):

sudo apt install python3-venv libcups2-dev libegl1 \

libxkbcommon-x11-0 libxkbcommon-x11-dev libdbus-1-3 \

libxcb-cursor0 libxcb-icccm4 libxcb-image0 \

libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \

libxcb-shape0 libxcb-xkb1 libfontconfig1 libxrender1

These libraries serve double duty: they let the resulting binary launch

on the build host AND ChromIQLinux.spec bundles a copy of each into the

output tarball so end users do not need to install them separately.

Then from the repo root:

python3 -m venv .venv

source .venv/bin/activate

pip install -r requirements.txt

python scripts/build_icons.py # optional — Linux uses the PNG

python -m PyInstaller ChromIQLinux.spec

Run with:

dist/ChromIQ/ChromIQ

Package for distribution:

tar -C dist -czf ChromIQ-Linux-x86_64.tar.gz ChromIQ

Argyll on Linux: install via your package manager

(`sudo apt install argyll`) or download from

https://www.argyllcms.com/downloadlinux.html. ChromIQ defaults to

/usr/bin and also probes /usr/local/bin, /opt/argyll/bin,

/opt/argyllcms/bin and ~/.local/bin — set the path explicitly in

Preferences if your install lives elsewhere.

Troubleshooting "qt.qpa.plugin: ... xcb-cursor0 ... is needed"

--------------------------------------------------------------

Qt 6.5+ depends on libxcb-cursor.so.0 to load the xcb platform plugin.

The Linux tarball produced from ChromIQLinux.spec bundles a copy of

this library (and the other xcb helpers Qt needs) so on most distros

the binary "just works". If you still hit the error on a minimal

system, install the system package as a fallback:

Debian/Ubuntu: sudo apt install libxcb-cursor0

Fedora/RHEL: sudo dnf install xcb-util-cursor

Arch: sudo pacman -S xcb-util-cursor

Notes

-----

- The build is architecture-specific: an Apple Silicon Mac produces an arm64

bundle; an Intel Mac produces an x86_64 bundle. To produce a universal

binary (runs on both), both architectures need to be available in the same

Python installation — this is complex and not necessary for most use cases.

- dist/ChromIQ.app is about 89 MB. This is normal — it bundles Python, PyQt6,

and all dependencies so recipients need nothing else installed.

- The build/ folder is an intermediate cache used by PyInstaller. It is

safe to delete but speeds up subsequent builds if kept.

- hooks/hook-workflow.py is an empty file that overrides a conflicting

PyInstaller hook from _pyinstaller_hooks_contrib. Do not delete it.