[section:building If and How to Build a Boost.Math Library, and its Examples and Tests]

[h4 Building a Library (shared, dynamic .dll or static .lib)]

The first thing you need to ask yourself is "Do I need to build anything at all?"
as the bulk of this library is header only: meaning you can use it just by
#including the necessary header(s).

For most simple uses,
including a header (or few) is best for compile time and program size.

Refer to
[link extern_c C99 and C++ TR1 C-style Functions]
for pros and cons of using
the TR1 components as opposed to the header only ones.

The ['only] time you ['need] to build the library is if you want to use the
`extern "C"` functions declared in `<boost/math/tr1.hpp>`.  To build this
using Boost.Build, from a command-line boost-root directory issue a command like:

   bjam toolset=gcc --with-math install

that will do the job on Linux, while:

   bjam toolset=msvc --with-math --build-type=complete stage

will work better on Windows (leaving libraries built
in sub-folder `/stage` below your Boost root directory).
Either way you should consult the
[@http://www.boost.org/doc/libs/release/more/getting_started/index.html
getting started guide] for more information.

You can also build the libraries from your favourite IDE or command line tool:
each `extern "C"` function declared in `<boost/math/tr1.hpp>` has its own
source file with the same name in `libs/math/src/tr1`.  Just select the
sources corresponding to the functions you are using and build them into
a library, or else add them directly to your project.  Note that the
directory `libs/math/src/tr1` will need to be in your compiler's
#include path as well as the boost-root directory
(MSVC Tools, Options, Projects and Solutions, VC++ Directories, Include files).

[note If you are using
a Windows compiler that supports auto-linking and you have built the sources
yourself (or added them directly to your project) then you will need to
prevent `<boost/math/tr1.hpp>` from trying to auto-link to the binaries
that Boost.Build generates.  You can do this by defining either
BOOST_MATH_NO_LIB or BOOST_ALL_NO_LIB at project level
(so the defines get passed to each compiler invocation).
]

Optionally the sources in `libs/math/src/tr1` have support for using
`libs/math/src/tr1/pch.hpp` as a precompiled header
['if your compiler supports precompiled headers.]  Note that normally
this header is a do-nothing `#include` to activate the header so that
it #includes everything required by all the sources you will need to
define BOOST_BUILD_PCH_ENABLED on the command line, both when building
the pre-compiled header and when building the sources.  Boost.Build
will do this automatically when appropriate.

[h4 Building the Examples]

The examples are all located in `libs/math/example`, they can all
be built without reference to any external libraries, either with
Boost.Build using the supplied Jamfile, or from your compiler's
command line.  The only requirement is that the Boost headers are
in your compilers #include search path.

[h4 Building the Tests]

The tests are located in `libs/math/test` and are best built
using Boost.Build and the supplied Jamfile.  If you plan to
build them separately from your favourite IDE then you will
need to add `libs/math/test` to the list of your compiler's
search paths.

You will also need to build and link to
the Boost.Regex library for many of the tests: this can built
from the command line by following the
[@http://www.boost.org/doc/libs/release/more/getting_started/index.html
getting started guide], using commands such as:

   bjam toolset=gcc --with-regex install
or   
   bjam toolset=clang --with-regex install
or
   bjam toolset=gcc,clang --with-regex install
or
   bjam toolset=msvc --with-regex --build-type=complete stage

depending on whether you are on Linux or Windows.

Many of the tests have optional precompiled header support
using the header `libs/math/test/pch.hpp`.
Note that normally this header is a do-nothing include:
to activate the header so that
it `#include`s everything required by all the sources you will need to
define BOOST_BUILD_PCH_ENABLED on the command line, both when building
the pre-compiled header and when building the sources.  Boost.Build
will do this automatically when appropriate.

[endsect] [/section:building If and How to Build a Boost.Math Library, and its Examples and Tests]

[/ building.qbk
  Copyright 2006, 2007, 2008, 2010 John Maddock and Paul A. Bristow.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]