2,655
edits
m (update plugin descriptions for Mac) |
|||
(30 intermediate revisions by 2 users not shown) | |||
Line 9: | Line 9: | ||
This article has | This article has information that should ease the installation of XDS and related programs like ([[XDS-viewer]], [[xdsstat]], [[XDSGUI|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). | ||
Line 22: | Line 22: | ||
ln -sf XDS-INTEL64_Linux_x86_64/* . | ln -sf XDS-INTEL64_Linux_x86_64/* . | ||
</pre> | </pre> | ||
In case the above website is unavailable, there is a [https:// | In case the above website is unavailable, there is a [https://{{SERVERNAME}}/pub/xds backup site]. | ||
If you want to process data from the [[Eiger]] detector: see below for plugins that allow XDS to read the .h5 files. Similarly for gzip-ed CBF files as mostly collected at EMBL Hamburg. | If you want to process data from the [[Eiger]] detector: see below for plugins that allow XDS to read the .h5 files. Similarly for gzip-ed CBF files as mostly collected at EMBL Hamburg. | ||
Line 34: | Line 34: | ||
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. | 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. | ||
=== tools and helper programs for [[generate_XDS.INP]] and [[XDSGUI]], and libraries === | === tools and helper programs for [[generate_XDS.INP]] and [[XDSGUI]], and libraries === | ||
Line 43: | Line 41: | ||
Since XDSGUI depends on graphics packages that may need to be installed, you can check the xdsgui binary with | Since XDSGUI depends on graphics packages that may need to be installed, you can check the xdsgui binary with | ||
ldd `which xdsgui` | grep found | ldd `which xdsgui` | grep found | ||
and that should show you the libraries | and that should show you the libraries it didn't find. Your friendly system administrator knows the specific commands to install those libraries. | ||
N.B. this may list libpng15.so for the latest XDSGUI (compiled May 2023), but you can ignore that! | |||
For RedHat-type distributions, that would typically be e.g. | For RedHat-type distributions, that would typically be e.g. | ||
Line 55: | Line 55: | ||
sudo apt-file update | sudo apt-file update | ||
Ubuntu | Versions of XDSGUI compiled before 2021: Ubuntu 20.04: If the Qt5 libraries are missing, use <code>sudo apt install libqt5gui5 libqt5printsupport5 libqt5opengl5</code>. On CentOS7, this would be <code>yum -y install qt5-qtbase-gui qt5-qtbase</code> . | ||
Ubuntu | On Ubuntu, latest XDSGUI may require <code>sudo apt install libxcb-xinerama0</code> | ||
<code>xxdiff</code> is likely available for your distribution - google for it, or try e.g. | <code>xxdiff</code> is likely available for your distribution - google for it, or try e.g. | ||
Line 77: | Line 71: | ||
For [[Eiger]] data processing, a h5dump binary (version 1.10 req'd for HDF5 data from DLS) and <code>H5ToXDS</code> is installed by the <code>get_folder.sh</code> script into /usr/local/bin. If the script is not used, <code>H5ToXDS</code> should be installed as [[Eiger|explained]], and <code>h5dump</code> should be installed by e.g. <code>yum -y install hdf5</code> (Ubuntu: <code>apt install hdf5-tools</code>) - but make sure that h5dump is version 1.10 or higher when processing HDF5 data from DLS. | For [[Eiger]] data processing, a h5dump binary (version 1.10 req'd for HDF5 data from DLS) and <code>H5ToXDS</code> is installed by the <code>get_folder.sh</code> script into /usr/local/bin. If the script is not used, <code>H5ToXDS</code> should be installed as [[Eiger|explained]], and <code>h5dump</code> should be installed by e.g. <code>yum -y install hdf5</code> (Ubuntu: <code>apt install hdf5-tools</code>) - but make sure that h5dump is version 1.10 or higher when processing HDF5 data from DLS. | ||
The LIB= feature for HDF5 files requires either the [https://www.dectris.com/company/news/newsroom/news-details/process-eiger-data-with-xds-fast Neggia] library (does not work for HDF5 data from DLS) or the [https://github.com/DiamondLightSource/durin Durin plugin]. These may be installed through the <code>get_folder.sh</code> script, in <code>/usr/local/lib64</code>. For using LIB= with .gz files, there is the xds-zcbf plugin. All plugins can also be found in [https://{{SERVERNAME}}/pub/linux_bin the Linux installation directory.] | |||
== macOS == | == macOS == | ||
=== [[XDS]] package === | Become familiar with the concept and ways to run commands as "root" (administrator) - google "mac osx become root". Installation tasks that are run in a Terminal window require root privileges if the programs and their links are written to /usr/local/bin. | ||
Therefore, if /usr/local/bin does not yet exist, prepare the following steps by opening the Terminal window, and then | |||
sudo mkdir /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. Also, this requires modification of the $PATH, by a one-time | |||
mkdir $HOME/bin | |||
echo 'export PATH=$PATH:$HOME/bin' >> ~/.zprofile | |||
=== [[XDS]] package for Intel Macs === | |||
If you are an academic user, | If you are an academic user, | ||
# obtain root privileges (it will ask for your password): | |||
sudo su | |||
cd /usr/local/bin | cd /usr/local/bin | ||
curl -L -o - https://xds.mr.mpg.de/XDS-OSX_64.tar.gz | tar xzvf - | curl -L -o - https://xds.mr.mpg.de/XDS-OSX_64.tar.gz | tar xzvf - | ||
ln -sf XDS-OSX_64/* . | ln -sf XDS-OSX_64/* . | ||
# release root permissions: | |||
exit | |||
(If you don't have root privileges and run in $HOME/bin, only the curl and ln commands have to be run) | |||
Starting with macOS Catalina, you may also need | Starting with macOS Catalina, you may also need | ||
xattr -dr XDS-OSX_64 | sudo xattr -dr com.apple.quarantine XDS-OSX_64 | ||
if you get a security error popup (google "xattr com.apple.quarantine catalina"). | if you get a security error popup (google "xattr com.apple.quarantine catalina"). | ||
Then make sure that the binaries are in the search path for executables, as explained in https://xds.mr.mpg.de/html_doc/downloading.html . | Then make sure that the binaries are in the search path for executables, as also explained in https://xds.mr.mpg.de/html_doc/downloading.html . | ||
If you want to process .h5 files written by Eiger detectors on a Mac with Intel CPU, use the [https://{{SERVERNAME}}/pub/mac_bin/durin-plugin.so Durin plugin for Intel Mac processors] (source code [https://github.com/DiamondLightSource/durin available]) or the [https://{{SERVERNAME}}/pub/mac_bin/dectris-neggia.so Dectris-Neggia plugin for Intel Mac processors] (source code [https://github.com/dectris/neggia available]). The latter may be faster, but does not work on data collected at Diamond Light Source. The former should in principle work for all HDF5 data. See [[Installation#other_programs:_XDS-viewer,_XDSSTAT,_XDSCC12,_XDSGUI,_XSCALE_ISOCLUSTER,_generate_XDS.INP|below]] for installation of these .so files. | |||
If you want to process *.cbf.gz files on a Mac with Intel CPU, you may get faster processing with the [https://{{SERVERNAME}}/pub/mac_bin/xds-zcbf.so xds-zcbf plugin for Intel Mac processors] ([https://git.embl.de/nikolova/xds-zcbf source code]). | |||
See [[Installation#other_programs:_XDS-viewer,_XDSSTAT,_XDSCC12,_XDSGUI,_XSCALE_ISOCLUSTER,_generate_XDS.INP|below]] for installation of these .so files. | |||
==== XDS package for Macs with Apple M processors ==== | |||
The Intel Mac XDS programs also work on the Apple Silicon machines, but the plugin libraries (see below) for e.g. reading data from Eiger detectors don't, and the native binaries are faster. | |||
Thus, change the above <code>curl</code> and <code>ln</code> commands to | |||
# become root (it will ask for your password): | |||
sudo su | |||
cd /usr/local/bin | |||
curl -L -o - https://xds.mr.mpg.de/XDS-Apple_M1.tar.gz | tar xzvf - | curl -L -o - https://xds.mr.mpg.de/XDS-Apple_M1.tar.gz | tar xzvf - | ||
ln -sf XDS-Apple_M1/* . | ln -sf XDS-Apple_M1/* . | ||
# release root permissions: | |||
exit | |||
As explained above, you may need | |||
sudo xattr -d com.apple.quarantine XDS-Apple_M1/* | |||
if you get a security-related popup saying that Apple cannot verify the software. | |||
If you want to process .h5 files written by Eiger detectors, use the [https:// | If you want to process .h5 files written by Eiger detectors, use the [https://{{SERVERNAME}}/pub/mac_bin/durin-plugin-Apple-arm64.so Durin plugin for Apple ARM64 processors] (source code [https://github.com/DiamondLightSource/durin available]) or the [https://{{SERVERNAME}}/pub/mac_bin/dectris-neggia-Apple-arm64.so Dectris-Neggia plugin for Apple ARM64 processors] (source code [https://github.com/dectris/neggia available]). The latter may be faster, but does not work on data collected at Diamond Light Source. The former should in principle work for all HDF5 data. | ||
If you want to process *.cbf.gz files, you may get faster processing with the [https:// | If you want to process *.cbf.gz files, you may get faster processing with the [https://{{SERVERNAME}}/pub/mac_bin/xds-zcbf-Apple-arm64.so xds-zcbf plugin for Apple ARM64 processors] ([https://git.embl.de/nikolova/xds-zcbf source code]). | ||
See [[Installation#other_programs:_XDS-viewer,_XDSSTAT,_XDSCC12,_XDSGUI,_XSCALE_ISOCLUSTER,_generate_XDS.INP|below]] for installation of these .so files. | |||
=== Prerequisites (Xcode, CCP4) for [[generate_XDS.INP]], [[XDSGUI]] and other programs === | === Prerequisites (Xcode, CCP4) for [[generate_XDS.INP]], [[XDSGUI]] and other programs === | ||
Line 130: | Line 149: | ||
Only Terminal windows that are opened afterwards will have access to the CCP4 programs! | Only Terminal windows that are opened afterwards will have access to the CCP4 programs! | ||
=== other programs: [[XDS-viewer]], [[XDSSTAT]], [[XDSCC12]], [[XDSGUI]], [[XSCALE_ISOCLUSTER]], [[generate_XDS.INP]] === | === other programs: [[XDS-viewer]], [[XDSSTAT]], [[XDSCC12]], [[XDSGUI]], [[XSCALE_ISOCLUSTER]], [[generate_XDS.INP]] === | ||
... can be downloaded from https://{{SERVERNAME}}/pub/mac_bin/ . A simple way to obtain them is is to open a Terminal, and type: | ... can be downloaded from https://{{SERVERNAME}}/pub/mac_bin/ . A simple way to obtain them is is to open a Terminal, and type: | ||
sudo su | sudo su | ||
which asks for the password and gives you administrator permissions. Then, | which asks for the password and gives you administrator permissions. Then, for Intel Macs, | ||
# any folder would do; here we use /usr/local/bin/mac_bin | # any folder would do; here we use /usr/local/bin/mac_bin | ||
mkdir -p /usr/local/bin/mac_bin | mkdir -p /usr/local/bin/mac_bin | ||
Line 147: | Line 160: | ||
chmod +x get_folder.sh | chmod +x get_folder.sh | ||
./get_folder.sh | ./get_folder.sh | ||
For Silicon Macs, | |||
# 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://{{SERVERNAME}}/pub/mac_bin/get_folder_silicon.sh | |||
chmod +x get_folder_silicon.sh | |||
./get_folder_silicon.sh | |||
After that, release root privileges: | |||
exit | |||
If you want to update the programs some time later, just run these commands again. | If you want to update the programs some time later, just run these commands again. | ||
In order to enable [[Eiger]] data processing, the <code>get_folder.sh</code> script | In order to enable [[Eiger]] data processing, the <code>get_folder.sh</code> (or <code>get_folder_silicon.sh</code>) script | ||
# copies Dectris' Neggia library and DLS's Durin library into <code>/usr/local/lib64</code> | # copies Dectris' Neggia library and DLS's Durin library into <code>/usr/local/lib64</code> . NOTE that the names of the native libraries for the Apple Silicon Macs ends with *-Apple-arm64.so . On Silicon Macs you can either use the Intel binaries for XDSGUI and XDS, or the Silicon binaries - the latter are recommended. You could in principle mix them but then you have to be careful with what you enter in the LIB= line of XDS.INP; and what you enter in Menu/Preferences/Paths/generic library of XDSGUI. | ||
# copies [https://www.globalphasing.com GlobalPhasing's] <code>hdf2mini-cbf</code> into <code>/usr/local/bin</code>, but under the name <code>H5ToXds</code> (consider getting a [https://www.globalphasing.com/autoproc/ autoPROC] license!) | # copies [https://www.globalphasing.com GlobalPhasing's] <code>hdf2mini-cbf</code> into <code>/usr/local/bin</code>, but under the name <code>H5ToXds</code> (consider getting a [https://www.globalphasing.com/autoproc/ autoPROC] license!) | ||
# copies <code>h5dump</code> [https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.12/hdf5-1.12.1/bin/unix/hdf5-1.12.1-Std-macos11_64-clang.tar.gz] into <code>/usr/local/bin</code> | # copies <code>h5dump</code> [https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.12/hdf5-1.12.1/bin/unix/hdf5-1.12.1-Std-macos11_64-clang.tar.gz] into <code>/usr/local/bin</code> | ||
A [https://{{SERVERNAME}}/pub/mac_bin/XDS-Viewer-macOS10.13.dmg 10.13] Qt5 version of XDS-viewer (compiled by T. Hauß) works on macOS Catalina, and is installed by <code>get_folder.sh</code>. Older Macs need [https://{{SERVERNAME}}/pub/mac_bin/XDS-Viewer-0.6.dmg this version]; newer macOS should install [https://{{SERVERNAME}}/pub/mac_bin/XDS-Viewer-macOS10.15.dmg 10.15]. For XDSGUI, the | A [https://{{SERVERNAME}}/pub/mac_bin/XDS-Viewer-macOS10.13.dmg 10.13] Qt5 version of XDS-viewer (compiled by T. Hauß) works on macOS Catalina, and is installed by <code>get_folder.sh</code>. Older Macs need [https://{{SERVERNAME}}/pub/mac_bin/XDS-Viewer-0.6.dmg this version]; newer macOS should install [https://{{SERVERNAME}}/pub/mac_bin/XDS-Viewer-macOS10.15.dmg 10.15]. | ||
For XDSGUI, you have a choice between the version for Intel Macs and that for Silicon Macs. Both do work on Silicon Macs, except for the plugin libraries - for these, the correct version (ending with -Apple-arm64.so) must be used together with xdsgui_mac_silicon. | |||
Lastly, it is useful (for e.g. XDSGUI) to install <code>xxdiff</code> from http://furius.ca/downloads/xxdiff/releases/macosx/ . I had to go to System Preferences > Security & Privacy > Privacy and add <code>xxdiff</code> to the programs with full disk access. | Lastly, it is useful (for e.g. XDSGUI) to install <code>xxdiff</code> . This used to be available from http://furius.ca/downloads/xxdiff/releases/macosx/ , but is also [https://{{SERVERNAME}}/pub/mac_bin/xxdiff-4.0b1.osx.dmg here]. I had to go to System Preferences > Security & Privacy > Privacy and add <code>xxdiff</code> to the programs with full disk access. | ||
=== Troubleshooting === | === Troubleshooting === | ||
Line 194: | Line 218: | ||
(Screenshot provided by Gustavo Lima) | (Screenshot provided by Gustavo Lima) | ||
A detailed [https:// | A detailed [https://{{SERVERNAME}}/pub/xds%20%20prog%20installation%20in%20WSL%20(Lata%20Panicker).pdf writeup for Ubuntu 20.04 LTS] was provided by Dr Lata Panicker, SO(G), BARC, India. | ||
Update September 2021: With the current version of Windows 10 and WSL, the Qt5 binary of XDSGUI does not seem to allow editing in the XDS.INP tab. If this happens, either use an external editor or use xdsgui.qt4. In the latter case, you may have to install Qt4 libraries. | Update September 2021: With the current version of Windows 10 and WSL, the Qt5 binary of XDSGUI does not seem to allow editing in the XDS.INP tab. If this happens, either use an external editor or use xdsgui.qt4. In the latter case, you may have to install Qt4 libraries. |