Installation

This article has some little script snippets that should ease the installation of XDS and related programs like (XDS-viewer, xdsstat, xdsgui). It is assumed that binaries (or links to binaries) should go to /usr/local/bin . This means that you should do this as the administrator (root), or have sudo rights (Mac, and some Linux distros).

Linux

Log in as root - we need write permission for /usr/local/bin .

XDS package

If you are an academic user, as root

 cd /usr/local/bin
wget -O- ftp://ftp.mpimf-heidelberg.mpg.de/pub/kabsch/XDS-INTEL64_Linux_x86_64.tar.gz | tar xzvf -
ln -sf XDS-INTEL64_Linux_x86_64/* .


In case the above site is unavailable, there is a backup site.

other programs: XDS-Viewer, XDSSTAT, XDSCC12, XDSGUI, XSCALE_ISOCLUSTER, spot2pdb, generate_XDS.INP

... can be downloaded from https://strucbio.biologie.uni-konstanz.de/pub/linux_bin/ . A simple way to obtain them is to create an empty folder, "cd" to that folder and then

wget https://strucbio.biologie.uni-konstanz.de/pub/linux_bin/get_folder.sh
chmod +x get_folder.sh
./get_folder.sh


You may repeat this every now and then to update the programs.

As root, the script copies the programs into /usr/local/bin/linux_bin, and links them to /usr/local/bin. As a normal user, they are downloaded to $HOME/bin/linux_bin, and linked to your$HOME/bin. In the latter case, make sure that $HOME/bin is in your$PATH.

The Qt5 graphics library is now the default for xdsgui and xds-viewer. Qt4 versions are available as xdsgui.qt4 and xds-viewer.qt4, for old Linux distributions (and for use with x2goclient, which would otherwise need special action for Qt5 binaries).

tools and helper programs for generate_XDS.INP and XDSGUI, and libraries

Since XDSGUI depends on graphics packages that may need to be installed, you can check the xdsgui binary with

ldd which xdsgui | grep found


and that should show you the libraries it it didn't find. Your friendly system administrator will then work out the specific commands to install those libraries.

For RedHat-type distributions, that would typically be e.g.

yum provides libXfixes.so.3


the output of which will tell you that this is in the libXfixes RPM.

If in the case of Ubuntu you don't know the name of the package that provides a certain library, the

 sudo apt-file search <name-of-library>


command should find it for you (where <name-of-library> could e.g. be libGLU.so.1). This needs a one-time installation by

 sudo apt install apt-file
sudo apt-file update


Ubuntu 18.04: if libQtOpenGL.so.4 is missing, use sudo apt install libqt4-opengl.

Ubuntu 20.04: if libQtOpenGL.so.4 is missing (for the Qt4 binary of XDSGUI), use

sudo add-apt-repository -y ppa:rock-core/qt4
sudo apt update
sudo apt install libqt4-opengl


If the Qt5 libraries are missing, use sudo apt install libqt5gui5 libqt5printsupport5 libqt5opengl5.

On CentOS7, this would be yum -y install qt5-qtbase-gui qt5-qtbase .

xxdiff is likely available for your distribution - google for it, or try e.g.

yum -y install xxdiff


on RHEL6/CentOS6/SL6 systems, or

apt install xxdiff


on Ubuntu. If Ubuntu 20.04 doesn't find it, use the latest from http://archive.ubuntu.com/ubuntu/pool/universe/x/xxdiff/

An xxdiff binary that runs on CentOS7 (RHEL7, SL7) is provided by the get_folder.sh script.

Alternatively, tkdiff may be installed, or other graphical comparison programs, like meld or kdiff3. vimdiff is also nice, and probably already installed.

For Eiger data processing, H5ToXDS should be installed as explained, and h5dump should be installed by e.g. yum -y install hdf5 (Ubuntu: apt install hdf5-tools). Furthermore, you want the Neggia library or the Durin plugin.

Mac OSX

Attention: generate_XDS.INP requires the Xcode command line tools to be installed (free of charge): open a Terminal window, and enter sudo xcode-select --install. You may have to explicitly agree to the License terms when running a Command Line Tool (e.g. strings) for the first time.

Become familiar with the concept and ways to run commands as "root" - google "mac osx become root". All the installation tasks that are run in a Terminal window require root privileges, since some of the programs and their links are written to /usr/local/bin. (As an alternative that does not require root for installation, one may create a directory $HOME/bin and use that for the programs and links. That would also require modification of the$PATH, by a one-time echo 'export PATH=$PATH:$HOME/bin' >> ~/.profile)

So, prepare the following steps by opening the Terminal window, and then

sudo su                    # this will make you root, and ask for your password
mkdir /usr/local/bin  # only if /usr/local/bin was not created before


XDS package

If you are an academic user,

echo you may have to "sudo su" first, to obtain administrator permissions!
cd /usr/local/bin
curl -L -o - ftp://ftp.mpimf-heidelberg.mpg.de/pub/kabsch/XDS-OSX_64.tar.gz | tar xzvf -
ln -sf XDS-OSX_64/* .


Starting with macOS Catalina, you also need

xattr -dr XDS-OSX_64/*


if you get a security error popup (google "xattr com.apple.quarantine catalina").

other programs: XDS-viewer, XDSSTAT, XDSCC12, XDSGUI, XSCALE_ISOCLUSTER, generate_XDS.INP

... can be downloaded from https://strucbio.biologie.uni-konstanz.de/pub/mac_bin/ . A simple way to obtain them is is to open a Terminal, and type:

sudo su


# any folder would do; here we use /usr/local/bin/mac_bin
mkdir -p /usr/local/bin/mac_bin
cd /usr/local/bin/mac_bin
curl -O -R https://strucbio.biologie.uni-konstanz.de/pub/mac_bin/get_folder.sh
chmod +x get_folder.sh
./get_folder.sh


If you want to update the programs some time later, just run these commands again.

In order to enable Eiger data processing, the get_folder.sh script

1. copies Dectris' Neggia library into /usr/local/lib64
2. copies eiger2cbf-osx into /usr/local/bin, but under the name H5ToXds (GlobalPhasing's hdf2mini-cbf would be preferable but needs autoPROC license)
3. copies version 1.8.7 of h5dump into /usr/local/bin (a 1.10 version is required for Eiger data from DLS)

A 10.13 Qt5 version of XDS-viewer (compiled by T. Hauß) works on macOS Catalina, and is installed by get_folder.sh. Older Macs need this version; newer macOS should install 10.15. For XDSGUI, the Qt4 version is still the default, but a Qt5 version is available.

Lastly, it is useful (for e.g. XDSGUI) to install xxdiff from http://furius.ca/downloads/xxdiff/releases/macosx/ .

Troubleshooting

If any of the commands

ls -l /usr/local/bin/generate_XDS.INP
ls -l /usr/local/bin/xdsgui
ls -l /usr/local/bin/xds-viewer
# in the same way, check the other programs that should be used


returns a message like file or directory not found then this means that you do not have the symlink. But even if these commands do not return errors, you should also check the targets of the symlink, as shown in the output of the ls -l commands. Again, these commands should not return an error message. If they do, the programs are not installed in the location where the symlink points to. You'll have to install the programs properly (in /Applications) and make the symlink point to the correct location.

A quick way is also

which generate_XDS.INP xdsgui xds xds-viewer xdsstat xdscc12


and this should return a line for each of the programs asked for.

Windows

The programs of the XDS package as well as XDSGUI, XDSSTAT, XDSCC12 and so on may be run on 64bit Windows 10 within the Linux Subsystem for Windows (WSL, or preferably WSL2). This (easily!) installs e.g. an Ubuntu environment, which supports the apt package manager, so in principle any software available for Ubuntu may be installed (or other distros, see [1]).

A lot of technical detail is at [2] .

Graphical Linux programs require installation of a X server like Xming or VcXsvr or Mobaxterm on the Windows host. There are helpful writeups (e.g. [3] and [4]). VcXsrc seems to have a problem with coot for some people (see WSL2 installation and responses). To use the X server with WSL, one has to say in the shell window

export DISPLAY=:0


before running the program. Running XDSGUI under WSL's Ubuntu may require installation of a few packages with e.g.

sudo apt-get install libgomp1 libqtgui4


(see XDSGUI and above).

generate_XDS.INP requires a number of packages (some of which are only for specific detectors!); I'd start with

sudo apt-get install coreutils binutils gawk sed bc grep


and if required, also install python and hdf5-tools.

XDSSTAT and the conversion to MTZ files by XDSCONV require a CCP4 installation accessible by WSL. In principle, CCP4 may be installed within WSL (have not tested this), or on the Windows host.

(Screenshot provided by Gustavo Lima)

A detailed writeup for Ubuntu 20.04 LTS was provided by Dr Lata Panicker, SO(G), BARC, India.

WSL2

I got CCP4 7.1 including coot-0.9.3 to work on Ubuntu 20.04 LTS with Xming but not with VcXsrc. Getting the Xserver to work properly requires addition of 3 lines in ~/.bashrc :

export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print$2}'):0.0
export LIBGL_ALWAYS_INDIRECT=1
source /opt/xtal/ccp4-7.1/bin/ccp4.setup-sh


cd /mnt/c/Users/MYUSERNAME/
echo "[wsl2]" > .wslconfig
echo "kernelCommandLine = vsyscall=emulate" >> .wslconfig


to make the shelx* programs happy (see https://github.com/microsoft/WSL/issues/4694 ), and "vsyscall=emulate" appear in /proc/cmdline. After creating the file, WSL must be restarted (or the machine booted).

A few libraries also needed installation (tcsh is needed by CCP4, the others are graphics libraries):

sudo apt install tcsh libqt5opengl5 libqt5printsupport5 libqt5gui5 libxcb-render0 libxcb-shm0 libglu1-mesa


In addition, the Xming Xlaunch needed a box checked that prevents access control; and the Windows firewall needed a rule for port 6000 as shown in https://stackoverflow.com/questions/61110603/how-to-set-up-working-x11-forwarding-on-wsl2 .

Performance of coot is good enough for me (100 frames/sec for "Spin view" of a thaumatin molecule, on a Dell XPS13 7390 2-in-1 notebook). XDSGUI and multi-threaded XDS work as expected. For reading .h5 files, the NEGGIA plugin works correctly, but the DURIN plugin currently crashes (a bug has been reported).