Development #
Requirements #
Bun 1.4+, Rust 1.95+ (edition 2024) and, on Windows, VS 2022 Build Tools with MSVC 14.42. On Windows, all native commands go through tools/msvc.ts, which loads the MSVC environment, hides child consoles and removes PATH entries that shadow link.exe and cmd.exe.
A fresh clone builds with the tracked assets; the game install is only needed to refresh them (docs/game-assets.md).
Build, run, test #
bun install
bun test :: TypeScript helper tests (tests/)
bun run typecheck :: tsc --noEmit
bun tools/msvc.ts cargo test :: Rust tests (crates/*/src and crates/*/tests)
bun tools/msvc.ts cargo clippy --all-targets -- -D warnings
bun tools/msvc.ts cargo fmt --check
bun tools/msvc.ts cargo build --release :: target/release/fmm.exe
On Linux and macOS, use plain Cargo (no MSVC wrapper):
bun install --frozen-lockfile
bun test
bun run typecheck
cargo fmt --all --check
cargo test --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo build --release # target/release/fmm
Linux uses the bundled fonts/resources, winit and FemtoVG (Wayland or X11). Build prerequisites include a C linker, pkgconf, fontconfig, X11/XCB, xkbcommon, Wayland and EGL development libraries, plus ALSA headers/pkg-config for Rodio playback (alsa-lib runtime). xdg-utils supplies xdg-open. The Windows wrapper and Win32 implementations are unchanged.
macOS needs the Xcode command-line tools and rustup's stable toolchain; winit, FemtoVG (OpenGL) and CoreAudio need no extra packages. cargo build --release produces a plain target/release/fmm binary, not a .app bundle.
fmm.exe is a standalone Windows GUI executable with fonts, game pieces and icons embedded. Copy it anywhere. It needs a Factorio data folder to manage mods; an install is optional and supplies builtin mods and the game version. Debug builds keep a console window; release builds don't.
Rust tests inject network and filesystem effects and use temporary directories. Portal parser tests replay saved responses from crates/core/tests/fixtures/ (inventory in its README.md) and never touch the network.
The additional cargo test --workspace --all-features check currently fails five ordinary portal success fixtures because broken-portal deliberately corrupts metadata responses. Those tests and the feature are unchanged by M7; run the dedicated recovery test with cargo test -p fmm_core --features broken-portal --test broken_portal. Default workspace tests and all-features Clippy are the normal acceptance gates.
The broken-portal feature #
cargo build --features broken-portal (on fmm) makes fmm_core corrupt portal metadata before parsing, so the HTML-to-catalogue fallback paths can be exercised. Images, archives, local data and stored records are unaffected. crates/core/tests/broken_portal.rs covers it.
Environment overrides #
| Variable | Effect |
|---|---|
FACTORIO_DIR |
Game install path; beats the saved setting |
FMM_SETTINGS_DIR, FMM_METADATA_DIR, FMM_CACHE_DIR |
Move settings, installed-mod metadata and cache independently |
MSVC_VCVARS |
Path of vcvars64.bat for tools/msvc.ts |
SLINT_VIEWER |
Software-only slint-viewer for the widget bench |
BENCH_CHROME |
Chrome path for the portal CSS reference renderer |
Point the three FMM_* variables at separate temporary folders whenever you run the app headlessly or in tests.
Headless captures #
fmm.exe --screenshot out.png --size WxH renders the app with an in-process software renderer and never shows a window or binds live install, remove, save or browser effects.
target\release\fmm.exe --screenshot out/screenshots/manage.png --fixture crates/app/tests/fixtures/r2b.json --size 1440x945
--fixture supplies a snapshot (rows, details, optional downloads placeholder rows) instead of scanning real mods. Most state flags need both --screenshot and --fixture; portal replay needs --screenshot. The accepted flags are listed in parse_args in crates/app/src/main.rs. They cover tab and view mode (--tab, --view table|rows|grid), selection, search and sort, pending toggles, download progress, confirmation and removal dialogs, Settings and onboarding, pointer and wheel input (--pointer x,y, --pointer-press 1, --wheel), the detail gallery and lightbox, and portal replay (--portal-html, --portal-full, --portal-updates, --catalogue, --explore-page). Read the PNG afterwards and compare it with docs/reference/.
The replay scripts below build their fixtures in an OS temporary folder, call target/release/fmm.exe and write images and logs to out/<name>/. Some compare against an earlier executable placed in their output folder; each script says which. Run cargo build --release first.
| Script | Captures |
|---|---|
tools/capture-m1.ts <temp-cache> [out] |
Portal search, browse, filters, loading, fallback and Updates from saved responses. --r4c <probe-cache> adds full details, gallery and descriptions; --r5 <probe-cache> adds inline formatting, gallery scrollbar, lightbox and the Updates header. |
tools/capture-m2b.ts |
Install and update action states, confirmation, removal and the result banner. |
tools/capture-m3.ts |
Independent toggles, missing dependencies, Install missing, incompatibilities, version pins and local zip and folder changelogs. |
tools/capture-m4.ts |
Settings, recovery messages and packaging checks (GUI subsystem, embedded icons). Temporarily renames assets/game; don't run it beside builds or extraction. |
tools/capture-m6.ts |
Table, Rows and Grid at narrow, wide and scrolled sizes, and Settings. |
tools/capture-r6.ts |
Compact actions, gallery input and descriptions. |
tools/capture-r7.ts |
Several progress rows, Explore states and gallery pointer input. |
tools/capture-r8.ts [--broken] |
Fixed detail panes, selectors, links and dependency focus, Settings and onboarding, window chrome, and the parser-failure fallback (--broken needs a broken-portal build saved as out/r8/fmm-broken.exe beside the normal one as fmm-default.exe). |
tools/capture-m8.ts |
Inline description images at 1000×600 and 1600×1000, two selected GIF frames, mixed PNG/JPEG/WebP/failure/linked badge and loading placeholders. Generates raster fixtures in an OS temporary directory and replays them through the fake transport, with no live network. |
tools/capture-r9.ts |
Queued/running/failed rows; controller-projected pending toggles, unlisted installs, selected pending and normal rows in Table/Rows/Grid at normal/minimum size; links, title/window controls, dependency tools, Show in Manage, save-only visible/hidden, hovered lightbox close and sound Settings. |
crates/core/examples/m1_capture_data.rs prepares the saved portal responses for capture-m1.ts from a probe folder. It makes allow-listed live requests, so run it only into a temporary FMM_CACHE_DIR. tools/make-catalogue-fixture.ts writes deterministic synthetic bulk catalogues without touching the network.
M8 adds capture-only --description-images <json> (URL-to-local-fixture-path map), --description-frame <index> (selects a deterministic animation frame), and --description-loading 1 (leaves placeholders). They require both --screenshot and --fixture. No live description transport is bound in captures; missing fixture responses fail. crates/core/examples/m8_images.rs generates the image bytes used by capture-m8.ts.
Pixel tools and the fidelity bench #
bun tools/crop.ts in.png x y w h out.png 4 :: zoomed crop (or --hex to print pixels)
bun tools/bench/compare.ts a.png b.png diff.png :: diff two same-size PNGs
bun tools/bench-slint.ts [id-or-prefix] --quiet :: widget states vs game crops
bun bench/slint/grid.ts in.png x y w h zoom out.png :: crop with a coordinate grid
bun bench/slint/ink.ts in.png x y w h #bg :: ink bounding box
bun bench/slint/runs.ts in.png row|col fixed from to :: colour runs along a line
bun bench/slint/diffpx.ts truth.png x y w h shot.png :: list differing pixels
-
tools/bench/png.tsis the PNG codec;diff.tshas the metrics and the PASS / NEAR / FAIL tiers plus text-ink scoring;refs.tsresolves crops frombench/refs.json(125% screenshots) andbench/slint/refs-100.json(100%). Crop names there refer todocs/reference/images. -
tools/bench/browser.tsrenders the extracted portal CSS in headless Chrome (device scale 1) as truth for portal-only widgets. Game screenshots stay authoritative for game widgets. -
tools/bench-slint.tsrenders each state inbench/slint/fixtures/*.slintthroughtools/shot.tsand the softwareslint-viewer, scores it against the crops, and writesout/bench-slint/report.mdwith side-by-side images. -
Build the viewer from a Slint 1.18.1 source checkout and point
SLINT_VIEWERat it:bun tools/msvc.ts --cwd <slint-source> cargo build --release -p slint-viewer --no-default-features --features renderer-softwareNever pass
--backendto the viewer; that bypasses its windowless platform and can open a window. A viewer built with Skia renders text with a different weight. Declare injected properties on the exported fixture component, since viewer data loading doesn't set inherited properties reliably.
Packaging #
The release build is the package: target/release/fmm.exe carries the window and executable icon (assets/game/factorio.ico, compiled in by crates/app/build.rs), the three Titillium fonts and every piece image. build.rs fails with a pointer to bun tools/setup-assets.ts if the tracked piece index or icons are missing. Linux uses no-replace kernel moves and home/per-volume freedesktop desktop Trash with the EXDEV copy/delete fallback disabled. macOS uses renameatx_np(RENAME_EXCL) moves and the NSFileManager Trash. Other targets refuse effects.
Release packages and GitLab releases #
Releases are started from the owner's macOS machine. Only the DMG builds locally; Linux and Windows build in containers on a LAN host over SSH, because this machine can't run a VM and Homebrew has no prebuilt LLVM for it.
The GitHub mirror also builds release packages when it receives a tag such as v0.2.1. Update the workspace version and release notes in the commit you want to ship, then create and push an annotated tag pointing to that commit. The workflow checks that the tag matches the workspace version. Ordinary branch pushes skip release CI. When all packages succeed, GitHub creates a draft release using the checked-in notes. Review the draft before publishing.
CI uses bun tools/package.ts macos --headless to create the universal DMG without Finder or Quick Look. For Linux and Windows, FMM_LOCAL_BUILD=1 runs the existing Podman builds on the Linux runner.
bun tools/package.ts all # or: macos | windows | linux; --dirty allows uncommitted changes
GITLAB_TOKEN=... bun tools/release.ts --push
tools/package.ts writes out/release/<version>/ from the workspace version, and every platform builds the same tracked and non-ignored working-tree files:
- macOS:
FactorioModManager-<v>-macos-universal.dmg. x86_64 and arm64 builds (deployment target 11.0) are joined withlipointoFactorio Mod Manager.app(assets/game/factorio.icns,com.werry.factoriomodmanager) and ad-hoc signed. The bundle'sCredits.htmlandNSHumanReadableCopyrightfill the standard About panel (author and repository links); the build number is the commit count. The DMG uses Steam's DMG geometry (660×470 window, 108 px icons at (155, 230) and (495, 230)), with an Applications link and a 1×/2× background rendered by Quick Look frompackaging/macos/dmg-background.html; Finder lays it out through AppleScript, so the first run asks to let the terminal control Finder. Eject any mountedFactorio Mod Managervolume first. - Windows:
FactorioModManager-<v>-windows-x86_64.exe, cross-compiled forx86_64-pc-windows-msvcon the same build host, frompackaging/windows/Containerfile: Ubuntu 24.04, apt's LLVM 18 (clang-cl, lld-link, llvm-lib, llvm-rc) and cargo-xwin 0.23.1. cargo-xwin downloads the MSVC CRT and Windows SDK under Microsoft's license into thefmm-xwinvolume. Its target dir is the separatefmm-target-windowsvolume. - Linux:
FactorioModManager-<v>-linux-x86_64.AppImageandFactorioModManager-<v>-arch-x86_64.pkg.tar.zst, both from one binary. The tree is copied over SSH toFMM_LINUX_HOST(defaultasabove), into~/fmm-build, and built with rootless podman frompackaging/linux/Containerfile(Ubuntu 22.04, glibc 2.35, pinned Rust). Named volumesfmm-cargoandfmm-targetcache downloads and builds. The AppImage uses appimagetool 1.9.1 and type2-runtime 20251108, pinned by SHA-256 in that file, and bundles no system libraries.makepkg --nodepsthen runspackaging/arch-bin/PKGBUILD(factoriomodmanager-bin, which provides and conflicts withfactoriomodmanager) in anarchlinux:base-develcontainer with--userns=keep-id.
tools/release.ts reads the project from the origin remote. It uploads each file to the generic package registry (factoriomodmanager/<version>/) and creates the release for v<version>, with links at /-/releases/<tag>/downloads/<file> and per-platform install notes (or --notes <file>). --push refuses a dirty tree, creates the annotated tag at HEAD when missing, and pushes the current branch and tag. Without it, the tag must already be on origin. Rerunning adds only missing links. The token needs the api scope.
Repository tooling map #
| Path | Purpose |
|---|---|
tools/msvc.ts |
Native build wrapper |
tools/setup-assets.ts, extract-assets.ts, dump-styles.ts, pieces.ts, style-slices.ts, fetch-portal-css.ts |
Asset refresh; see docs/game-assets.md |
tools/bench/, tools/bench-slint.ts, tools/shot.ts, tools/crop.ts |
Pixel comparison and cropping |
bench/slint/gen-pieces.ts, make-icons.ts |
Generate src/view/widgets/pieces.slint and the 100% icons |
src/core/ + tests/ |
gameStyle.ts (style inheritance and layer resolver) and paths.ts (install lookup) with their tests |
Linux fixture captures and safe launch #
m7_tmp=$(mktemp -d -t fmm-m7.XXXXXXXX)
FMM_SETTINGS_DIR="$m7_tmp/settings" FMM_CACHE_DIR="$m7_tmp/cache" \
FMM_METADATA_DIR="$m7_tmp/metadata" target/release/fmm \
--screenshot "$m7_tmp/manage.png" --fixture crates/app/tests/fixtures/r2b.json --size 1440x945
cargo test -p fmm_core --test linux real_install_read_only_probe -- --ignored --nocapture
The ignored probe only reads discovery/config/version/list data and writes no cache. It never reads player-data.json. Ordinary startup cleans stale download parts, so never launch effects-enabled against real mods for a discovery check. For a native launch, first create a temporary data/mods/mod-list.json and temporary settings/settings.json with its absolute dataDir, then use all three temporary FMM roots. Keep real install discovery separate. Owner acceptance targets KDE Plasma Wayland at the owner's normal scale; X11 and mixed-DPI/multi-scale matrices remain UNKNOWN/untested.
Linux backend fixtures run with injected paths; desktop Trash fixtures use isolated child HOME/XDG environments without changing the test process environment. To exercise cross-device backup-move refusal, set FMM_TEST_SECOND_TEMP to an existing isolated OS temporary directory on a different device from std::env::temp_dir(); the test checks device IDs before effects. Never point it at an existing user-data directory.
macOS fixture captures and probe #
The Linux capture command above works unchanged on macOS (use mktemp -d -t fmm-mac). The read-only probe is cargo test -p fmm_core --test macos real_install_read_only_probe -- --ignored --nocapture. NSFileManager ignores HOME, so no automated test trashes anything; the macOS tests cover Trash refusals only and leave real Trash moves to the owner checklist.
Personal Arch package (no installation) #
packaging/arch/PKGBUILD builds local version 0.1.0; no repository URL or owner's home path is embedded. Prepare its checksummed source from the committed runtime tree in an isolated directory:
package_tmp=$(mktemp -d -t fmm-package.XXXXXXXX)
cp packaging/arch/PKGBUILD packaging/arch/factoriomodmanager.desktop "$package_tmp/"
git archive --format=tar 47fa962c0a2366534e7a098306d2727f36282c64 Cargo.toml Cargo.lock crates src assets vendor/trash > "$package_tmp/factoriomodmanager-0.1.0.tar"
# Its sha256sum must match PKGBUILD; deliberately update the checksum after runtime changes.
(cd "$package_tmp" && makepkg --nodeps --cleanbuild)
bsdtar -tf "$package_tmp/factoriomodmanager-0.1.0-2-x86_64.pkg.tar.zst"
ldd target/release/fmm
The package disables makepkg C/C++ LTO: GCC LTO objects from ring cannot be consumed by Rust's default LLVM lld linker on this setup. Cargo retains its normal release optimization. The source archive is pinned by SHA-256 and runtime commit 47fa962c0a2366534e7a098306d2727f36282c64 (_source_commit in PKGBUILD). Use that revision rather than HEAD: git archive includes the commit identity even when later commits only change documentation or packaging. Only build inputs are archived; the desktop entry and icon use the tracked assets. The package stages /usr/bin/fmm, the desktop entry, and the 64x64 hicolor icon. It declares linked system libraries and dynamically loaded X11/Wayland/EGL support plus xdg-utils and alsa-lib for the linked audio backend. This is a personal local build, not an AUR release. AppImage and Flatpak packaging are deferred. Do not use makepkg -i, pacman -U, sudo or install dependencies for agent acceptance. Extract to a temporary directory and run a fixture screenshot from there to verify resources independently of the checkout.
The vendored Trash fallback regression calls only its internal move helper between
isolated temporary directories, never the desktop Trash selector. Run it with an
isolated second-filesystem FMM_TEST_SECOND_TEMP using
cargo test --manifest-path vendor/trash/Cargo.toml --lib fmm_tests::cross_device_copy_refused.
The patch and upstream MIT license are retained under vendor/trash/.
UI audio tests are device-free: cargo test -p fmm audio::tests exercises embedded
decoding, injected unavailable/disconnected/stalled outputs, voice bounds, gain,
mute, stale/full queues and bounded retry. ui_audio_real_controls records
semantic widget events without a real sink. Headless --screenshot never starts
audio. Settings fixtures can use temporary settings JSON with uiSoundsEnabled
and uiSoundVolume for enabled, disabled and zero-volume captures. Never point
fixture settings at real mod data. UI changes apply immediately; only folder
changes require restart.