Tip Generic snapshot BUSTER release date 20240710.

Please note this version of BUSTER is for academic users and its download, installation and use is conditional on acceptance of the licence conditions. Please carefully review these licence conditions before download, installation or use.

1. Introduction

  • These instructions have been prepared on an updated Mac running macOS version 10.9 "Mavericks" but should work equally on later macOS versions (see wikipedia macOS page).

  • Please first check that the machine on which you are running the installation is running a supported macOS release by following Apple Support Finding your macOS version and build information

Note GPhL software will only run on Macs running macOS 10.9 onwards. Releases prior to 10.9 are NOT supported. Please also note that some external dependencies, the CSDS (see below) in particular, require a later version of macOS.

  • Installation is done from a user account software with administration privileges, using the bash shell and assuming that the browser downloads to the ~/Downloads directory.

  • You will probably have to adapt the procedure in places as you are likely to be installing in a different location and possibly with a different shell.

  • The following crystallographic packages are requirements for the use of BUSTER:

    • CCP4 Suite - required by all components of BUSTER

    • Cambridge Structural Database (CSDS) - not needed for structure refinement with BUSTER or ligand fitting with Rhofit, but required for dictionary generation with Grade/Grade2 and model analysis with buster-report

  • The following utility programs/packages are also required:

    • ImageMagick - required by buster-report

    • PyMOL - required by buster-report (we provide a binary for some operating systems)

    • TeX/LaTeX - required by buster-report (for PDF generation)

  • Instructions for installation of all of these programs/packages are given below. If you already have working installations of versions of the above packages that are compatible with BUSTER (see sections below for version information), then we would recommend that you use these installations and you may skip the corresponding section(s) below.

2. macOS packages

  • A number of packages that will be required for full installation of the Global Phasing software suite and of a number of its dependencies, are not installed by default.

  • Firstly, Xcode will be required. If not already installed on your machine, Xcode is available through the "App Store".

    • Once installed, open Xcode and from the main Xcode tab in the finder bar, then select "preferences". When the preferences window opens, select the Downloads tab and then select and install "command line options"

      • If your system is running 10.9 "Mavericks" the command line tools are installed by typing the command xcode-select --install from a terminal window.

    • From a terminal window execute the command:

sudo xcodebuild -license

  • X11 is also no longer supplied with macOS and needs to be installed.

    • Download the current X11 dmg file from https://www.xquartz.org, double click on it to open and then follow the instructions to install.

  • Finally, we recommend that you ensure that the OS is up to date by applying OS-recommended updates (particular security patches).

3. CCP4 (and Coot)

Tip Skip this section if you already have a working CCP4 8.0 (and Coot) installation.

  • On your Mac navigate to http://www.ccp4.ac.uk and then select Download.

    • Make sure you are looking at the Mac OS X pane.

    • Download the Package Manager by clicking on the orange Download Now! button.

    • This will download a file called macosx-x86_64_ccp4-8.0-setup.dmg to your Downloads folder

    • Navigate to the Downloads folder and double click on macosx-x86_64_ccp4-8.0-setup.dmg to open it.

    • This will open a large Setup icon, double click on the icon.

    • You may be asked "Are you sure you want to open it?" Click Open

    • You will now be asked Setup wants to make changes. Type your password to allow this.

Tip The CCP4 installation user must have administration privileges

  • You should see the CCP4 Software Suite Setup: follow the instructions.

    • Select CCP4 Program Suite v8.0.

    • If you are a publically funded academic institution or you have a valid commercial SHELX licence: select SHELX.

    • If you are a publically funded academic institution or you have a valid commercial ARP/wARP licence: select ARP/wARP v8.0.

    • Agree to CCP4 terms and conditions (if not done before).

    • Confirm the ARP/wARP licence (if appropriate) and agree to its terms and conditions.

    • The CCP4 suite and Coot will be installed in folder /Applications (no user choice!).

    • Make sure that the folder you give for Choose temporary for download: is writable.

  • CCP4 package should be downloaded and installed: have a cup of coffee!

    • The installation process will automatically install all CCP4 updates available at the time of installation. Post-installation, we would strongly recommend that you keep your CCP4 installation updated by applying new updates as they are released by CCP4 (either through running ccp4i2, ccp4i or ccp4um).

  • If you want to test the installation see quick test of the CCP4 installation.

    • Test that the coot executable has been installed correctly by running it and verifying that the GUI works:

coot

  • Optionally test that the ARP/wARP system has been installed correctly by running:

$warpbin/check_programs.sh $warpbin/auto_tracing.sh $warpbin
### You are running ARP/wARP 8.0 patch 1 ###

Tip This page uses green bold text for the commands you type, blue italic text for the output produced and red italics for comments. The command prompt is omitted to make copy/paste easier. Some long lines may be wrapped in your display but if you use copy and paste the commands should work fine.
Note
You must have a working installation of CCP4 before installing Global Phasing Software.
We strongly recommend that you keep your CCP4 installation updated by applying new updates as they are released by CCP4 either through running ccp4i2, ccp4i or ccp4um.

4. BUSTER installation

  • This section is omitted from the "Generic" pages included as files in the distribution because to see this page the install must have already been done.

  • For details please consult the specific page available at your download page, see https://www.globalphasing.com/

  • The last part of the output is important as it describes how users set up access to the software, (for example BUSTER-install-important-information-log.txt), see also section BUSTER user access .

  • At this stage of the installation you will have a working BUSTER refine.

  • If you want, this can be quickly tested by checking for licence information in the refine help message test-refine-licence-log.html.

Tip To get all Global Phasing Software working fully involves installing other packages and some further configuration as detailed below.

5. CSD-Core install

Note

The CSD-Core package is required for Grade2 to produce restraint dictionaries for ligands and for buster_report to perform Mogul ligand geometry validation.

CSD-Core works well when installed on a high-performance NFS but Grade2 will run slowly if the CSD and Mogul databases are accessed using a low-performance disk. It is possible to speed things up by making a copy of the databases to a high performance local disk. For further information please see the FAQ Grade2 runs slowly for a ligand. What can I do about this?.

  • Please follow the CCDC instructions for obtaining and installing the CSD-Core package. If you have any problems with this then please contact CCDC support.

  • These instructions will work with 2023.2 CSD and following but we strongly recommend that the latest CSD is installed (currently 2024.1).

  • Once you have installed CSD-core, please ensure that the CCDC licensing process is completed.

  • You should make then sure that you can run CSD applications, particularly Mogul. This is easily done by clicking the icon installed as part of the CSD-Core installation.

Tip

  • For servers without a graphical interface, you can check that Mogul works properly from the command line by:

~/CCDC/ccdc-software/mogul/mogul.app/Contents/MacOS/mogul -ins /dev/null
INFO: CSD = /home/software/CCDC/ccdc-data/csd/as545be
INFO: MOGULDATA = /home/software/CCDC/ccdc-data/mogul
INFO: VERSION = 2024.1.0 (401960)
INFO: Initialisation file: /home/software/xtal/CCDC/ccdc-software/mogul/bin/mogul.ini

  • You will have to alter the command if you did not install CSD in the default location.

  • The command should output information on the location of the CSD and Mogul Databases, as shown above.

Tip If you do cannot install CSD-Core you should set the environment variable BDG_CSD_TOP_DIRECTORY to none at the configure stage. Grade2 will then not work and buster_report will not be able to perform Mogul ligand geometry validation. If no local installation of CSD-Core is available, we recommend using the Grade Web Server for non-confidential ligands.

6. MacPorts / Fink

The Global Phasing software suite also requires a number of additional third party packages for which standard binary distributions / installation packages are not available.

Installation and configuration of either the MacPorts or Fink package managers provides the easiest means of compilation and installation of these packages. Of these two options, we would strongly recommend use of MacPorts over Fink as we have noted more issues with Fink installation.

6.1. MacPorts installation

  • download the latest appropriate version of MacPorts from MacPorts

    • double click on the downloaded MacPorts.pkg file to start the installation process. Follow the instructions to complete the installation.

6.2. Fink installation

  • download the latest fink tar file (appropriate for your OS X version) from fink download

  • to install the fink package manager:

mkdir ~/fink; cd ~/fink
tar xvf ~/Downloads/fink*.tar.gz
fink-0.35.1/
+lines of output edited out…………'
cd fink-0.35.1
./bootstrap /sw

  • Answer the questions during the installation process (generally the default answers are OK).

  • Following installation, to set up the fink package manager you should:

source /sw/bin/init.sh

  • or if you use tcsh or csh:

source /sw/bin/init.csh

7. Additional packages

buster-report requires the following additional packages:

pymol, imagemagick and the tex system.

  • To install these (having completed the previous step) execute the following:

If using MacPorts

sudo port install tcl -corefoundation
sudo port install tk -quartz
sudo port install pymol imagemagick texlive texlive-latex-extra

  • By default, the packages should be installed in /opt/local/bin. Following installation, ensure that this directory is on your path in order to run these packages.

If using Fink

fink install pymol-py27 imagemagick texlive

  • These packages should be installed in /sw/bin. Following installation, in order to run these packages, either ensure that this directory is on your path or source the /sw/bin/init.(c)sh script.

  • It is possible that compilation/installation of some of the dependencies that these packages require may fail. In this eventuality, run fink configure and reset the number of allowed cpu’s to 1 and then try again.

8. BUSTER configure

Note

  • The configuration procedure for CSD-core altered in May 2024 and so it is necessary to alter existing setup_local.*sh files prepared before this release.

  • The environment variable BDG_CSD_TOP_DIRECTORY should be set to the location of the top-level directory of the CSD installation.

  • Lines setting setting BDG_TOOL_MOGUL, BDG_TOOL_CSD_PYTHON_API or CSD_HOME should be removed from the file(s).

  • It is best that all obsolete CSD-related configuration variables are are explicitly unset in setup_local.*sh by: 

unset BDG_TOOL_MOGUL CSD_HOME BDG_TOOL_CSD_PYTHON_API

  • The following lines provide an example of the lines to be added to setup_local.sh: 

export BDG_CSD_TOP_DIRECTORY=~software/CCDC/ccdc-software/
unset BDG_TOOL_MOGUL CSD_HOME BDG_TOOL_CSD_PYTHON_API

  • This stage involves creating files setup_local.sh and/or setup_local.csh in the GPhL installation directory ~/GPhL/BUSTER_snapshot_20240710

Tip

  • The file setup_local.sh is sourced by the Global Phasing Software setup script setup.sh used by sh, bash and dash users (see BUSTER user access below).

  • The file setup_local.csh is sourced by the Global Phasing Software setup script setup.csh used by csh and tcsh users (see BUSTER user access below).

  • If all your users use the same shell then you only need to provide the appropriate script.

  • If you have a sophisticated environment with some software only licenced or available on certain machines then the setup_local.*sh files can use shell script tests to achieve this. Please ask for help if you need it.

  • In general setup_local.sh and/or setup_local.csh once created will work for future releases and can be simply copied from the previous installation.

  • Sample setup_local.*sh files are provided in the directory ~/GPhL/BUSTER_snapshot_20240710/samples/. These files explain all the possible options that can be set but only a few will need to be set.

  • First copy over the sample file(s) into installation directory ~/GPhL/BUSTER_snapshot_20240710

    • If your users use the sh, bash and dash shell copy the sample file into place:

cd ~/GPhL/BUSTER_snapshot_20240710/
cp ./samples/setup_local.sh .

  • But if your users use the csh or tcsh shell the copy the csh sample file into place:

cd ~/GPhL/BUSTER_snapshot_20240710/
cp ./samples/setup_local.csh .

  • Then using you favourite text editor (emacs, vim, nano, jot, gedit, …) to edit the file(s), setting:

    • BDG_CSD_TOP_DIRECTORY. For Grade2 to work BDG_CSD_TOP_DIRECTORY must be set to the location of the top-level directory for the CSD installation.

      • The CSD installation top-level directory must contain the subdirectory ccdc-software and the subdirectory ccdc-utilities. It will also normally contain the subdirectory ccdc-data that will be used as the default location of the Mogul and CSD databases (unless this is overridden by setting BDG_CCDC_DATA).

      • If you do cannot install CSD-Core you should set the environment variable BDG_CSD_TOP_DIRECTORY to none. Grade2 will then not work and buster_report will not be able to perform Mogul ligand geometry validation.

      • Please note that, CSD-Core works well when installed on a high-performance NFS but Grade2 will run slowly if the CSD and Mogul databases are accessed using a low-performance disk. It is possible to speed things up by making a copy of the databases to a high performance local disk. For further information please see the FAQ Grade2 runs slowly for a ligand. What can I do about this?.

    • Other environment variables can be set for advanced configuration, as described in the sample setup_local.*sh files, but generally this is not necessary.

  • Now test the installation as described in the Testing section.

    • If checkdeps reports ERRORs then you will have to modify $BDG_home/setup_local.sh and/or $BDG_home/setup_local.csh. To do so use your favourite editor then test again.

9. BUSTER test install

  • We supply checkdeps: a tool that checks that the dependencies of all our programs are met. In addition checks are made that each 3rd party program works properly.

  • To run checkdeps:

    1. open a new terminal or shell,

    2. then invoke the GPhL setup script (see useraccess), and

    3. enter the command checkdeps at the shell prompt.

  • For instance, if you are a bash user then:

. ~/GPhL/BUSTER_snapshot_20240710/setup.sh
checkdeps

  • You will be prompted before each individual program is checked, unless you run

. ~/GPhL/BUSTER_snapshot_20240710/setup.sh
checkdeps -n

  • The checks should take about 10 seconds cpu.

  • The program is deliberately verbose to provide full details about your setup to be included in bug reports. But note that checkdeps finishes with a simple summary of results: 

checkdeps FINAL SUMMARY
     refine (licence):     SUCCESS
     grade:                SUCCESS
     grade_PDB_ligand:     SUCCESS
     hydrogenate:          SUCCESS
     buster-report:        SUCCESS
     grade2:               SUCCESS
     pipedream:            SUCCESS

  • If a FAIL was reported then look through the output for the lines that start with ERROR. For instance if the configuration step has not been carried out then checkdeps will produce output similar to: checkdeps-log-fail.txt .

Note If you have installed and set up autoPROC separately checkdeps will also check that the autoPROC command process functions correctly (since pipedream may use it).

  • If the installation and configuration has been completed successfully then the checkdeps output will end with SUCCESS for each check. An example of the sort of output you should expect from a successful installation is: checkdeps-log-success.txt .

  • Once you have achieved SUCCESS then run checkdeps on the other hosts that you want to run the software on.

  • In addition run checkdeps from a normal users account to make sure there are no permissions issues.

  • If you have time and are interested then you could conduct more thorough checks involving running individual programs:

10. BUSTER user access

  • For users to run programs from the BUSTER suite they need to invoke our setup script.

  • A good way to do this is to create a soft link called BUSTER_latest to the directory for the installation we have just made:

cd ~/GPhL
rm -f BUSTER_latest
ln -s BUSTER_snapshot_20240710 BUSTER_latest

  • The soft link is useful because it means that when in the future you install a new version of the software the soft link can be updated so that users automatically use the latest version of the software (but the previous version will still be available if wanted).

  • Once you have created the soft link, bash, dash & zsh users should access the software typically by adding the following lines to their ~/.bashrc file:

# Provide access to BUSTER package (refine, grade2, aB_autorefine, rhofit, pipedream …):
. ~software/GPhL/BUSTER_latest/setup.sh

  • csh or tcsh users should access the software typically by adding the following lines to their ~/.cshrc file:

# Provide access to BUSTER package (refine, grade2, aB_autorefine, rhofit, pipedream …):
source ~software/GPhL/BUSTER_latest/setup.csh

Note

  • In addition, the BUSTER tools visualise-geometry-coot and visualise-rhofit-coot require that coot is on the user’s PATH. The standard CCP4 (version 6.5 or later) setup scripts now provide for this.

  • You may also want to provide user access to directly run the other software (for instance mogul) but this is not necessary to run BUSTER tools.

  • If you have a site-specific special mechanism to provide access to software then this should be used instead!

  • Reference cards that provide users with a summary of the most useful tools and options are supplied in the installation. It can be useful if these can be printed (double sided) and supplied to users. Or you might want to include their location in an announcement email. The reference cards can be found:

$BDG_home/docs/buster_reference_card.pdf
$BDG_home/docs/pipedream/manual/pipedream_reference_card.pdf

../common/icons/home.png Back to Generic installation top page