wiki: Add Packaging niri page

3 files changed, 83 insertions, 19 deletions

diff --git a/wiki/Getting-Started.md b/wiki/Getting-Started.md
index 22a5b907..6637de0c 100644
--- a/wiki/Getting-Started.md
+++ b/wiki/Getting-Started.md
@@ -1,6 +1,6 @@
 The easiest way to get niri is to install one of the distribution packages.
 Here are some of them: [Fedora COPR](https://copr.fedorainfracloud.org/coprs/yalter/niri/) and [nightly COPR](https://copr.fedorainfracloud.org/coprs/yalter/niri-git/) (which I maintain myself), [NixOS Flake](https://github.com/sodiboo/niri-flake), and some more from repology below.
-See the [Building](#building) section if you'd like to compile niri yourself.
+See the [Building](#building) section if you'd like to compile niri yourself and the [Packaging niri](./Packaging-niri.md) page if you want to package niri.
 
 [![Packaging status](https://repology.org/badge/vertical-allrepos/niri.svg)](https://repology.org/project/niri/versions)
 
@@ -160,24 +160,6 @@ If you're not on NixOS, you may need [NixGL](https://github.com/nix-community/ni
 nix run --impure github:guibou/nixGL -- ./results/bin/niri
 ```
 
-### Packaging
-
-The recommended way to package niri is so that it runs as a standalone desktop session.
-To do that, put files into the correct directories according to this table.
-
-| File | Destination |
-| ---- | ----------- |
-| `target/release/niri` | `/usr/bin/` |
-| `resources/niri-session` | `/usr/bin/` |
-| `resources/niri.desktop` | `/usr/share/wayland-sessions/` |
-| `resources/niri-portals.conf` | `/usr/share/xdg-desktop-portal/` |
-| `resources/niri.service` (systemd) | `/usr/lib/systemd/user/` |
-| `resources/niri-shutdown.target` (systemd) | `/usr/lib/systemd/user/` |
-| `resources/dinit/niri` (dinit) | `/usr/lib/dinit.d/user/` |
-| `resources/dinit/niri-shutdown` (dinit) | `/usr/lib/dinit.d/user/` |
-
-Doing this will make niri appear in GDM and other display managers.
-
 ### Manual Installation
 
 If installing directly without a package, the recommended file destinations are slightly different.
diff --git a/wiki/Packaging-niri.md b/wiki/Packaging-niri.md
new file mode 100644
index 00000000..7348e032
--- /dev/null
+++ b/wiki/Packaging-niri.md
@@ -0,0 +1,81 @@
+### Overview
+
+When building niri, check `Cargo.toml` for a list of build features.
+For example, you can replace systemd integration with dinit integration using `cargo build --release --no-default-features --features dinit,dbus,xdp-gnome-screencast`.
+The defaults however should work fine for most distributions.
+
+> [!WARNING]
+> Do NOT build with `--all-features`!
+>
+> Some features are meant only for development use.
+> For example, one of the features enables collection of profiling data into a memory buffer that will grow indefinitely until you run out of memory.
+
+The `niri-visual-tests` sub-crate/binary is development-only and should not be packaged.
+
+The recommended way to package niri is so that it runs as a standalone desktop session.
+To do that, put files into the correct directories according to this table.
+
+| File | Destination |
+| ---- | ----------- |
+| `target/release/niri` | `/usr/bin/` |
+| `resources/niri-session` | `/usr/bin/` |
+| `resources/niri.desktop` | `/usr/share/wayland-sessions/` |
+| `resources/niri-portals.conf` | `/usr/share/xdg-desktop-portal/` |
+| `resources/niri.service` (systemd) | `/usr/lib/systemd/user/` |
+| `resources/niri-shutdown.target` (systemd) | `/usr/lib/systemd/user/` |
+| `resources/dinit/niri` (dinit) | `/usr/lib/dinit.d/user/` |
+| `resources/dinit/niri-shutdown` (dinit) | `/usr/lib/dinit.d/user/` |
+
+Doing this will make niri appear in GDM and other display managers.
+
+### Panics
+
+Good panic backtraces are required for diagnosing niri crashes.
+Please use the `niri panic` command to test that your package produces good backtraces.
+
+```
+$ niri panic
+thread 'main' panicked at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/time.rs:1142:31:
+overflow when subtracting durations
+stack backtrace:
+   0: rust_begin_unwind
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/std/src/panicking.rs:665:5
+   1: core::panicking::panic_fmt
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/panicking.rs:74:14
+   2: core::panicking::panic_display
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/panicking.rs:264:5
+   3: core::option::expect_failed
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/option.rs:2021:5
+   4: expect<core::time::Duration>
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/option.rs:933:21
+   5: sub
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/time.rs:1142:31
+   6: cause_panic
+             at /builddir/build/BUILD/niri-0.0.git.1699.279c8b6a-build/niri/src/utils/mod.rs:382:13
+   7: main
+             at /builddir/build/BUILD/niri-0.0.git.1699.279c8b6a-build/niri/src/main.rs:107:27
+   8: call_once<fn() -> core::result::Result<(), alloc::boxed::Box<dyn core::error::Error, alloc::alloc::Global>>, ()>
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/ops/function.rs:250:5
+note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
+```
+
+Important things to look for:
+
+- The panic message is there: "overflow when subtracting durations".
+- The backtrace goes all the way up to `main` and includes `cause_panic`.
+- The backtrace includes the file and line number for `cause_panic`: `at /.../src/utils/mod.rs:382:13`
+
+If possible, please ensure that your niri package on its own has good panics, i.e. *without* installing debuginfo or other packages.
+The user likely won't have debuginfo installed when their compositor first crashes, and we really want to be able to diagnose and fix all crashes right away.
+
+### Rust dependencies
+
+Every niri release comes with a vendored dependencies archive from `cargo vendor`.
+You can use it to build the corresponding niri release completely offline.
+
+If you don't want to use vendored dependencies, consider following the niri release's `Cargo.lock`.
+It contains the exact dependency versions that I used when testing the release.
+
+If you need to change the versions of some dependencies, pay extra attention to `smithay` and `smithay-drm-extras` commit hash.
+These crates don't currently have regular stable releases, so niri uses git snapshots.
+Upstream frequently has breaking changes (API and behavior), so you're strongly advised to use the exact commit hash from the niri release's `Cargo.lock`.
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
index c8454ad5..7952e4e1 100644
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -8,6 +8,7 @@
 * [Application-Specific Issues](./Application-Issues.md)
 * [Xwayland](./Xwayland.md)
 * [Gestures](./Gestures.md)
+* [Packaging niri](./Packaging-niri.md)
 * [FAQ](./FAQ.md)
 
 ## Configuration