mirror of
https://github.com/lucannez64/darling-lol.git
synced 2026-10-26 19:47:42 +00:00
fix(nix): simplify compiler setup and complete rootless session lifecycle
This commit is contained in:
Nicolai Bruns committed
1 parent
3c0b9cdfd3
commit
573f290552
12 files changed
+824
-176
No files matched your search
+229
@@ -0,0 +1,229 @@
|
||||
# Nix setup
|
||||
|
||||
The experimental Nix package provides a rootless build and launch environment
|
||||
for x86_64 Linux. It supplies the dependencies, not a prebuilt Darling runtime
|
||||
or game files. Initial setup builds Darling in a writable per-user workspace.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Enable Nix flakes and configure subordinate UID/GID ranges for your user. On
|
||||
NixOS, add this to your system configuration and rebuild:
|
||||
|
||||
```nix
|
||||
users.users.<name>.autoSubUidGidRange = true;
|
||||
```
|
||||
|
||||
On other Linux distributions, [install Nix using the official instructions](https://nixos.org/download/).
|
||||
You do not need to install NixOS. If you already use `nix-shell`, Nix is installed.
|
||||
Enable the modern CLI and flakes in `~/.config/nix/nix.conf`:
|
||||
|
||||
```ini
|
||||
experimental-features = nix-command flakes
|
||||
```
|
||||
|
||||
Alternatively, enable them for an individual command:
|
||||
|
||||
```sh
|
||||
nix --extra-experimental-features 'nix-command flakes' run github:lucannez64/darling-lol
|
||||
```
|
||||
|
||||
The rootless launcher requires unprivileged user namespaces, subordinate UID/GID
|
||||
ranges, and working `newuidmap`/`newgidmap` helpers. If these are already configured
|
||||
on your distribution, no additional host setup is needed.
|
||||
|
||||
Run setup in an interactive terminal and allow roughly 40–50 GB for the runtime
|
||||
build.
|
||||
|
||||
## Install and launch
|
||||
|
||||
Run the flake directly from GitHub; no local checkout is needed:
|
||||
|
||||
```sh
|
||||
nix run github:lucannez64/darling-lol
|
||||
```
|
||||
|
||||
On first launch, setup prompts to build Darling and install the Riot client.
|
||||
To explicitly open the installer, including for another region:
|
||||
|
||||
```sh
|
||||
nix run github:lucannez64/darling-lol#installer
|
||||
```
|
||||
|
||||
Setup prompts before building. Subsequent launches reuse a compatible runtime;
|
||||
they do not automatically rebuild it. If the package is installed in your
|
||||
profile or system configuration, the equivalent commands are
|
||||
`darling-lol --installer` and `darling-lol`. The desktop entry opens a terminal
|
||||
for prompts and session output.
|
||||
|
||||
Keep the terminal open while clients are running and until cleanup completes.
|
||||
Default and installer sessions wait for clients to exit, then shut Darling down
|
||||
in the same namespace. A failed shutdown is retried without discarding that
|
||||
namespace.
|
||||
|
||||
## Install permanently
|
||||
|
||||
`nix run` does not add commands to your profile or install a desktop menu entry.
|
||||
It does reuse downloaded store paths and the persistent Darling workspace.
|
||||
For commands on your `PATH` and desktop-menu access, install the package using
|
||||
one of the following methods.
|
||||
|
||||
### User profile (NixOS or other Linux distributions)
|
||||
|
||||
```sh
|
||||
nix profile add github:lucannez64/darling-lol#default
|
||||
```
|
||||
|
||||
Then launch from your application menu or terminal:
|
||||
|
||||
```sh
|
||||
darling-lol
|
||||
# Explicit setup or runtime shell:
|
||||
darling-lol --installer
|
||||
darling-lol-shell
|
||||
```
|
||||
|
||||
If the desktop entry does not appear, ensure your desktop session includes
|
||||
`~/.nix-profile/share` in `XDG_DATA_DIRS`, then log out and back in. Non-NixOS
|
||||
systems may need this desktop-session integration after installing Nix.
|
||||
|
||||
To upgrade, find the package's name with `nix profile list`, then run
|
||||
`nix profile upgrade <name>`. Close the clients first; after upgrading, run
|
||||
`darling-lol --update` to rebuild the mutable runtime when required.
|
||||
|
||||
### NixOS system configuration
|
||||
|
||||
In your system flake, add the input and pass it to your NixOS modules:
|
||||
|
||||
```nix
|
||||
inputs.darling-lol.url = "github:lucannez64/darling-lol";
|
||||
|
||||
outputs = inputs@{ nixpkgs, ... }: {
|
||||
nixosConfigurations.<hostname> = nixpkgs.lib.nixosSystem {
|
||||
system = "x86_64-linux";
|
||||
specialArgs = { inherit inputs; };
|
||||
modules = [ ./configuration.nix ];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Merge these entries into your existing flake rather than replacing its outputs.
|
||||
In `configuration.nix`, add the package and subordinate-ID configuration:
|
||||
|
||||
```nix
|
||||
{ inputs, pkgs, ... }:
|
||||
{
|
||||
environment.systemPackages = [
|
||||
inputs.darling-lol.packages.${pkgs.stdenv.hostPlatform.system}.default
|
||||
];
|
||||
users.users.<name>.autoSubUidGidRange = true;
|
||||
nix.settings.experimental-features = [ "nix-command" "flakes" ];
|
||||
}
|
||||
```
|
||||
|
||||
Apply with `sudo nixos-rebuild switch --flake .#<hostname>`. The launcher and
|
||||
desktop entry are then installed system-wide; each user still has a separate
|
||||
workspace and prefix. Start `darling-lol` as your normal user, not with sudo.
|
||||
|
||||
To upgrade, update the input with `nix flake update darling-lol`, rebuild your
|
||||
system, and run `darling-lol --update` after closing the clients.
|
||||
|
||||
## Update
|
||||
|
||||
Close League and both Riot clients and wait for the launcher to finish cleanup.
|
||||
Then run the updated flake and rebuild the runtime:
|
||||
|
||||
```sh
|
||||
nix run --refresh github:lucannez64/darling-lol -- --update
|
||||
# Installed package: darling-lol --update
|
||||
```
|
||||
|
||||
This rebuilds incrementally, installs the base runtime into the user-owned
|
||||
workspace, and refreshes the per-prefix overlays. No `sudo` is needed.
|
||||
|
||||
## Local checkout and scripts
|
||||
|
||||
You can also launch the flake directly from an already checked-out repository:
|
||||
|
||||
```sh
|
||||
cd /path/to/darling-lol
|
||||
nix run .
|
||||
```
|
||||
|
||||
Or clone it first:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/lucannez64/darling-lol.git
|
||||
cd darling-lol
|
||||
nix run .
|
||||
```
|
||||
|
||||
The same checkout also provides installer and update commands:
|
||||
|
||||
```sh
|
||||
nix run .#installer
|
||||
# After updating the checkout:
|
||||
nix run . -- --update
|
||||
```
|
||||
|
||||
These commands work on NixOS and other Linux distributions with Nix installed.
|
||||
Use `nix run` for this flake rather than `nix-shell`: the launcher sets up the
|
||||
rootless namespace in addition to supplying dependencies. `nix develop` is for
|
||||
development tools only; use `nix run .#shell` for an actual runtime shell.
|
||||
|
||||
To run a repository script inside the rootless FHS environment, pass its command
|
||||
after `--`. Commands run from the managed workspace, using the tools copied from
|
||||
the selected flake:
|
||||
|
||||
```sh
|
||||
nix run github:lucannez64/darling-lol -- python3 scripts/validate.py
|
||||
# Equivalent from a local checkout:
|
||||
nix run . -- python3 scripts/validate.py
|
||||
```
|
||||
|
||||
Use the supported installer/update commands for maintenance. Arbitrary script
|
||||
commands do not get the default launcher's automatic client-session cleanup; if
|
||||
a script starts Darling, shut it down in the same namespace before returning.
|
||||
For multiple commands, use an interactive runtime shell:
|
||||
|
||||
## Runtime shell
|
||||
|
||||
```sh
|
||||
nix run github:lucannez64/darling-lol#shell
|
||||
# Local checkout: nix run .#shell
|
||||
# Installed package: darling-lol-shell
|
||||
```
|
||||
|
||||
Use the launcher-provided shell rather than entering the raw FHS environment.
|
||||
If you start Darling manually in this shell, run `darling shutdown` there
|
||||
before exiting. A separately launched shell cannot reconnect to an existing
|
||||
Darling namespace.
|
||||
|
||||
## Files and operational limits
|
||||
|
||||
- Workspace: `${XDG_DATA_HOME:-$HOME/.local/share}/darling-lol`.
|
||||
- Default guest prefix: `$HOME/.darling`; set `DPREFIX` to use another prefix.
|
||||
Explicit `DPREFIX` and `RIOT_GUEST_HOME` overrides take precedence over saved
|
||||
configuration, so clear stale overrides before switching installations.
|
||||
- Package upgrades refresh managed tools and remove previously tracked obsolete
|
||||
files. Builds, the installed runtime, guest prefixes, and unmanaged files are
|
||||
preserved. Edit the source checkout rather than copied workspace tools.
|
||||
- One active session is supported per workspace. A workspace lock and live
|
||||
prefix marker prevent concurrent launches; the launcher does not kill an
|
||||
existing session or reconnect across namespaces. Inspect an unexpected live
|
||||
marker rather than deleting it to force a launch.
|
||||
- Readiness records in `build/nix-ready/` validate the selected prefix, guest,
|
||||
package, base runtime, and required overlays. A new prefix can reuse a
|
||||
compatible base runtime; failed setup invalidates readiness.
|
||||
- Keep `build/nix-gcroots/` while using the workspace. Mutable compiled binaries
|
||||
can reference Nix-store libraries, so these roots retain the package closures
|
||||
they need. Remove them only when discarding the dependent build outputs.
|
||||
|
||||
The launcher uses subordinate-ID user namespaces before entering the FHS
|
||||
environment. Mount privileges are scoped to that namespace, not host root;
|
||||
workspace and prefix files retain the Linux user's ownership. The setup does
|
||||
not install a host setuid binary or require a privileged runtime installation.
|
||||
|
||||
Darling compilation still happens outside Nix derivations and uses the host CPU;
|
||||
the resulting runtime is not a portable, binary-cacheable Nix package. The
|
||||
FFmpeg dependency is pinned to 8.x because the generated AV wrappers require
|
||||
its library ABI.
|
||||
+19
-59
@@ -1,73 +1,33 @@
|
||||
# Setup and portability
|
||||
|
||||
## NixOS package
|
||||
<a id="nixos-package"></a>
|
||||
|
||||
Use `darling-lol`, `darling-lol --installer`, or `darling-lol-shell` rather than
|
||||
invoking the raw FHS environment. The launcher uses `unshare --map-auto` before
|
||||
bubblewrap, so the user needs subordinate UID/GID ranges (`/etc/subuid` and
|
||||
`/etc/subgid`, or NixOS `users.users.<name>.autoSubUidGidRange = true`).
|
||||
Namespace root maps to a subordinate host ID, not host root. The FHS entrypoint
|
||||
restores the real Linux user's IDs while retaining namespace-only capabilities;
|
||||
the Darling shim temporarily switches effective IDs for mounts. No `sudo`,
|
||||
root-owned binary in a writable workspace, or host setuid installation is needed.
|
||||
## Nix package
|
||||
|
||||
The launcher refreshes managed scripts with executable bits and owner-write access,
|
||||
rejecting symlinks in that managed tree. It preserves `build/`, `usr-local/`, and
|
||||
the guest prefix. Edit the source checkout, not copied workspace tools.
|
||||
See [prerequisites](NIX.md#prerequisites) before starting, and the
|
||||
[Nix setup guide](NIX.md) for local checkout usage, updates, scripts, and runtime
|
||||
details.
|
||||
|
||||
First setup: run `darling-lol --installer` in an interactive terminal, choose the
|
||||
build when prompted, then choose the Riot region. The desktop entry uses
|
||||
`Terminal=true` and delegates terminal selection to the desktop environment.
|
||||
A launch with EOF stdin fails with a command to run in a terminal; it does not
|
||||
try a hard-coded list of terminal emulators or silently abandon a prompt.
|
||||
Run the experimental rootless package on x86_64 Linux:
|
||||
|
||||
Update: after manually exiting League and both Riot clients, shut down Darling
|
||||
in the ORIGINAL `darling-lol-shell` terminal with `darling shutdown`, then exit
|
||||
that shell. Upgrade the Nix package and run `darling-lol --update` in a terminal.
|
||||
This rebuilds incrementally, installs into the user-owned `/usr/local` bind,
|
||||
and installs paired per-prefix overlays without sudo. For a first-time setup,
|
||||
the same rootless update path performs the base build/install. Native/manual
|
||||
(non-Nix) instructions below still use their normal privileged base install.
|
||||
```sh
|
||||
nix --extra-experimental-features 'nix-command flakes' run github:lucannez64/darling-lol
|
||||
```
|
||||
|
||||
Readiness JSON under `build/nix-ready/` is keyed by canonical prefix and checks
|
||||
the configured guest and resolved host guest home, UID/GID, package path,
|
||||
maintained patch/tool identities, executable modes, base SDK/runtime metadata
|
||||
and required-overlay inventory. Stamping reuses required-artifact validation.
|
||||
Changing `RIOT_GUEST_HOME` invalidates readiness. Explicit `DPREFIX` and
|
||||
`RIOT_GUEST_HOME` environment overrides take precedence over saved configuration;
|
||||
clear stale values before selecting a different installation. A separate base
|
||||
manifest avoids rebuilding when only a new prefix needs overlays.
|
||||
Updates invalidate readiness before replacing the base; failed/interrupted setup
|
||||
cannot leave the previous prefix stamp authoritative. Existing app bundles never
|
||||
bypass these checks. Normal ready launches only check state, not rebuild.
|
||||
To install permanently, adding the launcher to your user profile:
|
||||
|
||||
Operational limits: each workspace supports one foreground namespace session.
|
||||
The launcher holds a lock while its child runs, even if bubblewrap closes file
|
||||
descriptors. It refuses a live `.init.pid` rather than reconnecting across new
|
||||
user namespaces or killing anything. A stale/reused live PID can therefore block
|
||||
a launch conservatively; inspect it before taking manual action. Never remove a
|
||||
marker just to force another launch. Manual stop/reconnect and game lifecycle
|
||||
acceptance have not been exercised with this repaired package. Keep the original
|
||||
shell open if you need to stop a session. Maintenance requires that prefix idle;
|
||||
rootless CMake's shutdown hook checks only that prefix, never enumerates and
|
||||
shuts down every user's launchd. The inherited scoped stop helper remains used
|
||||
by overlay installers; it is fixture-tested, not live-game tested here.
|
||||
```sh
|
||||
nix profile add github:lucannez64/darling-lol#default
|
||||
```
|
||||
|
||||
Mutable Linux ELF outputs can retain Nix-store interpreter/library references.
|
||||
A native compiler probe executed successfully with its store-path interpreter;
|
||||
there is no evidence that all such outputs require `patchelf`. The update path
|
||||
creates indirect closure roots under `build/nix-gcroots/` before compiling and
|
||||
retains old package roots for incremental outputs. Keep those roots while using
|
||||
the workspace; remove them only when discarding/rebuilding all dependent mutable
|
||||
outputs. This trades disk retention for GC safety, not a claim of full runtime
|
||||
relocatability. A full Darling build/upgrade and GC acceptance test remains open.
|
||||
Then run `darling-lol` or use the desktop application menu. See
|
||||
[permanent installation](NIX.md#install-permanently) for details.
|
||||
|
||||
The FFmpeg dependency is explicitly 8.x: generated Darling AV wrappers reference
|
||||
`libavformat.so.62`, `libavcodec.so.62`, and `libavutil.so.60`; FFmpeg 9 cannot
|
||||
replace those ABI versions.
|
||||
|
||||
Run the package regression suite with `python3 -m unittest discover -s tests -v`.
|
||||
First launch builds Darling and guides you through Riot client installation.
|
||||
NixOS is not required; other Linux distributions with Nix installed are also
|
||||
supported.
|
||||
|
||||
## Native setup notes
|
||||
|
||||
The patch manifest pins Darling to `60ba801decee7a00782f74f6be4c8ffb013f79ff` and records every changed submodule's revision. `scripts/prepare.py` checks each revision before applying patches and never resets an existing checkout to make a patch apply. Re-running it accepts an already-applied patch.
|
||||
|
||||
|
||||
Reference in new issue
Block a user