- TypeScript 73.3%
- Nix 15.1%
- Python 6%
- Shell 2.4%
- C++ 2.3%
- Other 0.7%
Was efbdc866fcddc9bff23da00b1722d17e52115567, now 3434abb448b6e671ebad8b042a607a5772c7ac58. Upstream tags no releases, so this is a deliberate snapshot of master rather than something a schedule chose. |
||
|---|---|---|
| .dev | ||
| .forgejo/workflows | ||
| deploy/k8s | ||
| hosts | ||
| installer | ||
| mame-sync | ||
| modules | ||
| pkgs | ||
| vm | ||
| windows | ||
| .gitignore | ||
| flake.lock | ||
| flake.nix | ||
| R2-MIRROR.md | ||
| README.md | ||
| shot.png | ||
arcade-nix
NixOS packages for the arcade cabinet.
| Package | What it is |
|---|---|
mame-no-nag |
nixpkgs' MAME with the startup emulation-warning screen patched out — a cabinet has nobody to press OK |
What is here
| Kind | Where | Example |
|---|---|---|
| Nix packages | pkgs/ |
mame-no-nag, flycast, supermodel, teknoparrot, attractplus, sinden-lightgun, mame-sync |
| NixOS modules | modules/ |
the binary cache, the ROM manager service |
| Cabinet configs | hosts/ |
charles-cab, vm |
| Vendored source | mame-sync/ |
the ROM manager application |
How an application is built stays separate from how a cabinet runs it.
The ROM manager's source is vendored at mame-sync/ and built by
pkgs/mame-sync.nix; modules/rom-manager.nix is how a cabinet runs it. A
client installs applications — it should not have to care whether one arrives
as a Nix package
or an image.
Which emulator covers which hardware
Chosen per generation, because no single emulator is best at all of them:
| Hardware | Package | Why this one |
|---|---|---|
| Arcade generally | mame-no-nag |
MAME, with the startup warning screen patched out |
| Sega Model 2 | mame-no-nag |
MAME's Model 2 drivers are good enough — Virtua Cop 1 and 2 have been working since 0.196. Model 2 Emulator has broader compatibility but is Windows-only and closed, so it is not worth the Wine dependency until a specific title disappoints |
| Sega Model 3 | supermodel |
MAME's Model 3 drivers are not playable; Supermodel is the only real option |
| NAOMI / NAOMI 2 / Atomiswave / Dreamcast | flycast |
Far ahead of MAME on this hardware, and where most of the light-gun catalogue lives |
| PC-based arcade (Sega Lindbergh, Namco, …) | teknoparrot |
JVS/IO emulator and loader. Note it loads Windows game binaries, so running them is still per-title Wine/Proton work |
| Frontend | attractplus |
Attract-Mode Plus with the MarqueeDisplay customisations |
| Light guns | sinden-lightgun |
Sinden driver. Flycast exposes a "Light Gun" device type and a Sinden enumerates as two devices, mouse and keyboard, mapped separately |
Related repos:
charles/mame-sync— upstream of the vendoredmame-sync/, and where its container image is still published for anyone running it that waycharles/mame-windows-build— MinGW cross-compile for the legacy Windows cabinet
Running the ROM manager
It is a package, so selecting mame-sync is what turns the service on — in the
installer's Applications list, or in cabinet.packages.selected. It is in
cabinet.packages.default, so a cabinet nobody has configured gets it: one
installed without the manager has no interface to change its own mind with.
Setting the service directly still works and still wins:
{
services.rom-manager = {
enable = true;
environmentFile = "/etc/rom-manager.env"; # secrets: tokens
};
}
No paths: on a cabinet they come from cabinet.storage — the collection area
as the source, the roms area as the destination — so a cabinet that later puts
either on a NAS does not have to be reconfigured here as well. romPath and
playSetPath are still there for a machine that runs the manager without being
a cabinet.
Secrets go in environmentFile, never extraEnvironment — anything set in the
Nix config lands in the world-readable store.
Adding a package
Drop a .nix file into pkgs/. That is the whole procedure.
The flake reads the directory, so a file named pkgs/foo.nix becomes
pkgs.foo in the overlay, packages.x86_64-linux.foo, and a build target in
CI. Nothing in flake.nix needs editing — which also means two people can add
packages without touching the same lines.
Each file is a normal callPackage expression. Either wrap something nixpkgs
already has:
{ someExistingPkg }:
someExistingPkg.overrideAttrs (old: { /* ... */ })
or build from scratch when nixpkgs does not carry it:
{ stdenv, fetchFromGitHub, cmake, ... }:
stdenv.mkDerivation (finalAttrs: { /* ... */ })
For an emulator, do not override a nixpkgs package. Read its recipe, copy the dependency list, and write your own derivation pinned to upstream's tag — see Versions, and how they move for why, and Adding an emulator for the procedure. Overriding is still right for something small that is not version-critical, where an override is a diff rather than a thing to maintain.
Adding an emulator
Four have gone in this way. The procedure, and the traps, in the order you meet them:
1. Find out what upstream actually ships. A native Linux build changes
everything. TeknoParrot looked like a Wine problem until its net8 branch
turned out to publish a self-contained .NET 8 Linux build — which made it an
autoPatchelfHook package like sinden-lightgun rather than a Wine wrapper.
2. Read nixpkgs' recipe as a reference, not a dependency. It knows the
dependency list, the make flags and the install phase, and that is worth
having. Check whether the patches it carries are still needed: nixpkgs seds a
#include <cstdint> into Supermodel for GCC 15, and upstream had already fixed
it — applying it would have inserted the include twice.
3. Write three files.
pkgs/<name>.nix the derivation, reading the pin
pkgs/<name>-version.json { version | rev, hash }
.forgejo/workflows/<name>-version.yml the updater
The flake, the cabinet's package list and CI all discover pkgs/ on their own,
so nothing needs registering for the package to build and publish.
4. Register it in modules/emulators.nix. This part is not discovered,
and skipping it is the failure that looks like success: the package builds,
publishes and installs, and the cabinet then shows nothing, because the
frontend was never told the emulator exists.
Add an entry to builtins', keyed by the name the romlist and display take:
naomi = {
package = "flycast"; # must match the pkgs/ filename
definition = { … }; # executable, romext, artwork, system
};
That set is what cabinet.emulators.known is derived from, and three things
read it: the frontend configuration, which writes an Attract-Mode .cfg and
a display per installed emulator; the installer, which splits its package
list into applications and emulators; and the ROM manager's configuration,
checked against it so an override naming a system nothing provides is rejected
rather than producing something unrunnable.
An emulator with a .cfg but no display is invisible — the romlist builds and
the cabinet shows nothing — which is why the module writes both together, and
why a half-registration is worse than none.
Check it landed:
nix eval --json .#nixosConfigurations.vm.config.cabinet.emulators.known
# {"mame":"mame-no-nag","model3":"supermodel","naomi":"flycast",…}
5. Build it locally before pushing. In the nixos/nix container against a
persistent store volume, with --max-jobs 1 --cores 4 — an uncapped build has
exhausted this VM's memory, and a full one has exhausted the Proxmox thin pool
underneath it. Run fstrim -av afterwards. Nix keeps no partial build state,
so every missing dependency costs a full rebuild to discover, which is exactly
why finding them locally beats finding them one CI round-trip at a time.
6. Expect dependencies nothing declares. MAME needed three rounds: turning
off the Qt debugger silently removed the OpenGL headers Qt5 had been supplying
transitively, and then the Vulkan renderer wanted Wayland, Xlib and XCB
headers at once. When a header goes missing, read what the source actually asks
for rather than fixing them one at a time — renderer_vk.h enables all three
window systems, which was visible in the source and would have taken three
rebuilds to learn by failing.
Two failure modes are invisible to readelf and will only show up at runtime:
dlopened libraries. Vulkan for Flycast, the whole windowing stack for anything using SDL. These go onLD_LIBRARY_PATHin amakeWrapperwrapper, because nothing in the build links them.- Applications that write beside their own binary. Supermodel refuses to
start without
ConfigandAssetsin$HOME; TeknoParrot saves profiles next to its executable. The store is read-only, so the wrapper seeds a writable directory on first run withcp -rn— copied, not symlinked, or the writes land back in the store.
7. Mind the CI container's missing tools. nixos/nix ships coreutils and
gnugrep but no sed and no find. A decorative sed in the publish step
threw away an hour of successful MAME compilation on every run for weeks. Do
the work in jq or shell builtins.
Use it
Add the flake as an input and apply the overlay:
{
inputs.arcade-nix.url = "git+https://git.forked.io/charles/arcade-nix";
outputs = { self, nixpkgs, arcade-nix, ... }: {
nixosConfigurations.cabinet = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
{
nixpkgs.overlays = [ arcade-nix.overlays.default ];
environment.systemPackages = [ pkgs.mame-no-nag ];
}
];
};
};
}
Or build it directly:
nix build git+https://git.forked.io/charles/arcade-nix#mame-no-nag
Where things live on a cabinet
Everything under one root, with each name saying what it holds.
/srv/arcade/
├── config/<app>/ frontend and emulator configuration. never a mount
├── collection/ the raw set, as the torrent client writes it. mame-sync's SOURCE
├── roms/<emulator>/ play set. what the frontend plays
├── media/<emulator>/ artwork, snaps, marquees, videos
├── incoming/ partial downloads, when a client runs here
└── remote/<area>/ where a share is mounted, one per area above
Every area is the same type with the same options, so any of them can be a
share — the mount lands beside the local directory, at remote/<area>, never
on top of it. Mounting over the local one would hide whatever is already there:
still on disk, invisible, which is a confusing way to lose a collection.
collection/ is a source and nothing else, and that is the one place the two
halves come apart. areas.collection.remote.playable = false by default: the
share mounts and mame-sync reads it, but the mount point stays out of
searchPaths, so it never reaches MAME's rompath. A collection is update
packs, BIOS files and non-working drivers, and a frontend pointed at it fills a
cabinet with entries that do not run. Set it true only for a share that holds
a curated set you actually want to play off the network.
One pattern, instantiated per kind of data
ROMs are the first case, not a special one. Artwork, media and anything else that grows can live on a share for the same reasons, so this is a single type used repeatedly rather than a set of one-off options:
cabinet.storage.areas.media.remote = {
enable = true;
kind = "cifs"; # or "nfs"
server = "nas.local";
share = "artwork";
credentialsFile = "/etc/arcade/nas.cred"; # cifs only; a path, never a literal
};
Every instance gets the same mount treatment — nofail,
x-systemd.automount, and RequiresMountsFor= on whatever consumes it — so
those lessons are written once instead of being re-learned per data type.
Consumers come in two kinds, and it matters which. Some take a list, and compose local and remote for free:
rompath /srv/arcade/roms/mame;/srv/arcade/roms/mame/bios
marquee_path /srv/arcade/media/mame/marquee;/srv/arcade/remote/media/mame/marquee
That composition is what areas.<name>.searchPaths returns, and the mount
point is in it whether or not a share is configured. Both consumers skip a
directory that does not exist, so an empty one costs nothing — and it means a
share mounted there later works with nothing regenerated, and that adding a NAS
does not rewrite every emulator's configuration in the cabinet's repository.
The only area left out is collection, and not because it lacks a share:
remote.playable = false keeps a raw set out of rompath deliberately.
Attract-Mode's artwork paths are lists of directories, and MAME's rompath
is a list too. These degrade well: a share that is down means fewer marquees,
not a cabinet that fails. Consumers that accept only one path need either a
choice or a union mount, and that is worth knowing before wiring one up rather
than after.
config/ is the exception, permanently. Not "remote is unimplemented" but
"remote is not permitted": a cabinet whose configuration sits behind a mount
boots to nothing the day the network is down. It stays local and is committed
to the cabinet's own repository, which is what makes it restorable onto
replacement hardware.
Each application's configuration directory is moved there and symlinked back
to where the application expects it — ~/.attract → config/attractmode,
~/.mame → config/mame, ~/.local/share/teknoparrot →
config/teknoparrot. A symlink rather than a "config directory" flag because
each of these has its own way of being told, and two of them rewrite the file
that says so; a symlink works the same for all three and the application
cannot undo it. What that buys is one directory that is the cabinet's
configuration: one thing to back up, one to restore, one place to look when a
machine behaves unlike its neighbour.
Emulators configure themselves into the frontend
Choosing MAME in the installer used to leave a cabinet with MAME on it and a
frontend that had never heard of it — the operator still had to add an
emulator and type paths in, on an arcade cabinet, with a joystick. Every one of
those paths is already known, so cabinet.emulators writes them:
~/.attract/emulators/mame.cfg with the executable, rompath, romext and
the artwork directories, all composed from the storage areas.
Entries are named for the hardware, not the emulator that runs it: naomi is
Flycast, model3 is Supermodel. That name is what the display says on the
cabinet and what the ROM directory under roms/ is called, and the hardware is
what the machine in front of you is — the emulator is an implementation detail
that could be swapped without the games changing.
Rewritten on every boot and byte-identical given the same inputs, which is what
makes it safe for config/ to be in git — the hourly backup sees a change only
when a path really moved. The executable is named through
/run/current-system/sw/bin rather than by store path for the same reason.
attract.cfg is the exception: Attract-Mode rewrites that file wholesale
whenever anyone changes a setting in its menus, so it is the operator's. A
display is seeded into it once, when there is none at all, and never touched
again.
Romlists are built, not live — attractplus --build-romlist — and rebuilt when
the emulator configuration changes rather than on every boot, because asking
MAME for its entire -listxml takes minutes.
Answering this during installation
The installer has a Storage section, alongside the ROM manager's: one question
per area — collection, play set, artwork — each either the cabinet's own disk
or an NFS share. The answers go into cabinet.json in the cabinet's repository
before the disk is partitioned, so a reinstall starts from them.
NFS or SMB. Choose SMB and it asks for the login once, then lists the
server's shares rather than making someone remember the name and type it on a
cabinet — and lets you walk into a subdirectory, so an area can point at
//nas/media/arcade/artwork rather than the top of a share holding several
things. If the listing fails (unreachable server, older protocol, hidden share)
it falls back to typing the name: being unable to browse must not mean being
unable to configure.
The password goes two places and neither is the Nix store. The cabinet gets a
0600 file at /etc/arcade/nas.cred that mount.cifs reads as root, and
cabinet.json in the cabinet's own private repository keeps it so a reinstall
restores it without anyone typing it again. The store is world-readable on the
machine, so a password written into the configuration would be readable by
anything running on the cabinet — the configuration only ever names the path.
The collection and the play set are different things
The collection is everything downloaded: base set, update packs, CHDs, BIOS, the datfile. Thousands of files, mostly never played. The play set is the curated subset the frontend shows. The ROM manager is precisely the thing that moves between them — that is what its saved selections and copy progress are.
Pointing a frontend at a collection fills it with update packs and non-working sets, so the two must not be the same directory.
Two shares, doing different jobs
They are easy to conflate and must not be:
The source share is areas.collection: the NAS, holding the set exactly as
the torrent client wrote it. mame-sync reads it. It never appears in rompath — a raw set
is update packs, non-working drivers and BIOS files, and pointing a frontend at
it fills the cabinet with things that do not run. That is what
remote.playable = false encodes, and it is the only area shipped that way.
The destination share is areas.roms: optional, and where mame-sync puts
what it selects when the play set is not local. It does appear in rompath.
rompath in both MAME and Attract-Mode is a list, so the two destinations are
not exclusive:
rompath = /srv/arcade/roms/mame;/srv/arcade/remote/roms/mame;/srv/arcade/remote/roms
The ROM manager writes the sets into the play set directory itself and keeps
BIOS and device zips in bios/ beside them — that one stays its own directory
because it makes "what did the manager install" answerable by looking, while a
roms/ inside roms/mame/ only reads like a mistake.
The last entry is the mount point itself, for the common case where a share was
picked as //nas/…/MAME/roms and is the ROM directory. That shape is MAME's
alone: its romlist is filtered against -listxml, so a file that is not a MAME
set never becomes an entry. Nothing else here has such a list, and pointing
Flycast at the same directory would put every MAME zip in the NAOMI display.
Local costs disk but plays with the network down. Remote costs nothing and is dead when the share is. Large CHDs load noticeably slower over SMB, which is where the difference is actually felt.
Configuration never lives on a mount
/srv/arcade is local. Only remote/ is ever a mount point, and config/ is
committed to the cabinet's own repository. A cabinet whose configuration is
behind a network mount boots to nothing the day the network is down, and
restoring it onto replacement hardware is what the repository is for.
Things that will bite, if this gets built carelessly
- The ROM manager must not start before the share mounts. It bind-mounts
the ROM path into podman; if the container starts first it binds the empty
directory underneath and reports an empty collection while the share is
mounted correctly the whole time.
RequiresMountsFor=on the container unit. - Network mounts need
nofailandx-systemd.automount. A cabinet whose NAS is off must still boot to the frontend. A hard mount is a machine that hangs in somebody's living room because a NAS was unplugged in another house. - Attract-Mode's romlist is generated, not live. Built while a share is up, it goes on listing those games when the share is down and they simply fail to launch — which looks broken in a way "the game is not there" does not. Put remote games in their own display, or regenerate on mount.
Installing in a virtual machine
The ISO boots UEFI or BIOS and carries drivers for the usual hypervisors, so most of this is nothing. Two exceptions are worth knowing before losing an evening to either.
Hyper-V: turn Secure Boot off
A Generation 2 VM enables Secure Boot with the "Microsoft Windows" template, which will not validate the ISO's bootloader. It fails before anything of ours runs, so there is no error message and no log — the VM simply does not start.
# Either turn it off:
Set-VMFirmware -VMName "ArcadeOS" -EnableSecureBoot Off
# ...or point it at the CA that signs Linux bootloaders:
Set-VMFirmware -VMName "ArcadeOS" -SecureBootTemplate "MicrosoftUEFICertificateAuthority"
Make sure the DVD is ahead of the disk, too:
$vm = Get-VM "ArcadeOS"
Set-VMFirmware $vm -FirstBootDevice (Get-VMDvdDrive $vm)
A Generation 1 VM avoids the question entirely — it is BIOS, and the ISO carries isolinux as well as UEFI. It is also the quickest way to confirm Secure Boot is what is wrong.
If the install succeeds and the machine then hangs on reboot
It is a missing storage driver: initrd is waiting for a root device that no loaded driver can see. Nothing prints the name of the driver it needs, which is what makes this expensive to diagnose.
modules/cabinet.nix carries the drivers for Hyper-V, QEMU, VMware and the
usual physical controllers, so a cabinet installed from this repository should
not hit it. A host file that sets boot.initrd.availableKernelModules for its
own hardware adds to that list rather than replacing it — if you find yourself
writing an exhaustive list there, the module has already done it for you.
How the patch works
pkgs/mame-no-nag.nix overrides nixpkgs' mame with a postPatch that flips
one line in src/frontend/mame/ui/ui.cpp:
bool show_warnings = true; -> bool show_warnings = false;
It uses substituteInPlace --replace-fail, which errors when the string is
not found. When MAME eventually refactors that line the build fails loudly
rather than quietly producing a binary that still nags. Treat such a failure as
"go re-derive the patch", not "go delete the assertion".
--replace-fail needs a reasonably recent nixpkgs. On an older one it does not
exist and --replace is the fallback — but --replace does not fail on a
miss, which is the whole point, so prefer bumping nixpkgs.
Versions, and how they move
Every emulator here pins its own upstream version. None inherit nixpkgs'.
That was not the original design, and why it changed is worth keeping: nixpkgs carried MAME 0.287 while mamedev had tagged 0.289, and a cabinet's ROM sets follow the newest release. An emulator two versions behind its ROM sets is not useful. Treat nixpkgs as a source of build recipes, not of versions — borrow the dependency list, own the tag.
The pin lives in a JSON file beside the package. Data rather than Nix, so a bot rewrites it without parsing a language:
pkgs/mame-no-nag.nix pkgs/mame-version.json { version, hash }
pkgs/flycast.nix pkgs/flycast-version.json { version, hash }
pkgs/teknoparrot.nix pkgs/teknoparrot-version.json { version, tag, hash }
pkgs/supermodel.nix pkgs/supermodel-version.json { rev, date, hash }
A .json in pkgs/ is invisible to everything that enumerates packages — the
flake, modules/packages.nix and CI's discover job all filter for .nix — so
it can sit next to the package it belongs to.
The updater workflows
One per emulator in .forgejo/workflows/, all the same shape: ask upstream what
the newest version is, stop if it is not newer, otherwise prefetch the hash,
rewrite the JSON, prove the pin still evaluates, commit, push, and dispatch
a build of that one package. They differ only in what "newest" means, and that
difference is forced by upstream:
| Workflow | Follows | Schedule |
|---|---|---|
mame-version |
mamedev/mame tags (mame0289) |
daily |
flycast-version |
flyinghead/flycast tags (v2.6), release candidates filtered out |
daily |
teknoparrot-version |
the version inside the asset filename — the net8 tag is rolling and its assets are replaced in place |
daily |
supermodel-version |
master, because upstream tags nothing |
none — dispatch only |
Supermodel is deliberately the odd one. With no tags there is no signal that anyone considered a given commit fit to ship, so a schedule would roll a cabinet onto whatever landed overnight. It is a button instead.
All of them compare with sort -V and refuse to move backwards, so a retagged
or withdrawn release cannot drag a cabinet onto an older build.
Why build from source rather than ship a binary
The MAME tracker builds a Windows mame.exe in CI and pushes it to the current
cabinet over SMB. It briefly built a Linux binary too, which was dropped: a
Debian-linked binary has no place in a NixOS closure, and nixpkgs already
handles SDL, Qt and the system libraries properly. Building from source is both
more correct here and less to maintain.
The cost is that this is a modified derivation, so cache.nixos.org will never
have it and the cabinet compiles MAME itself — roughly an hour. If that becomes
annoying, the answer is a binary cache (attic or cachix) populated by CI, not a
prebuilt binary checked into a repo.
Prebuilt applications
A patched package is a different derivation from the one nixpkgs ships, so
cache.nixos.org never has it and a client would compile MAME itself —
roughly an hour. CI publishes prebuilt applications so clients install rather
than build.
One cache per application, and the client picks. CI builds each package in
pkgs/ as its own independent job and publishes its own release
(nix-cache-<package>). A machine that only runs MAME fetches only MAME's
cache; nothing pushes a whole system closure onto a client that did not ask
for one.
Independence is the point:
- One package failing to build does not stop the others being published.
- A package with no published cache is simply skipped by the client sync; the rest still install prebuilt.
- Cabinet system closures are deliberately not built or cached. Clients select applications; they build their own systems.
Forgejo cannot serve as a Nix substituter directly — a cache is files at nested
paths (nar/<hash>.nar.xz), which release assets cannot express. So each cache
ships as one asset and the client unpacks it to a local directory and
substitutes from there. Transparent at nixos-rebuild time, no server to run,
only HTTPS to Forgejo.
One-time setup
Already done. The signing-key workflow generated the key, wrote the
private half straight into the NIX_SIGNING_KEY repo secret over the API (it
is never printed or committed), and published the public half as a release
asset:
arcade-nix:uJIgpmwmGwRFbZyc5TEdVBg52IVVuwyY1CypgsowCDY=
It is also downloadable from the cache-key release. Re-run that workflow only
to rotate the key — every client's publicKey must then be updated, and caches
signed with the old key stop being accepted.
Run packages to build and publish the applications.
On a client
{
imports = [ arcade-nix.nixosModules.binary-cache ];
services.arcade-nix-cache = {
enable = true;
packages = [ "mame-no-nag" ]; # only what this machine installs
publicKey = "arcade-nix:uJIgpmwmGwRFbZyc5TEdVBg52IVVuwyY1CypgsowCDY=";
# tokenFile = "/etc/arcade-nix-token"; # only while the repo is private
};
nixpkgs.overlays = [ arcade-nix.overlays.default ];
environment.systemPackages = [ pkgs.mame-no-nag ];
}
A timer refreshes daily. A failed sync is deliberately non-fatal: a stale cache means a slow build, never a broken one, so it must not block a rebuild.
The public key is not optional. Without it Nix refuses the cache's paths — which is what you want, since an unsigned cache is one anybody can put anything into.
CI
.forgejo/workflows/packages.yml builds and publishes one job per package,
discovered from pkgs/ — a new file is picked up with no workflow edit.
fail-fast is off and each package publishes its own release, so the jobs share
nothing. That is deliberate: MAME's cache must not depend on an unrelated
package building.
Runs weekly and on dispatch. Not on push: a full MAME compile is about an hour on the 4-core runner, and with more than one person committing here, a job per push is not reasonable. The weekly run catches a nixpkgs bump that breaks a patch without anyone having to deploy first.
workflow_dispatch takes an optional only input to build a single package
rather than all of them.
.forgejo/workflows/signing-key.yml is the one-time key setup described above.