Information

Documentation

Installation instructions (CrystFEL 0.9.1 and earlier)

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 should also install 'flex' and 'bison' from Homebrew, because the default versions on Mac OS are too old (Bison 2.6 or above is required). You will need to install Homebrew separately (see the instructions on its website), then simply do the following:

$ brew install gsl hdf5 flex bison argp-standalone pkg-config doxygen

3. Install the "optional" dependencies

Note: "optional" here means that you can install CrystFEL without these dependencies. However, you almost certainly don't want to. For example, the "optional" dependencies include the libraries necessary for the graphical user interface parts of CrystFEL.

The optional dependencies for CrystFEL are GTK2, Cairo, Pango, GDK-pixbuf, FFTW, 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 gtk3-devel cairo-devel pango-devel gdk-pixbuf2-devel fftw-devel ncurses-devel libpng-devel libtiff-devel

   For Debian:
$ sudo apt install libgtk-3-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+3 cairo pango gdk-pixbuf fftw libpng libtiff

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.9.0.tar.gz
$ cd crystfel-0.9.0

For CrystFEL version 0.8.0 and above, 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.

Again for Mac OS, you will need to help CrystFEL's build system find some of the libraries from Homebrew. Run these commands to set up the necessary environment variables:

$ 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"

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 ..
     or
$ ./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-0.8.0) and old CrystFEL versions, respectively:

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

CBFlib is not used at all by CrystFEL 0.9.0 and above, so you can ignore this point completely for those versions.