DOC: add note about manually downloading qhull + freetype

tacaswell · tacaswell · commit 26278b638dc7 · 2023-07-28T18:50:05.000-04:00
diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst
@@ -112,6 +112,9 @@ necessary to run the test suite, because different versions of FreeType
 rasterize characters differently) and of Qhull.  As an exception, Matplotlib
 defaults to the system version of FreeType on AIX.
 
+Use system libraries
+~~~~~~~~~~~~~~~~~~~~
+
 To force Matplotlib to use a copy of FreeType or Qhull already installed in
 your system, create a :file:`mplsetup.cfg` file with the following contents:
 
@@ -121,7 +124,16 @@ your system, create a :file:`mplsetup.cfg` file with the following contents:
    system_freetype = true
    system_qhull = true
 
-before running ``python -m pip install .``.
+before running
+
+.. code-block:: sh
+
+   python -m pip install .
+
+
+You can also use the :envvar:`MPLSETUPCFG` to specify the path to a cfg file when
+installing from pypi.
+
 
 In this case, you need to install the FreeType and Qhull library and headers.
 This can be achieved using a package manager, e.g. for FreeType:
@@ -174,6 +186,23 @@ remember to clear your artifacts before re-building::
   git clean -xfd
 
 
+Manual Download
+~~~~~~~~~~~~~~~
+
+
+If the automatic download does not work (for example on air-gapped systems) it
+is preferable to instead use system libraries.  However you can manually
+download and unpack the tarballs into::
+
+  build/freetype-2.6.1  # on all platforms but windows ARM64
+  build/freetype-2.11.1 # on windows ARM64
+  build/qhull-2020.2
+
+at the top level of the checkout repository.  The expected sha256 hashes of
+the downloaded tarballs is in :file:`setupext.py` if you wish to verify
+before unpacking.
+
+
 Minimum pip / manylinux support (linux)
 ---------------------------------------
 
diff --git a/setupext.py b/setupext.py
@@ -181,7 +181,8 @@ def get_and_extract_tarball(urls, sha, dirname):
 }
 # This is the version of FreeType to use when building a local version.  It
 # must match the value in lib/matplotlib.__init__.py, and the cache path in
-# `.circleci/config.yml`.
+# `.circleci/config.yml`. Also update the docs in
+# `docs/devel/dependencies.rst`.
 TESTING_VERSION_OF_FREETYPE = '2.6.1'
 if sys.platform.startswith('win') and platform.machine() == 'ARM64':
     # older versions of freetype are not supported for win/arm64
@@ -193,6 +194,7 @@ def get_and_extract_tarball(urls, sha, dirname):
 LOCAL_FREETYPE_HASH = _freetype_hashes.get(LOCAL_FREETYPE_VERSION, 'unknown')
 
 # Also update the cache path in `.circleci/config.yml`.
+# Also update the docs in `docs/devel/dependencies.rst`.
 LOCAL_QHULL_VERSION = '2020.2'
 LOCAL_QHULL_HASH = (
     'b5c2d7eb833278881b952c8a52d20179eab87766b00b865000469a45c1838b7e')
