From 76e9eae32e6d8cbee2148c6ea6fb055e1118bf8c Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <me@wilfred.me.uk>
Date: Tue, 13 May 2025 01:14:24 +0100
Subject: [PATCH] Document how to build difftastic for packaging

Closes #531
Closes #813
---
 manual/src/SUMMARY.md              |  1 +
 manual/src/packaging_difftastic.md | 78 ++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 manual/src/packaging_difftastic.md

diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
index 079a53122..d303a7310 100644
--- a/manual/src/SUMMARY.md
+++ b/manual/src/SUMMARY.md
@@ -3,6 +3,7 @@
 - [Introduction](./introduction.md)
 - [Installation](./installation.md)
   - [From Source](./from_source.md)
+  - [Packaging Difftastic](./packaging_difftastic.md)
 - [Usage](./usage.md)
   - [Git](./git.md)
   - [Mercurial](./mercurial.md)
diff --git a/manual/src/packaging_difftastic.md b/manual/src/packaging_difftastic.md
new file mode 100644
index 000000000..7295f9614
--- /dev/null
+++ b/manual/src/packaging_difftastic.md
@@ -0,0 +1,78 @@
+# Packaging Difftastic
+
+This page contains recommendations for people creating a difftastic
+package.
+
+Note that the difftastic author only provides the source code and
+prebuilt binaries on GitHub. Packages have been created by other
+people -- thank you!
+
+## Packaging The Binary
+
+Difftastic can be built with `cargo`. The compiled binary will be at
+`target/release/difft` when using the following command.
+
+```
+$ cargo build --release
+```
+
+C library dependencies are built with the `cc` crate, which [exposes
+various environment
+variables](https://docs.rs/cc/1.1.30/cc/index.html#external-configuration-via-environment-variables)
+to configure the C toolchain (e.g. `CFLAGS`).
+
+### Reproducible Builds
+
+Difftastic's build script (the `build.rs` file) uses Rayon to build C
+libraries in parallel, which can lead to minor ordering changes in the
+final binary.
+
+You can avoid this by disabling Rayon parallelism.
+
+```bash
+$ RAYON_NUM_THREADS=1 cargo build --release
+```
+
+### MIME Database
+
+Difftastic depends on
+[tree_magic_mini](https://docs.rs/tree_magic_mini/latest/tree_magic_mini/),
+which access the MIME database on the current system. The MIME database is
+used to recognise file types, to ensure that binary files are not
+compared as text.
+
+This means that the difftastic package should depend on a MIME
+database package, if available.
+
+Difftastic respects the [XDG base
+specification](https://specifications.freedesktop.org/basedir-spec/latest/index.html#basics)
+to find the MIME database files. These files are typically at
+`/usr/share/mime`, `/usr/local/share/mime` or
+`/opt/homebrew/share/mime`.
+
+## Man Page
+
+As of difftastic 0.58, a man page is available. See the file
+`difft.1`.
+
+This file is generated from `difft.1.md`, but the generated `difft.1`
+is included in the repository for convenience.
+
+## The Manual
+
+Please consider including the difftastic manual with your
+package. These are HTML files that can be generated with `mdbook`.
+
+## Testing
+
+If your packaging tool supports testing, consider running the
+difftastic unit tests.
+
+```bash
+# Run the normal tests.
+$ cargo test
+
+# Run the tests that depend on the
+# MIME database being present.
+$ cargo test -- --ignored
+```