From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Wed, 14 Dec 2022 22:34:21 +0000 (+0000)
Subject: docs: Document new installation approaches
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?a=commitdiff_plain;h=43570cdb564414e8e1b5c6c90e96a153f8d1a945;p=hippotat.git

docs: Document new installation approaches

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---

diff --git a/docs/colophon.md b/docs/colophon.md
index 324f175..57e83be 100644
--- a/docs/colophon.md
+++ b/docs/colophon.md
@@ -1,5 +1,5 @@
-Colophon
-========
+Colophon and references
+=======================
 
 Hippotat is Copyright 2017-2022 Ian Jackson
 and contributors.
diff --git a/docs/install.md b/docs/install.md
index 5083a1b..bd740b5 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -9,11 +9,34 @@ It is most convenient to install (especailly the server) as a `.deb`.
 Building
 --------
 
-On a system with a new enough `cargo` and `rustc`:
+Obtain the source code from the canonical server:
+<https://salsa.debian.org/iwj/hippotat/>
+
+### Building with vanilla Debian tooling
+
+On a Debian (or derivative) with compatible dependencies,
+you can use the standard Debian build runes:
 
 ```
    apt-get build-dep .
-   CARGO='cargo --locked' dpkg-buildpackage -uc -b
+   dpkg-buildpackage -uc -b
+```
+
+At the time of writing this works on Debian testing (aka "bookworm").
+
+### Building binary packages with hybrid tooling
+
+Because of impedance mismatches between
+distros' approaches to packaging,
+and the language specifkc package manager treadmill,
+it can easily happy that you can't build on your Debian release.
+You can use a hybrid approach instead:
+
+On a system with a new enough `cargo` and `rustc`:
+
+```
+   apt-get -Pcargo-upstream build-dep .
+   CARGO='cargo --locked' dpkg-buildpackage -Pcargo-upstream -uc -b
 ```
 
 Sadly, Debian bullseye is not new enough;
@@ -26,11 +49,21 @@ The precise versions of those dependencies, and their precise contents,
 are controlled and checked
 by the `Cargo.lock` file shipped in the Hippotat source tree,
 provided that `cargo --locked` is used.
+So the invocation above is *not* equivalent to some `curl|bash` rune.
+
+### Building executables with upstream Rust ecosystem tooling
 
 If you don't want to install debs,
 you can also just use cargo to build the two binaries,
-`hippotat` and `hippotatd`.
-You could perhaps even `cargo install hippotat` on a client machine.
+`hippotat` and `hippotatd`:
+```
+    cargo build --locked --release
+```
+
+Hippotat releases are also published to `crates.io`, so
+you could perhaps even `cargo install hippotat`.
+Like any `cargo install`,
+this *is* morally equivalent to `curl|bash`.
 
 
 Installation