Update INSTALL.md

1 files changed, 95 insertions, 38 deletions

diff --git a/INSTALL.md b/INSTALL.md
index c2137937..f431dc27 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -55,8 +55,8 @@ to download and install any of them separately from source.  In particular, we
 emphatically recommend against trying to install GTK, Cairo, Pango or
 gdk-pixbuf from source.
 
-If OpenCL is available on your system, GPU-accelerated diffraction calculation
-will be enabled for `pattern_sim`.
+If OpenCL headers and corresponding GPU drivers are available on your system,
+GPU-accelerated diffraction calculation will be enabled for `pattern_sim`.
 
 Processing data relies on indexing 'engines'.  By default, you will have access
 to the [TakeTwo](https://journals.iucr.org/d/issues/2016/08/00/rr5128/) indexing
@@ -142,10 +142,12 @@ $ sudo make install
 Starting up
 -----------
 
-Run `indexamajig` for a basic check that the installation has succeeded.  It
-should complain that `You need to provide the input filename (use -i)`.
+Run `indexamajig` for a basic check that the installation has succeeded.  A
+healthy newborn CrystFEL should complain that `You need to provide the input
+filename (use -i)` when run with no other command-line options.
+
 Alternatively, run `crystfel` to start the graphical user interface, provided
-that GTK3 was available during installation.
+that the dependencies for the GUI were met (see above).
 
 Refer to the tutorial to see where to go from here!
 
@@ -156,46 +158,101 @@ The following problems are usually only encountered when installing dependencies
 manually, in non-standard locations and with multiple conflicting parallel
 installations of certain dependencies.
 
-* If you get an error about an incorrect number of parameters for `getpgrp`,
-  check that HDF5 was installed using CMake, not autotools (`./configure`).
-
-  The compiler flags generated by `h5cc -show` include all kinds of stuff that
-  shouldn't be there, such as `-D_BSD_SOURCE` which changes some function
-  prototypes (e.g. `getpgrp`).  Meson uses this method as a fallback if
-  `pkg-config` fails to locate HDF5, breaking the CrystFEL build because
-  CrystFEL calls `getpgrp` and relies on a certain function signature.
-  Therefore, you need to make sure that HDF5 is discovered using `pkg-config`,
-  not `h5cc`.  However, HDF5 only installs its `pkg-config` file when built
-  using CMake, not autotools.  This problem does not occur when building
-  CrystFEL with CMake, because CMake extracts the include paths from the `h5cc`
-  output.
-
-* The following error means that CrystFEL was accidentally compiled with headers
-  from a new HDF5 version (1.10 or higher) but linked with an older one (1.8 or
-  lower):
+* **Problem**: Linker error about HDF5 and `fPIC`:
+    ```
+    /usr/bin/ld: <install path>/lib/libhdf5.a(H5.o): relocation R_X86_64_32 against `.rodata' can not be used when making a shared object; recompile with -fPIC
+    ```
+
+  **Explanation**: CrystFEL uses several libraries, including HDF5, GSL and FFTW,
+  via its own shared library.  To make this work, the dependency libraries need
+  to have been compiled into relocatable code (position-independent code, hence
+  'PIC').
+
+  **Solution**: If compiling HDF5 with autotools (`./configure` et al.), add the
+  appropriate compiler option: `./configure H5_CFLAGS=-fPIC`.  The problem is
+  not known to occur when compiling HDF5 using CMake.
+
+* **Problem**: Linker error about FFTW and `fPIC`:
+    ```
+    /usr/bin/ld: /usr/lib/libfftw3.a(mapflags.o): relocation R_X86_64_32 against `.rodata' can not be used when making a shared object; recompile with -fPIC
+    /usr/lib/libfftw3.a: could not read symbols: Bad value
+    ```
+
+  **Explanation**: As above.
+
+  **Solution**: When building FFTW: `./configure --enabled-shared`.
+
+* **Problem**: Compiler error about `getpgrp`:
+    ```
+    ../libcrystfel/src/utils.c: In function ‘progress_bar’:
+    ../libcrystfel/src/utils.c:383:2: error: too few arguments to function ‘getpgrp’
+      if ( tcgetpgrp(STDERR_FILENO) != getpgrp() ) return;
+      ^
+    ````
+
+  **Explanation**: This one is is quite complicated, and ultimately due to a
+  misfeature of the HDF5 build process.  The compiler flags for HDF5, set via
+  the `CFLAGS` environment variable while compiling HDF5, are tracked through
+  into the output of the `h5cc` compiler driver program.  From here, they get
+  picked up by Meson and added to the compiler flags for CrystFEL.
+
+  It's not obvious from the HDF5 documentation, but `H5_CFLAGS` should be used
+  instead of `CFLAGS` for controlling how HDF5 itself is compiled.  `H5_CFLAGS`
+  are private to HDF5, whereas `CFLAGS` get added to `h5cc`.  Several Linux
+  distributions, including Arch and CentOS, apparently set some problematic
+  flags in `CFLAGS`.  One such flag is `-D_BSD_SOURCE`, which changes the
+  prototypes of certain system calls including `getpgrp`, breaking CrystFEL.
+
+  **Solution**: Three options:
+
+  Option 1: Do not use your distribution's HDF5 package.  Instead, compile
+  HDF5 yourself.  If you compile HDF5 with autotools (`./configure` et al.),
+  take care to use `H5_CFLAGS` instead of `CFLAGS` to add any compiler flags.
+  Ensure that the `h5cc` corresponding to the correct version of HDF5 is found,
+  by making sure that its location comes first in `PATH` when compiling
+  CrystFEL.
+
+  Option 2: Compile HDF5 using CMake instead of autotools.  In this case,
+  HDF5 will install a `pkg-config` file which Meson will use in preference to
+  `h5cc`.
+
+  Option 3: Compile CrystFEL using CMake instead of Meson.  CMake extracts
+  the include paths from the `h5cc` output and ignores the others.  However,
+  note that CrystFEL's CMake build process is deprecated and will eventually be
+  removed.
+
+
+* **Problem**: Linker error about missing HDF5 symbols:
     ```
     libcrystfel/libcrystfel.so.0.9.1: undefined reference to `H5P_CLS_LINK_CREATE_ID_g'
     libcrystfel/libcrystfel.so.0.9.1: undefined reference to `H5Oget_info_by_idx1'
     ```
+
+  **Explanation**: CrystFEL was accidentally compiled with headers from a new
+  HDF5 version (1.10 or higher) but linked with an older one (1.8 or lower).
   This can happen if there are headers in the include path corresponding to an
   HDF5 installation different to the one found during the configuration step of
   CrystFEL's build process.
 
-  The solution is to make sure that HDF5 is found consistently: make sure that
-  the `pkg-config` file (`libhdf5.pc`) exists and is found correctly (set
-  `PKG_CONFIG_PATH`).  If not using `pkg-config`, make sure that `PATH` is set
-  so that the location of the correct version of `h5cc` comes first.
+  **Solution**: Ensure that HDF5 is found consistently:  Make sure that
+  the `pkg-config` file (`libhdf5.pc` or `libhdf5-<version>.pc`) exists and is
+  found correctly (set `PKG_CONFIG_PATH`).  Make sure that `PATH` is set so
+  that the location of the correct version of `h5cc` comes first.
 
-* If, after fixing the above problem, you still get an error about
-  `H5Oget_info_by_idx` (note: no `1` at the end), there could be some residual
-  `ccache` files causing problems.  The (somewhat drastic) fix is simply to
-  `rm -rf ~/.ccache`.
+* **Problem**: After fixing the above problem, there is still a complaint about
+  HDF5: `H5Oget_info_by_idx` (note: no `1` at the end).
+
+  **Explanation**: This change to the HDF5 headers seems to confuse `ccache`.
+
+  **Solution**: The (somewhat drastic) fix is simply to `rm -rf ~/.ccache`.
+
+* **Problem**: After all of the above, HDF5 is *still* not found correctly.
+
+  **Explanation**: The `pkg-config` files for HDF5, if they exist, might
+  contain the version number.  Example: `libhdf5-1.12.0.pc`.  This makes them
+  difficult to find using `pkg-config`, because you have to know the version
+  number in advance!  For example, `pkg-config --cflags libhdf5-1.12.0`.
+
+  **Solution**: Upgrade to Meson 0.53.0 or later, which is aware of this quirk
+  and looks for any HDF5 `pkg-config` file.
 
-* If the build process complains about FFTW and `-fPIC`, make sure that your
-  installation of FFTW was configured with `./configure --enable-shared`:
-    ```
-    /usr/bin/ld: /usr/lib/libfftw3.a(mapflags.o): relocation R_X86_64_32 against `.rodata' can not be used when making a shared object; recompile with -fPIC
-    /usr/lib/libfftw3.a: could not read symbols: Bad value
-    ```
-  This is because CrystFEL uses the FFTW shared library via `libcrystfel`, which
-  is itself a shared library.