Clarify install docs

.gitignore

@@ -19,6 +19,7 @@ __pycache__/
 /docs/source/firedrake.rst
 /docs/source/firedrake.*.rst
 /docs/source/homebrew_deps.txt
+/docs/source/minimal_apt_deps.txt
 /docs/source/obtaining_pyop2.rst
 /docs/source/petsc_configure_options.txt
 /docs/source/team.rst

docs/Makefile

@@ -43,7 +43,7 @@ help:
 
 TARGETS = html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
-GENERATED_FILES = source/team.rst source/demos source/element_list.csv source/firedrake_citations.rst source/apt_deps.txt source/homebrew_deps.txt source/petsc_configure_options.txt
+GENERATED_FILES = source/team.rst source/demos source/element_list.csv source/firedrake_citations.rst source/apt_deps.txt source/homebrew_deps.txt source/minimal_apt_deps.txt source/petsc_configure_options.txt
 
 publishpdf:
 	env FIREDRAKE_MANUAL_RELEASE=`date +%Y-%m` $(MAKE) latexpdf
@@ -101,6 +101,13 @@ source/homebrew_deps.txt:
 		--show-system-packages > source/homebrew_deps.tmp
 	mv source/homebrew_deps.tmp source/homebrew_deps.txt
 
+source/minimal_apt_deps.txt:
+	python ../scripts/firedrake-configure \
+		--package-manager apt-x86_64 \
+		--show-minimal-system-packages > source/minimal_apt_deps.tmp
+	mv source/minimal_apt_deps.tmp source/minimal_apt_deps.txt
+
+
 source/petsc_configure_options.txt:
 	python ../scripts/firedrake-configure \
 		--no-package-manager \

docs/source/install.rst

@@ -20,6 +20,13 @@ it should be installable on any Linux distribution. Windows users are encouraged
 to use WSL_ or one of Firedrake's
 :ref:`alternative installation mechanisms<alternative_install>`.
 
+If installing on an HPC system most of the following steps should remain
+applicable, though care will have to be taken to make sure that the right system
+packages are used. A community-maintained collection of instructions for how to install
+Firedrake onto a number of different HPC systems may be found
+`here <https://github.com/firedrakeproject/firedrake/wiki/HPC-installation>`__.
+If install on an HPC system not included in the wiki, please consider contributing a
+page describing the installation on that system.
 
 .. _pip_install_firedrake:
 
@@ -92,9 +99,20 @@ which will install the following packages:
 .. literalinclude:: homebrew_deps.txt
    :language: text
 
-If you do not have one of these systems then these dependencies will need to
-be installed manually.
+The packages installed here are a combination of system dependencies,
+like a C compiler, BLAS, and MPI,  and 'external packages' that are used by PETSc, like
+MUMPS and HDF5.
 
+If you are not installing onto Ubuntu or macOS then it is your responsibility to
+ensure that these system dependencies are in place. Some of the dependencies
+(e.g. a C compiler) must come from your system whereas others, if desired, may be
+downloaded by PETSc ``configure`` by passing additional flags like
+``--download-mpich`` or ``--download-openblas`` (run ``./configure --help | less`` to
+see what is available). To give you a guide as to what system dependencies are
+needed, on Ubuntu they are:
+
+.. literalinclude:: minimal_apt_deps.txt
+   :language: text
 
 .. _install_petsc:
 

scripts/firedrake-configure

@@ -82,7 +82,18 @@ Please see https://firedrakeproject.org/install for more information."""
         "--show-system-packages",
         "--sysdeps",  # alias
         action="store_true",
-        help="Print out the system packages Firedrake needs. The user must install these.",
+        help=(
+            "Print out the system packages Firedrake needs including those "
+            "expected by PETSc."
+        ),
+    )
+    cmd_group.add_argument(
+        "--show-minimal-system-packages",
+        action="store_true",
+        help=(
+            "Print out the minimal system packages Firedrake needs to build. "
+            "The user must install these."
+        ),
     )
     cmd_group.add_argument(
         "--show-petsc-configure-options",
@@ -120,6 +131,13 @@ Please see https://firedrakeproject.org/install for more information."""
                 "please install them manually"
             )
         print(" ".join(SYSTEM_PACKAGES[package_manager, arch]), end="")
+    elif args.show_minimal_system_packages:
+        if package_manager is None:
+            raise RuntimeError(
+                "Cannot install Firedrake dependencies without a package manager, "
+                "please install them manually"
+            )
+        print(" ".join(MINIMAL_SYSTEM_PACKAGES[package_manager]), end="")
     elif args.show_petsc_configure_options:
         print(" ".join(PETSC_CONFIGURE_OPTIONS[package_manager, arch]), end="")
     elif args.show_petsc_version:
@@ -166,21 +184,21 @@ def has_homebrew() -> bool:
         raise RuntimeError("Unexpected error occurred searching for homebrew")
 
 
-BASE_LINUX_APT_PACKAGES = (
-    "bison",
+MINIMAL_LINUX_APT_PACKAGES = (
     "build-essential",
-    "cmake",
     "flex",
     "gfortran",
     "git",
-    "libopenblas-dev",
-    "libopenmpi-dev",
     "ninja-build",
     "pkg-config",
     "python3-dev",
     "python3-pip",
 )
 
+BASE_LINUX_APT_PACKAGES = (
+    MINIMAL_LINUX_APT_PACKAGES + ("bison", "cmake", "libopenblas-dev", "libopenmpi-dev")
+)
+
 PETSC_EXTRAS_LINUX_APT_PACKAGES = (
     "libfftw3-dev",
     "libfftw3-mpi-dev",
@@ -197,23 +215,24 @@ PETSC_EXTRAS_LINUX_APT_PACKAGES = (
     "libsuperlu-dist-dev",
 )
 
-COMMON_LINUX_APT_PACKAGES = BASE_LINUX_APT_PACKAGES + PETSC_EXTRAS_LINUX_APT_PACKAGES
+LINUX_APT_PACKAGES = BASE_LINUX_APT_PACKAGES + PETSC_EXTRAS_LINUX_APT_PACKAGES
 
-BASE_MACOS_HOMEBREW_PACKAGES = (
+MINIMAL_MACOS_HOMEBREW_PACKAGES = (
     "autoconf",
     "automake",
     "boost",
-    "cmake",
     "gcc",
     "libtool",
     "make",
     "ninja",
-    "openblas",
-    "openmpi",
     "pkg-config",
     "python",
 )
 
+BASE_MACOS_HOMEBREW_PACKAGES = (
+    MINIMAL_MACOS_HOMEBREW_PACKAGES + ("cmake", "openblas", "openmpi")
+)
+
 PETSC_EXTRAS_MACOS_HOMEBREW_PACKAGES = (
     "fftw",
     "hwloc",
@@ -225,17 +244,23 @@ PETSC_EXTRAS_MACOS_HOMEBREW_PACKAGES = (
     "zlib",
 )
 
-COMMON_MACOS_HOMEBREW_PACKAGES = (
+MACOS_HOMEBREW_PACKAGES = (
     BASE_MACOS_HOMEBREW_PACKAGES + PETSC_EXTRAS_MACOS_HOMEBREW_PACKAGES
 )
 
+MINIMAL_SYSTEM_PACKAGES = {
+    LINUX_APT_X86_64: MINIMAL_LINUX_APT_PACKAGES,
+    LINUX_APT_AARCH64: MINIMAL_LINUX_APT_PACKAGES,
+    MACOS_HOMEBREW_ARM64: MINIMAL_MACOS_HOMEBREW_PACKAGES,
+}
+
 SYSTEM_PACKAGES = {
-    (LINUX_APT_X86_64, ARCH_DEFAULT): COMMON_LINUX_APT_PACKAGES,
-    (LINUX_APT_X86_64, ARCH_COMPLEX): COMMON_LINUX_APT_PACKAGES,
-    (LINUX_APT_AARCH64, ARCH_DEFAULT): COMMON_LINUX_APT_PACKAGES,
-    (LINUX_APT_AARCH64, ARCH_COMPLEX): COMMON_LINUX_APT_PACKAGES,
-    (MACOS_HOMEBREW_ARM64, ARCH_DEFAULT): COMMON_MACOS_HOMEBREW_PACKAGES,
-    (MACOS_HOMEBREW_ARM64, ARCH_COMPLEX): COMMON_MACOS_HOMEBREW_PACKAGES,
+    (LINUX_APT_X86_64, ARCH_DEFAULT): LINUX_APT_PACKAGES,
+    (LINUX_APT_X86_64, ARCH_COMPLEX): LINUX_APT_PACKAGES,
+    (LINUX_APT_AARCH64, ARCH_DEFAULT): LINUX_APT_PACKAGES,
+    (LINUX_APT_AARCH64, ARCH_COMPLEX): LINUX_APT_PACKAGES,
+    (MACOS_HOMEBREW_ARM64, ARCH_DEFAULT): MACOS_HOMEBREW_PACKAGES,
+    (MACOS_HOMEBREW_ARM64, ARCH_COMPLEX): MACOS_HOMEBREW_PACKAGES,
 }
 
 COMMON_PETSC_CONFIGURE_OPTIONS = (