Creating the Tools for Production Builds

Ascendara's helper tools are bundled into standalone executables so users don't need Python, Node.js, or any dependencies installed. The Downloader, Game Handler, and Crash Reporter are written in Rust and built with Cargo, the Python tools are built with PyInstaller (6.16.0), and the Achievement Watcher is built with pkg.

Each platform has a build script that builds the tools for you. You normally don't need to run PyInstaller yourself.

Which Tools Each Platform Ships

On-demand tools ("sidecars") are downloaded from cdn.ascendara.app the first time a feature needs them. See System Design.

Windows

python scripts/build_windows_helpers.py

Run this on a native Windows x64 machine with Cargo, Yarn, and 7-Zip x64 installed in C:\Program Files\7-Zip. The script:

1. Creates a virtual environment in .build_venv and installs PyInstaller and the requirements of the Notification Helper and Torrent Handler.
2. Builds those two Python tools as single windowed executables (so Windows doesn't open a console window when Ascendara starts them):
   bashCopy

   python -m PyInstaller --onefile --noconfirm --clean --windowed \
     --name AscendaraTorrentHandler \
     --icon binaries/AscendaraTorrentHandler/src/ascendara.ico \
     --distpath binaries/AscendaraTorrentHandler/dist \
     --add-data "binaries/AscendaraTorrentHandler/src/ascendara.ico;." \
     --add-binary "C:\Program Files\7-Zip\7z.exe;." \
     --add-binary "C:\Program Files\7-Zip\7z.dll;." \
     --add-data "C:\Program Files\7-Zip\License.txt;licenses/7zip" \
     binaries/AscendaraTorrentHandler/src/AscendaraTorrentHandler.py

   The Torrent Handler bundles 7-Zip and its license. The Notification Helper bundles its sounds folder and adds --hidden-import PyQt6.QtMultimedia so it can play notification sounds.
3. Builds the Rust tools: cargo build --release --locked in binaries/AscendaraCrashReporter, binaries/AscendaraGameHandler, and binaries/AscendaraDownloader. The Downloader extracts archives itself, so it needs no bundled 7-Zip or UnRAR.
4. Builds the Achievement Watcher: yarn install --frozen-lockfile and yarn build-win in binaries/AscendaraAchievementWatcher.
5. Checks that every resource listed in package.json exists and is a Windows x64 executable.

The outputs are placed where package.json expects them:

Linux

yarn dist-linux builds the tools as part of the app build:

• Creates .build_venv, installs PyInstaller and every tool's requirements, and builds Language Translation, the Torrent Handler, and the Notification Helper as single-file executables.
• Bundles the system unrar and p7zip's 7z and 7z.so (with their license notices) into the Torrent Handler. The script uses Debian/Ubuntu paths; other distributions may need adjustments.
• Builds the Downloader, Crash Reporter, and Game Handler with Cargo and the Achievement Watcher with yarn build-linux.

macOS

yarn dist-mac builds the tools for each target architecture in its own virtual environment (.build_venv_mac/<arch>), builds the Downloader, Game Handler, and Crash Reporter with an explicit Rust target, and bundles the official macOS 7zz (downloaded by yarn setup-mac) into the Torrent Handler. Apple Silicon builds also build the pinned Highball CLI (yarn setup-highball, or scripts/build_highball.py) and bundle it in Contents/Resources/Highball with its engine manifest, compatibility data, and license notices. Intel builds don't include Highball and use the system Wine. See README_MAC_BUILD.md in the repository.

Achievement Watcher

Note: This tool is written in JavaScript, not Python. It's packaged with pkg 5.8 using a Node 18 runtime.

cd binaries/AscendaraAchievementWatcher
yarn install --frozen-lockfile
yarn build-win     # or build-linux / build-mac

The output is dist/AscendaraAchievementWatcher(.exe).

Downloader, Game Handler, and Crash Reporter

Note: These tools are written in Rust and need Rust 1.90 or newer. The Crash Reporter uses the FLTK GUI toolkit.

cd binaries/AscendaraDownloader   # or AscendaraGameHandler / AscendaraCrashReporter
cargo build --release --locked

The output is target/release/<Tool>(.exe). On Windows, build.rs embeds the icon into the executable.

Building a Single Tool Manually

To build one Python tool by hand, install its requirements and run PyInstaller from the project root:

pip install -r binaries/AscendaraNotificationHelper/requirements.txt pyinstaller==6.16.0
python -m PyInstaller --onefile --noconfirm --clean --windowed \
  --name AscendaraNotificationHelper \
  --icon binaries/AscendaraNotificationHelper/src/ascendara.ico \
  --distpath binaries/AscendaraNotificationHelper/dist \
  --add-data "binaries/AscendaraNotificationHelper/src/sounds;sounds" \
  --hidden-import PyQt6.QtMultimedia \
  binaries/AscendaraNotificationHelper/src/AscendaraNotificationHelper.py

On Linux and macOS, use : instead of ; to separate the source and destination in --add-data and --add-binary.

Command Options Explained

• --onefile: Bundles everything into a single executable
• --windowed: Builds a GUI-subsystem executable, so no console window opens when Ascendara starts the tool
• --icon: Sets the executable's icon
• --add-binary: Includes native binaries such as 7z.exe
• --add-data: Includes data files such as the icon and license notices
• --hidden-import: Includes modules PyInstaller can't detect automatically
• --distpath: Where the executable is written

Running Tools From Source

In development mode, Ascendara starts the Python tools from binaries/<Tool>/dist/ and the Rust tools from binaries/<Tool>/target/release/, so build the tools you're testing. You can also run a tool directly, for example:

cd binaries/AscendaraDownloader
cargo run --release -- "https://example.com/game.zip" "Example Game" false false false false "1.0" "1 GB" ./games