Is CrystFEL already installed on your system?

Before installing CrystFEL yourself, consider that it might be installed already where you're working.

SLAC/LCLS (psana system)

If you're processing data on the LCLS psana system, you can use the pre-installed copy of CrystFEL. Type one of the following to set up your environment:

$ source /reg/g/cfel/crystfel/crystfel-0.7.0/setup-sh
$ source /reg/g/cfel/crystfel/crystfel-0.7.0/setup-csh

Use the .sh version if your shell is sh, bash or zsh. Use the .csh version if you use tcsh. If you don't know, your shell is probably bash. Replace the version number (0.7.0) with any other version if you need to, or with "dev" to get the development version. If you use the development version, read /reg/g/cfel/crystfel/crystfel-dev/ChangeLog every now and again to see what's changed.

CFEL/DESY (Maxwell system)

CrystFEL is installed in the CFEL software stack on Maxwell. Look on Confluence for instructions.

SBGrid Consortium laboratories

CrystFEL is installed and supported at SBGrid Consortium laboratories.

Installation instructions

1. Install the C compiler and development tools

Because you'll be compiling and installing CrystFEL from source code, you'll need to install the C compiler and related tools. If you've ever compiled anything from source before, you'll have these already. If this is the first time, one of the following commands should do the trick:

   For Fedora 22 and later:
$ sudo dnf group install 'Development Tools'

  For Debian or Ubuntu:
$ sudo apt install build-essential

For Mac OS, you will need the Command Line Tools ("CLT") for Xcode, or the full Xcode installation. To install the Xcode CLT, use the following:

$ xcode-select --install

Alternatively, you can install Xcode from the App Store or the Apple website.

2. Install the mandatory dependencies

The mandatory dependencies are HDF5 (version 1.8.0 or later) and the GNU Scientific Library (GSL). You can download these packages from their respective websites and install them separately, but we strongly recommend against it. It is much easier and more reliable to install them from your Linux distribution's package manager.

HDF5 is the file format which is used by CrystFEL. The HDF5 libraries are maintained by the HDF Group. You need HDF5 version 1.8.0 or later.

   For Fedora:
$ sudo dnf install hdf5-devel gsl-devel

   For Debian:
$ sudo apt install libhdf5-dev libgsl-dev

For other Linux distributions, look in the package management tool for packages with similar names to the above. Note that the "dev" or "devel" packages are needed (in addition to the plain library packages, which will be installed automatically).

For Mac OS, the best way to get the dependencies is using Homebrew. You will need to install Homebrew separately (see the instructions on its website), then simply do the following:

$ brew install gsl hdf5

3. Install the optional dependencies

The optional dependencies for CrystFEL are GTK2, Cairo, Pango, GDK-pixbuf, FFTW, CBFlib, OpenCL, Curses, libPNG and libTIFF. If these libraries are available, extra features will be enabled. For example, the GUI functions depend on GTK, and some indexing methods depend on FFTW. Most of these are available in distribution package managers already, so it's easy to install them. As before, you can install these from scratch using the source code downloaded from each package's website, but we emphatically recommend against it. GTK in particular has very many dependencies of its own. None of these are particularly exotic packages, a fact which you may need to carefully emphasise to your system administrator.

To get them all from your distribution's packaging system, try one of the following commands:

   For Fedora:
$ sudo dnf install gtk2-devel cairo-devel pango-devel gdk-pixbuf2-devel fftw-devel CBFlib-devel ncurses-devel libpng-devel libtiff-devel

   For Debian:
$ sudo apt install libgtk2.0-dev libcairo2-dev libpango1.0-dev libgdk-pixbuf2.0-dev libfftw3-dev libcbf-dev libncurses5-dev libpng-dev libtiff5-dev

If you want to install OpenCL to enable GPU acceleration of some functions, consult your GPU's documentation. This can be pretty tricky, and is only needed for speeding up simulation of patterns.

CrystFEL can use the following external programs for indexing diffraction patterns: MOSFLM (from CCP4, or separately installed), DirAx, XDS and Felix. The more of these programs you have available, the merrier!

For Mac OS, the optional dependencies will again come from Homebrew:

$ brew install gtk+ cairo pango gdk-pixbuf fftw libpng libtiff

Unfortunately there is no Homebrew formula for CBFlib yet. If you're on Mac OS and need to process images directly from CBF format, you'll need to install it separately. It has its own installation instructions on its website.

4. Download and install CrystFEL itself

See the download page for details of how to download CrystFEL. Unpack the download file and move into the folder:

$ tar -xzf crystfel-0.7.0.tar.gz
$ cd crystfel-0.7.0

For versions of CrystFEL after (not including) 0.7.0, you will need CMake in addition to the dependencies already installed. It is easy to install:

   For Fedora:
$ sudo dnf install cmake

   For Ubuntu and Debian:
$ sudo apt install cmake

For Mac OS, you should visit the CMake website download page, or run the command brew install cmake

Then, the following commands will compile and install CrystFEL:

$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

For older versions of CrystFEL (0.7.0 and earlier), use the following commands instead:

$ ./configure
$ make
$ sudo make install

Now, the CrystFEL programs should be accessible just as described in the other documentation.

Advanced installation options

Setting the installation location (prefix)

This is what to do if you want to install CrystFEL in your home directory or in another specific location rather than the usual system location.

Simply add an extra option to the cmake or "./configure" command in step 4:

$ cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ..
$ ./configure --prefix=/path/to/install

Specifying the location of CBFlib

This might be necessary if CBFlib is installed in a non-system location. For new (0.7.0+) and old CrystFEL versions, respectively:

$ cmake -DCBFLIB_CBF_INCLUDES=/path/to/cbflib/include -DCBF_LIBRARIES=/path/to/cbflib/lib/
$ ./configure --with-cbflib=/path/to/cbflib