aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--INSTALL.md196
-rw-r--r--README.md70
2 files changed, 198 insertions, 68 deletions
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 00000000..25e07ba6
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,196 @@
+Installation instructions
+=========================
+
+CrystFEL installation is supported on GNU/Linux (including on Windows via
+[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/))
+and Mac OS X. A native installation on Windows is reported as possible, but is
+not supported.
+
+
+Supported installations at facilities
+-------------------------------------
+
+Before starting, check the [list of facility installations](https://www.desy.de/~twhite/crystfel/facilities.html)
+to find out if there's already a CrystFEL installation available at your site.
+
+If you want to use CrystFEL on a facility computer system, we recommend leaving
+the installation to facility IT staff. This means that a single installation
+can be shared and maintained. In addition, installing software from source, on
+a system where you don't have administrative access, can be quite difficult.
+Please feel free to tell the IT staff to get in touch with us for assistance,
+and also to make sure that the installation is documented on the list of
+supported facility installations.
+
+
+Dependencies
+------------
+
+Here are the mandatory dependencies - you cannot install CrystFEL without these:
+
+* Either [CMake](https://cmake.org/) 3.12 or later or [Meson](https://mesonbuild.com/) 0.50.0 or later (Meson is preferred)
+* [HDF5](https://www.hdfgroup.org/downloads/hdf5/) 1.8.0 or later (1.10.0 or later is required for many recent data formats which use the 'virtual data set' feature)
+* [GNU Scientific Library (GSL)](https://www.gnu.org/software/gsl/)
+* [Bison](https://www.gnu.org/software/bison/) 2.6 or later
+* [Flex](https://www.gnu.org/software/flex/)
+* [Zlib](https://www.zlib.net/) (1.2.3.5 or later preferred for better decompression speed)
+
+The following dependencies are "optional", in the sense that you can install
+CrystFEL without them. However, a CrystFEL installation without these will lack
+important features such as the graphical user interface. The following list is
+roughly in order of importance:
+
+* GTK3 (required for GUI)
+* Cairo (required for GUI)
+* Pango (required for GUI)
+* gdk-pixbuf (required for GUI)
+* [libccp4](ftp://ftp.ccp4.ac.uk/opensource/) (required for MTZ import/export)
+* [FFTW3](http://fftw.org/) (required for `asdf` indexing)
+* [FDIP](https://stash.desy.de/users/gevorkov/repos/fastdiffractionimageprocessing/) (for `peakFinder9` peak search algorithm)
+* NCurses (for integration diagnostics: `indexamajig --int-diag`)
+
+Apart from FDIP, all of the dependencies mentioned above (including libccp4 -
+yes, really!) should be available from your Linux distribution's package
+manager, or from [Homebrew](https://brew.sh/) on Mac OS. You should not need
+to download and install any of them separately from source, and we emphatically
+recommend against trying to do so.
+
+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
+algorithm. Provided that FFTW is available, you will also have access to the
+`asdf` algorithm. The more of the following are additionally installed, the
+better your experience will be:
+
+* [XGandalf](https://stash.desy.de/users/gevorkov/repos/xgandalf)
+* [PinkIndexer](https://stash.desy.de/users/gevorkov/repos/pinkindexer)
+* [Mosflm](https://www.mrc-lmb.cam.ac.uk/mosflm/mosflm/)
+* [DirAx](http://www.crystal.chem.uu.nl/distr/dirax/)
+* [XDS](http://xds.mpimf-heidelberg.mpg.de/)
+
+The indexing engines have their own installation instructions. XGandalf and
+PinkIndexer need to be installed before compiling CrystFEL, but the others can
+be installed at any time afterwards.
+
+Note that you only need the Mosflm binary, not the full `iMosflm` user interface.
+[Download it here](https://www.mrc-lmb.cam.ac.uk/mosflm/mosflm/ver730/pre-built/mosflm-linux-64-noX11.zip).
+
+You probably have CCP4 installed already, with its own copy of `mosflm`.
+However, you should keep your CCP4 installation separate from CrystFEL. The
+reason is that CCP4 comes with its own private copies of all its dependencies,
+and it becomes very difficult to make the build process for CrystFEL (or
+anything else) find the right versions of everything. Do not 'source' the CCP4
+setup file before trying to install CrystFEL, and make sure that the setup file
+is not automatically referenced in your shell setup files (`.bashrc` and
+others).
+
+Here are the commands to install all the basic dependencies (including the
+optional dependencies, but not the indexing engines) on Fedora 22 or later:
+```
+$ sudo dnf group install 'Development Tools'
+$ sudo dnf install hdf5-devel gsl-devel gtk3-devel cairo-devel pango-devel gdk-pixbuf2-devel meson cmake
+$ sudo dnf install fftw-devel ncurses-devel zeromq-devel msgpack-devel libccp4-devel
+```
+
+Here are the commands for Ubuntu and Debian:
+```
+$ sudo apt install build-essential
+$ sudo apt install libhdf5-dev libgsl-dev gtk3-devel cairo-devel pango-devel gdk-pixbuf2-devel meson cmake
+$ sudo apt install fftw-devel ncurses-devel libmsgpack-dev libzmq3-dev libccp4-dev
+```
+
+For Mac OS X, first install [Homebrew](https://brew.sh/), which will also cause
+[Xcode](https://developer.apple.com/xcode/) to be installed. Then:
+```
+$ brew install gsl hdf5 flex bison argp-standalone pkg-config doxygen gtk+3 cairo pango gdk-pixbuf fftw meson cmake
+$ export PATH="$(brew --prefix)/opt/bison/bin:$(brew --prefix)/opt/flex/bin:$PATH"
+$ export LDFLAGS="-L$(brew --prefix)/opt/bison/lib -L$(brew --prefix)/opt/flex/lib -L$(brew --prefix)/opt/argp-standalone/lib -largp $LDFLAGS"
+$ export CFLAGS="-I$(brew --prefix)/opt/flex/include -I$(brew --prefix)/opt/argp-standalone/include/ $CFLAGS"
+```
+The `export` commands ensure that the libraries installed via Homebrew can be
+found by CrystFEL's build system.
+
+
+Building and installing using Meson (recommended)
+-------------------------------------------------
+
+The actual compilation and installation step is very easy. Here are the
+commands:
+```
+$ meson build
+$ ninja -C build
+$ sudo ninja -C build install
+```
+
+
+Building and installing using CMake (deprecated)
+------------------------------------------------
+
+Compiling and installing using CMake is also simple:
+```
+$ mkdir build
+$ cd build
+$ cmake ..
+$ make
+$ 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)`.
+Alternatively, run `crystfel` to start the graphical user interface, provided
+that GTK3 was available during installation.
+
+Refer to the tutorial to see where to go from here!
+
+
+Notes about strange problems
+----------------------------
+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):
+ ```
+ 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'
+ ```
+ 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.
+
+* 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`.
+
+* 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.
diff --git a/README.md b/README.md
index c86a68ae..fd387fa9 100644
--- a/README.md
+++ b/README.md
@@ -29,78 +29,12 @@ specialised software suite are:
Getting started
---------------
+See INSTALL.md for installation instructions.
+
The best way to get started, after installation, is to run command ```crystfel```
to start the graphical user interface.
-Installation
-------------
-
-CrystFEL installation is supported on GNU/Linux and Mac OS X. The terse
-installation instructions below should be enough if you're experienced with
-installing software from source. More detailed installation information is
-available [on the website](https://www.desy.de/~twhite/crystfel/install.html).
-
-Here are the mandatory dependencies - you cannot install CrystFEL without these:
-
-* Either [CMake](https://cmake.org/) 3.12 or later or [Meson](https://mesonbuild.com/) (Meson is preferred)
-* [HDF5](https://www.hdfgroup.org/downloads/hdf5/) 1.8.0 or later (1.10.0 or later is required for many recent data formats)
-* [GNU Scientific Library (GSL)](https://www.gnu.org/software/gsl/)
-* [Bison](https://www.gnu.org/software/bison/) 2.6 or later
-* [Flex](https://www.gnu.org/software/flex/)
-* [Zlib](https://www.zlib.net/) (1.2.3.5 or later preferred for better decompression speed)
-
-The following dependencies are "optional", in the sense that you can install
-CrystFEL without them. However, a CrystFEL installation without these will lack
-important features such as the graphical user interface:
-
-* GTK3 or later
-* Cairo
-* Pango
-* gdk-pixbuf
-* NCurses
-* libPNG
-* [libccp4](ftp://ftp.ccp4.ac.uk/opensource/)
-
-Note that all of the dependencies mentioned above (including libccp4) should be
-available from your Linux distribution's package manager, or from
-[Homebrew](https://brew.sh/) on Mac OS. You should not need to download and
-install any of them separately from source, and we emphatically recommend
-against trying to do so!
-
-Note that using the libraries from the full CCP4 suite is not recommended. CCP4
-includes so many other libraries that it becomes very difficult to link using
-the correct versions of everything.
-
-Processing data relies on indexing algorithms. The more of the following are
-installed, the better your experience will be:
-
-* [FFTW3](http://fftw.org/)
-* [XGandalf](https://stash.desy.de/users/gevorkov/repos/xgandalf)
-* [PinkIndexer](https://stash.desy.de/users/gevorkov/repos/pinkindexer)
-* [Mosflm](https://www.mrc-lmb.cam.ac.uk/mosflm/mosflm/)
-* [DirAx](http://www.crystal.chem.uu.nl/distr/dirax/)
-* [XDS](http://xds.mpimf-heidelberg.mpg.de/)
-
-Installation follows the normal CMake procedure:
-
-```
-$ mkdir build
-$ cd build
-$ cmake ..
-$ make
-$ sudo make install
-```
-
-Or, with Meson:
-
-```
-$ meson . build
-$ ninja -C build
-$ sudo ninja -C build install
-```
-
-
Licence
-------