Nonsystem Boost
===============

(Accurate as of boost 1.47.0)

If you want to build against nonsystem boost (i.e. boost that isn't
available as a package) on linux, you need to use specific build
flags, so that boost's uniquely cantankerous build system generates
files that cmake's ``find_package()`` can find.  First you run the
included ``bootstrap.sh``, then run bjam like this::

  ./bjam threading=multi link=shared runtime-link=shared --layout=tagged install

If you're on ubuntu I recommend using `checkinstall
<https://help.ubuntu.com/community/CheckInstall>`_ for easy removal of
the package if you get things wrong.  Example::

  sudo checkinstall ./bjam threading=multi link=shared runtime-link=shared -j8 --layout=tagged --prefix=/usr/local/boost-1.40.0 install

Checkinstall will ask for a summary and such.  Be sure to check that
the autogenerated name of the package is reasonable (item 3 below)::

  *****************************************
  **** Debian package creation selected ***
  *****************************************

  *** Warning: The package name "boost_1_40_0" contains illegal
  *** Warning: characters. dpkg might not like that so I changed
  *** Warning: them to dashes.

  This package will be built according to these values:

  0 -  Maintainer: [ root@bsq ]
  1 -  Summary: [ boost 1.40.0 in /usr/local/boost-1.40.0 ]
  2 -  Name:    [ boost-1-40-0 ]
  3 -  Version: [ 20110926 ]
  4 -  Release: [ 1 ]
  5 -  License: [ GPL ]
  6 -  Group:   [ checkinstall ]
  7 -  Architecture: [ amd64 ]
  8 -  Source location: [ boost_1_40_0 ]
  9 -  Alternate source location: [  ]
  10 - Requires: [  ]
  11 - Provides: [ boost-1-40-0 ]
  12 - Conflicts: [  ]
  13 - Replaces: [  ]

  Enter a number to change any of them or press ENTER to continue:

With boost, ``checkinstall`` figures out a reasonable package name due
to the name of the directory that the boost tarball unpacks to.  With
others it can get it wrong... ``tmp`` is a terrible name for a
package.

When you then want to detect this new boost when running cmake, use
``BOOST_ROOT`` (see also the cmake docs for ``FindBoost``), e.g.:

.. code-block:: bash

   cmake ../src -DBOOST_ROOT=/usr/local/boost-1.40.0