Add macOS compiler failure to install FAQ (#4345)

Author: connorjward

docs/source/install.rst

@@ -262,23 +262,23 @@ No such file or directory: '/tmp/.../petsc/conf/petscvariables'
 
 If you encounter the error:
 
-   .. code-block:: text
-
-      FileNotFoundError: [Errno 2] No such file or directory: '/tmp/.../petsc/conf/petscvariables'
+.. code-block:: text
 
-when running the ``pip install`` instruction this is usually a sign that the
-environment variables ``PETSC_DIR`` or ``PETSC_ARCH`` are not set correctly.
-You can check this by making sure that you can run the following command
-without error::
-
-   $ ls $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/petscvariables 
+   FileNotFoundError: [Errno 2] No such file or directory: '/tmp/.../petsc/conf/petscvariables'
 
-If this raises an error then you should re-``export`` the variables necessary to
-build Firedrake as described :ref:`above<install_firedrake>`::
+when running the ``pip install`` instruction this is usually a sign that either:
+you are using a cached version of petsc4py that is linked incorrectly, or that
+the environment variables ``PETSC_DIR`` or ``PETSC_ARCH`` are not set correctly.
+To fix this we suggest purging the pip cache before re-exporting the environment
+variables::
 
+   $ pip cache purge
    $ export $(python3 firedrake-configure --show-env)
 
-and try the install again.
+You can check that ``PETSC_DIR`` and ``PETSC_ARCH`` are set correctly by making
+sure that you can run the following command without error::
+
+   $ ls $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/petscvariables 
 
 Missing symbols post install
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -291,13 +291,34 @@ the wrong compiled library. This is usually caused by issues with caching.
 To resolve the problem you should first remove any existing cached packages::
 
    $ pip uninstall -y h5py mpi4py petsc4py slepc4py
-   $ pip cache remove h5py
-   $ pip cache remove mpi4py
-   $ pip cache remove petsc4py
-   $ pip cache remove slepc4py
+   $ pip cache purge
 
 before re-running the instruction to install Firedrake.
 
+Unable to configure PETSc on macOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are running on macOS and encounter error messages during PETSc
+``configure`` like the following:
+
+.. code-block:: text
+
+   *********************************************************************************************
+              UNABLE to CONFIGURE with GIVEN OPTIONS (see configure.log for details):
+   ---------------------------------------------------------------------------------------------
+            Cannot use scalapack without Fortran, make sure you do NOT have --with-fc=0
+   *********************************************************************************************
+
+then this is usually a sign that your Homebrew and/or Xcode are too old. We
+recommend making sure that they are both up-to-date before trying again.
+
+For Homebrew it is sometimes useful to run the command::
+
+   $ brew doctor
+
+as this can flag issues with your system that should be resolved before
+installing Firedrake.
+
 .. _customising:
 
 Customising Firedrake