.. contents:: Table of Contents

---------------------
Installation overview
---------------------

Periodically the most recent cctbx source code including all
its dependencies is *automatically* exported from the source code
databases (CVS) and bundled into self-extracting files that are
published at:

  - http://cci.lbl.gov/cctbx_build/

This web page also provides self-extracting binary distributions for a
variety of platforms. It is most convenient to use these binary bundles
if possible. Installation is very simple and fast. The minimal
instructions are shown at the download page.

Source code bundles are available if a binary distribution cannot be
used. The Unix bundles include a file ``cctbx_install_script.csh``. If
Python 2.2.1 or higher is pre-installed on the target platform (e.g.
Redhat 8.0) the ``cctbx_bundle.selfx`` file is most useful. Otherwise it
is best to download the ``cctbx_python_bundle.selfx`` file because
the installation script will automatically install Python before
proceeding with the installation of the cctbx modules (but see the
`Mac OS X notes <http://cci.lbl.gov/cctbx_build/mac_os_x_notes.html>`_).
The Unix installation script is known to work with the following
compilers:

  - Linux: any gcc >= 2.96 (tested with gcc up to version 3.2.2;
    gcc 3.3 works without optimization only)
  - Tru64 Unix: cxx 6.5.1
  - IRIX: CC 7.3.1.2
  - Mac OS 10.2: gcc 3.3 (works without optimization only)

Other Unix platforms will most likely require adjustments of the
build scripts.

The self-extracting source code bundle for Windows (``cctbx_bundle.exe``)
does not include an installation script.

-----------------------------------------
Manually building from sources under Unix
-----------------------------------------

Building from sources requires Python 2.2.1 or higher and a working C++
compiler (see above). If Python is not available already it can be
installed in the following way::

  gunzip -c Python-2.2.2.tar.gz | tar xf -
  cd Python-2.2.2
  ./configure --prefix=/your/choice
  make
  make install

This installation does **not** require a privileged account (e.g. root).
It may be convenient (but is not required) to add the directory
``/your/choice/bin`` to the command-line search ``PATH``, e.g. using
``csh``::

  set path=(/your/choice/bin $path)

The most recent, complete cctbx source code is available in the file
`cctbx_bundle.tar.gz <http://cci.lbl.gov/cctbx_build/results/current/cctbx_bundle.tar.gz>`_
published at the cctbx build page. To unpack this file in a new, empty directory::

  gunzip -c cctbx_bundle.tar.gz | tar xf -

This creates a subdirectory ``cctbx_sources``. The installation
procedure should be executed in another directory, e.g.::

  mkdir cctbx_build
  cd cctbx_build
  /your/choice/bin/python ../cctbx_sources/libtbx/configure.py iotbx

The last command initializes the ``cctbx_build`` directory and 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

Shells other than ``csh`` may require a different command.

To compile all cctbx modules enter::

  libtbx.scons .

On a machine with multiple CPUs enter::

  libtbx.scons -j N .

where N is the number of CPUs available. The time required for the
compilations scales linearly with the number of CPUs available.

To run some regression tests after the compilation is finished enter::

  source setpaths_all.csh
  python $SCITBX_DIST/run_tests.py
  python $CCTBX_DIST/run_tests.py --Quick

The output should show many OK. A Python Traceback is an indicator
for problems.

-----------------------------------------------------------
Manually building from sources under Windows 2000 or higher
-----------------------------------------------------------

The cctbx installation requires Visual C++ 7.1 (Visual Studio .NET 2003).

To install Python under Windows 2000 it is best to use a binary
installer from the `Python download page <http://www.python.org/download/>`_.
The default choices presented by the installation wizard are usually fine.

The most recent, complete cctbx source code is available in the
self-extracting file
`cctbx_bundle.exe <http://cci.lbl.gov/cctbx_build/results/current/cctbx_bundle.exe>`_
published at the cctbx build page. To unpack this file in a new, empty
directory simply enter::

  cctbx_bundle.exe

This creates a subdirectory ``cctbx_sources``. The installation
procedure should be executed in another directory, e.g.::

  mkdir cctbx_build
  cd cctbx_build
  C:\python22\python.exe ..\cctbx_sources\libtbx\configure.py iotbx

The last command initializes the ``cctbx_build`` directory and creates
a file ``setpaths.bat`` (among others). This file must be used to
initialize a new shell or process with the cctbx settings::

  setpaths.bat

To compile all cctbx modules enter::

  libtbx.scons .

On a machine with multiple CPUs enter::

  libtbx.scons -j N .

where N is the number of CPUs available. The time required for the
compilations scales linearly with the number of CPUs available.

To run some regression tests after the compilation is finished enter::

  setpaths.bat all
  python %SCITBX_DIST%\run_tests.py
  python %CCTBX_DIST%\run_tests.py --Quick

The output should show many OK. A Python Traceback is an indicator
for problems.

----------------
Migrating to CVS
----------------

To participate in the development of the cctbx modules or to get easy
access to the most recent changes it may be useful to checkout some
modules directly from the CVS databases maintained at Sourceforge_.
To initialize access via anonymous cvs issue the command::

  cvs -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx login

At the prompt simply press the Enter key.

To replace the modules extracted from a source code bundle::

  cd cctbx_sources
  rm -rf libtbx boost_adaptbx scitbx cctbx iotbx
  cvs -z3 -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx co libtbx
  cvs -z3 -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx co boost_adaptbx
  cvs -z3 -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx co scitbx
  cvs -z3 -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx co cctbx
  cvs -z3 -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx co iotbx

To recompile run the ``libtbx.scons`` command again (``source setpaths.csh``
or run ``setpaths.bat`` first if necessary). This command is similar to the
more familar ``make`` command, only much more powerful. ``libtbx.scons``
is a very thin wrapper around SCons_. The `SCons documentation`_ applies
without modification.

In theory it is also possible to replace the boost directory from a
cctbx source code bundle with a working copy of the `boost CVS tree`_
at Sourceforge. However, many Boost_ developers do not have access to
all platforms for testing. In practice it happens quite often that a
``cvs update`` of the boost tree leads to compiler errors. Therefore we
believe that most users are best served by the stable boost libraries
included in the cctbx source code bundles. In irregular intervals we
migrate to the latest Boost release and work out all necessary
adjustments and fixes.

The source code in the ``ccp4io`` module is kindly provided by CCP4_. We
feel that it is not appropriate to keep this code in a CVS tree on
Sourceforge because it is developed and maintained by CCP4. Our
distribution contains a very small number of customizations (disabled
print and exit statements). Otherwise it is the original code
that we keep in sync with the master version provided by CCP4.

Back_

.. _Back: introduction.html

.. _SCons: http://www.scons.org/
.. _`SCons documentation`: http://www.scons.org/doc/HTML/scons-man.html
.. _Boost: http://www.boost.org/
.. _`boost CVS tree`: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/boost/boost/
.. _CCP4: http://www.ccp4.ac.uk/
.. _SourceForge: http://sourceforge.net/
