docs: create PACKAGING.md

2 files changed, 131 insertions, 0 deletions

diff --git a/PACKAGING.md b/PACKAGING.md
new file mode 100644
index 0000000..c306bab
--- /dev/null
+++ b/PACKAGING.md
@@ -0,0 +1,128 @@
+# Packaging river for distribution
+
+First of all, I apologize for writing river in Zig. It will likely make
+your job harder until Zig is more mature/stable. I do however believe that
+writing my software in Zig allows me to deliver the best quality I can
+despite the drawbacks of depending on a relatively immature language/toolchain.
+
+## Source tarballs
+
+Source tarballs with stable checksums and git submodule sources included may
+be found on the [github releases](https://github.com/riverwm/river/releases)
+page. These tarballs are signed with the PGP key available on my website at
+<https://isaacfreund.com/public_key.txt>.
+
+For the 0.1.3 release for example, the tarball and signature URLs are:
+```
+https://github.com/riverwm/river/releases/download/v0.1.3/river-0.1.3.tar.gz
+https://github.com/riverwm/river/releases/download/v0.1.3/river-0.1.3.tar.gz.sig
+```
+
+## Zig version
+
+Until Zig 1.0, Zig releases will often have breaking changes that prevent
+river from building. River tracks the latest minor version Zig release
+and is only compatible with that release and any patch releases. At the time
+of writing for example river is compatible with Zig 0.9.0 and 0.9.1 but
+not Zig 0.8.0 or 0.10.0.
+
+## Build options
+
+River is built using the Zig build system. To see all available build
+options run `zig build --help`.
+
+Important: By default Zig will build for the host system/cpu using the
+equivalent of `-march=native`. To produce a portable binary `-Dcpu=baseline`
+at a minimum must be passed.
+
+Here are a few other options that are particularly relevant to packagers:
+
+- `-Dcpu=baseline`: Target the baseline CPU, or any other set of CPU features.
+
+- `-Dtarget=x86_64-linux-gnu`: Target architecture, OS, and ABI triple. See
+the output of `zig targets` for an exhaustive list of targets and CPU features,
+use of `jq(1)` to inspect the output recommended.
+
+- `-Dpie`: Build a position independent executable.
+
+- `-Dstrip`: Build without debug info. This not the same as invoking `strip(1)`
+on the resulting binary as it prevents the compiler from emitting debug info
+in the first place. For greatest effect, both may be used.
+
+- `--sysroot /path/to/sysroot`: Set the sysroot for cross compilation.
+
+- `--libc my_libc.txt`: Set system libc paths for cross compilation. Run
+`zig libc` to see a documented template for what this file should contain.
+
+- Enable compiler optimizations:
+
+  - `-Drelease-safe`: Keep all assertions and runtime safety checks active.
+
+  - `-Drelease-fast`: Optimize for execution speed, disable all assertions
+  and runtime safety checks.
+
+  - `-Drelease-small`: Optimize for binary size, disable all assertions and
+  runtime safety checks.
+
+Please use `-Drelease-safe` when building river for general use. CPU execution
+speed is not the performance bottleneck for river, the GPU is. Additionally,
+the increased safety is more than worth the binary size trade-off in my
+opinion.
+
+## Build prefix and DESTDIR
+
+To control the build prefix and directory use `--prefix` and the `DESTDIR`
+environment variable. For example
+```bash
+DESTDIR="/foo/bar" zig build --prefix /usr install
+```
+will install river to `/foo/bar/usr/bin/river`.
+
+The Zig build system only has a single install step, there is no way to build
+artifacts for a given prefix and then install those artifacts to that prefix
+at some later time. However, much existing distribution packaging tooling
+expect separate build and install steps. To fit the Zig build system into this
+tooling, I recommend the following pattern:
+
+```bash
+build() {
+    DESTDIR="/tmp/river-destdir" zig build --prefix /usr install
+}
+
+install() {
+    cp -r /tmp/river-destdir/* /desired/install/location
+}
+```
+
+## Examples
+
+Build for the host architecture and libc ABI:
+```bash
+DESTDIR=/foo/bar zig build -Drelease-safe -Dcpu=baseline \
+    -Dstrip -Dpie --prefix /usr install
+```
+
+Cross compile for aarch64 musl libc based linux:
+```bash
+cat > xbps_zig_libc.txt <<-EOF
+    include_dir=${XBPS_CROSS_BASE}/usr/include
+    sys_include_dir=${XBPS_CROSS_BASE}/usr/include
+    crt_dir=${XBPS_CROSS_BASE}/usr/lib
+    msvc_lib_dir=
+    kernel32_lib_dir=
+    gcc_dir=
+EOF
+
+DESTDIR="/foo/bar" zig build \
+    --sysroot "${XBPS_CROSS_BASE}" \
+    --libc xbps_zig_libc.txt \
+    -Dtarget=aarch64-linux-musl -Dcpu=baseline \
+    -Drelease-safe -Dstrip -Dpie \
+    --prefix /usr install
+```
+
+## Questions?
+
+If you have any questions feel free to reach out to me at
+`mail@isaacfreund.com` or in `#zig` or `#river` on `irc.libera.chat`, my
+nick is `ifreund`.
diff --git a/README.md b/README.md
index fd8f713..620f595 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,9 @@ zig build -Drelease-safe --prefix ~/.local install
 ```
 To enable experimental Xwayland support pass the `-Dxwayland` option as well.
 
+If you are packaging river for distribution, see also
+[PACKAGING.md](PACKAGING.md).
+
 ## Usage
 
 River can either be run nested in an X11/Wayland session or directly