1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
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 CentOS and Fedora 22 or
later (for CentOS, replace `dnf` with `yum`):
```
$ 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.
|
