The easiest way to install cctbx is through the Conda package manager. You can get a full environment from Anaconda or just the conda package manager with the Miniconda installer.
There are two packages available, cctbx and cctbx-base. The cctbx package is cctbx-base with some additional packages (wxpython, pyside2, ipython).
With the conda command available, a new cctbx-base environment named my_env can be created with
conda create -n my_env -c conda-forge cctbx-base
To choose a specific version of Python, add the python package with the specific version
conda create -n my_env -c conda-forge cctbx-base python=3.8
Then the environment can be activated with
conda activate my_env
To install cctbx-base into the currently active environment, use
conda install -c conda-forge cctbx-base
The python package with a specific version can be added to change the version of python that is already installed in the active environment.
1. Download https://raw.githubusercontent.com/cctbx/cctbx_project/master/libtbx/auto_build/bootstrap.py in the directory where the cctbx and its dependencies shall be installed
2. Run python bootstrap.py (you may want to run it with the --help option first to discover the available options).
For better compatibility with newer operating systems, you will want to use conda packages for dependencies. Add the --use-conda flag and the command becomes python bootstrap.py --use-conda. This will run the miniconda installer if conda cannot be found. The environment with the dependencies will be located in the conda_base directory. See the description of the --use-conda flag from the --help output for more details.
The installation will take a long while (15 min - 1 hour, depending on your computer) but the script will verbosely describe what it does.
This creates the subdirectories base, build, and modules. The base directory contains dependencies for cctbx, build contains the compiled cctbx code, and modules contains the source code for cctbx. To keep bootstrap.py in your installation directory up-to-date with the version in modules, you can create a symbolic link to that version:
cd <installation directory>
rm bootstrap.py
ln -s ./modules/cctbx_project/libtbx/auto_build/bootstrap.py
Within the build directory, cctbx creates a file setpaths.csh (among others). This file must be used to initialize a new shell or process with the cctbx settings:
source setpaths.csh
There is also a setpaths.sh for bash users.
To update your cctbx installation to the latest version, you can just run:
python ./bootstrap.py
again in the <installation directory>. This will update the source code in the modules directory and recompile the changes (if necessary) in build. Occasionally, dependencies in base are updated. When this happens, just delete the base directory and rerun the bootstrap.py command.
To compile any local changes to the source code, enter the build directory and run:
make
This will actually run the libtbx.scons command using all available CPUs. You can also manually specify the number of CPUs to use, for example:
libtbx.scons -j 4
Note that libtbx.scons is just a thin wrapper around SCons. The SCons documentation applies without modification.
To run scripts with cctbx imports use the command:
libtbx.python your_script.py
(You can also use scitbx.python, cctbx.python, iotbx.python, etc.; all these commands are equivalent.)
For example, to run some regression tests after the compilation is finished enter:
source build/setpaths_all.csh
libtbx.python $SCITBX_DIST/run_tests.py
libtbx.python $CCTBX_DIST/run_tests.py --Quick
The output should show many OK. A Python Traceback is an indicator for problems.
Conceptually it is a trivial task to compile and link portable source code. However, in real life this is one of the most time-consuming nuisances, in particular if multiple, diverse platforms have to be supported. In the version 1.0 release of the cctbx we made an attempt to address this with the home-made fast track build system. Of course home-made is often good enough, but a professional solution is almost always better, especially if it comes with no strings attached.
Fortunately such a system is now available: SCons, short for Software Construction tool. This is a perfect fit for the cctbx because the SCons developers have apparently adopted a similar “professional is better than home-made” philosophy: SCons is implemented in pure Python, and SCons configuration files (the equivalent of Makefiles) are pure Python scripts. SCons has many advantages compared to a traditional make-based build system. To quote some points from the SCons documentation:
When we moved from our home-grown build system to SCons we found all these points to be perfectly true. It only took very little effort to write a small configure script for setting up a master SConstruct file based on the user’s choice of which cctbx modules to use and which to ignore. New modules can easily be tied into this system simply by providing a SConstruct file in the module’s top-level directory. The author of the new module has complete control over the build process. The existing settings can simply be reused, customized, or totally replaced, all within one uniform and 100% platform-independent framework, the Python language.