From b864d1084cc417500bc3ea86210d0d972a0d4c9f Mon Sep 17 00:00:00 2001
From: Julian Smith <julian.smith@artifex.com>
Date: Thu, 4 Jan 2024 17:34:07 +0000
Subject: [PATCH] docs/: added page about packaging for Linux distributions.

---
 docs/installation.rst |  6 +++
 docs/packaging.rst    | 97 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+)
 create mode 100644 docs/packaging.rst

diff --git a/docs/installation.rst b/docs/installation.rst
index fe2fc83f9..1edd1c99e 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -195,6 +195,12 @@ not generally supported:
   command line.
 
 
+Packaging
+---------
+
+See :doc:`packaging`.
+
+
 Enabling Integrated OCR Support
 ---------------------------------------------------------
 
diff --git a/docs/packaging.rst b/docs/packaging.rst
new file mode 100644
index 000000000..9fef79d99
--- /dev/null
+++ b/docs/packaging.rst
@@ -0,0 +1,97 @@
+.. include:: header.rst
+
+
+Packaging for Linux distributions
+=================================
+
+
+Requirements
+------------
+
+* Python
+* MuPDF checkout (including submodules).
+* PyMuPDF checkout.
+* System packages listed in `scripts/sysinstall.py:g_sys_packages`.
+* Python packages listed in `pyproject.toml`.
+
+Extra requirements for running tests:
+
+* Python packages listed in `scripts/gh_release.py:test_packages`.
+
+
+General steps
+-------------
+
+* Build and install MuPDF:
+  
+  * Install required system packages.
+  * Run `make install-shared-python` on MuPDF's `Makefile` with at least
+    these make variables:
+  
+    * `DESTDIR` set to the install directory, e.g. `/`.
+    *
+      `prefix` set to location relative to DESTDIR, such as `/usr/local` or
+      `/usr`. Must start with `/`.
+    * `USE_SYSTEM_LIBS=yes`.
+    * `HAVE_LEPTONICA=yes`.
+    * `HAVE_TESSERACT=yes`.
+
+* Build and install PyMuPDF:
+
+  *
+    Run `pip install ./PyMuPDF` or `pip wheel ./PyMuPDF` with at least these
+    environment variables:
+    
+    *
+      `PYMUPDF_SETUP_MUPDF_BUILD=` (empty string) to prevent download and build
+      of hard-coded MuPDF release.
+    *
+      `CFLAGS`, `CXXFLAGS` and `LDFLAGS` set to allow visibility of the
+      installed MuPDF headers and shared libraries.
+    *
+      `PYMUPDF_SETUP_IMPLEMENTATIONS=b` to build only the rebased
+      implementation. [This will become the default in a future release.]
+
+* Run PyMuPDF tests:
+
+  * Ensure required Python packages are available.
+  *
+    Run `pytest -k "not test_color_count" PyMuPDF` (test `test_color_count` is
+    known fail if MuPDF is not built with PyMuPDF's custom config.h).
+
+
+Use of scripts/sysinstall.py
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`scripts/sysinstall.py` provides a useful example of build commands
+that are known to to work, because it does a build, install and test
+using a local fake root director and is run regularly by Github action
+`.github/workflows/test_sysinstall.yml`.
+
+* Run with `-h` or look at the doc-string to see detailed usage information.
+* It uses Debian-style `apt` commands to install system packages.
+* By default it assumes local git checkouts `mupdf/` and `PyMuPDF/`.
+*
+  It currently installs only into a fake root directory because `pip` cannot
+  do a system install; the commands will need to be modified to install into
+  `/usr` or `/usr/local`.
+
+To run a full build, install and test in a local fake root:
+
+.. code-block:: shell
+
+    ./PyMuPDF/scripts/sysinstall.py
+
+To see what commands would be run without actually running them:
+
+.. code-block:: shell
+
+    ./PyMuPDF/scripts/sysinstall.py -m 0 -p 0 -t 0
+
+
+See also
+--------
+
+*
+  `setup.py`'s initial doc-comment has detailed information about the
+  environment variables used when building PyMuPDF.