libs/math/doc/overview/building.qbk

   1 [section:building If and How to Build a Boost.Math Library, and its Examples and Tests]
   2
   3 [h4 Building a Library (shared, dynamic .dll or static .lib)]
   4
   5 The first thing you need to ask yourself is "Do I need to build anything at all?"
   6 as the bulk of this library is header only: meaning you can use it just by
   7 #including the necessary header(s).
   8
   9 For most simple uses,
  10 including a header (or few) is best for compile time and program size.
  11
  12 Refer to
  13 [link extern_c C99 and C++ TR1 C-style Functions]
  14 for pros and cons of using
  15 the TR1 components as opposed to the header only ones.
  16
  17 The ['only] time you ['need] to build the library is if you want to use the
  18 `extern "C"` functions declared in `<boost/math/tr1.hpp>`.  To build this
  19 using Boost.Build, from a command-line boost-root directory issue a command like:
  20
  21    bjam toolset=gcc --with-math install
  22
  23 that will do the job on Linux, while:
  24
  25    bjam toolset=msvc --with-math --build-type=complete stage
  26
  27 will work better on Windows (leaving libraries built
  28 in sub-folder `/stage` below your Boost root directory).
  29 Either way you should consult the
  30 [@http://www.boost.org/doc/libs/release/more/getting_started/index.html
  31 getting started guide] for more information.
  32
  33 You can also build the libraries from your favourite IDE or command line tool:
  34 each `extern "C"` function declared in `<boost/math/tr1.hpp>` has its own
  35 source file with the same name in `libs/math/src/tr1`.  Just select the
  36 sources corresponding to the functions you are using and build them into
  37 a library, or else add them directly to your project.  Note that the
  38 directory `libs/math/src/tr1` will need to be in your compiler's
  39 #include path as well as the boost-root directory
  40 (MSVC Tools, Options, Projects and Solutions, VC++ Directories, Include files).
  41
  42 [note If you are using
  43 a Windows compiler that supports auto-linking and you have built the sources
  44 yourself (or added them directly to your project) then you will need to
  45 prevent `<boost/math/tr1.hpp>` from trying to auto-link to the binaries
  46 that Boost.Build generates.  You can do this by defining either
  47 BOOST_MATH_NO_LIB or BOOST_ALL_NO_LIB at project level
  48 (so the defines get passed to each compiler invocation).
  49 ]
  50
  51 Optionally the sources in `libs/math/src/tr1` have support for using
  52 `libs/math/src/tr1/pch.hpp` as a precompiled header
  53 ['if your compiler supports precompiled headers.]  Note that normally
  54 this header is a do-nothing `#include` to activate the header so that
  55 it #includes everything required by all the sources you will need to
  56 define BOOST_BUILD_PCH_ENABLED on the command line, both when building
  57 the pre-compiled header and when building the sources.  Boost.Build
  58 will do this automatically when appropriate.
  59
  60 [h4 Building the Examples]
  61
  62 The examples are all located in `libs/math/example`, they can all
  63 be built without reference to any external libraries, either with
  64 Boost.Build using the supplied Jamfile, or from your compiler's
  65 command line.  The only requirement is that the Boost headers are
  66 in your compilers #include search path.
  67
  68 [h4 Building the Tests]
  69
  70 The tests are located in `libs/math/test` and are best built
  71 using Boost.Build and the supplied Jamfile.  If you plan to
  72 build them separately from your favourite IDE then you will
  73 need to add `libs/math/test` to the list of your compiler's
  74 search paths.
  75
  76 You will also need to build and link to
  77 the Boost.Regex library for many of the tests: this can built
  78 from the command line by following the
  79 [@http://www.boost.org/doc/libs/release/more/getting_started/index.html
  80 getting started guide], using commands such as:
  81
  82    bjam toolset=gcc --with-regex install
  83 or
  84    bjam toolset=clang --with-regex install
  85 or
  86    bjam toolset=gcc,clang --with-regex install
  87 or
  88    bjam toolset=msvc --with-regex --build-type=complete stage
  89
  90 depending on whether you are on Linux or Windows.
  91
  92 Many of the tests have optional precompiled header support
  93 using the header `libs/math/test/pch.hpp`.
  94 Note that normally this header is a do-nothing include:
  95 to activate the header so that
  96 it `#include`s everything required by all the sources you will need to
  97 define BOOST_BUILD_PCH_ENABLED on the command line, both when building
  98 the pre-compiled header and when building the sources.  Boost.Build
  99 will do this automatically when appropriate.
 100
 101 [endsect] [/section:building If and How to Build a Boost.Math Library, and its Examples and Tests]
 102
 103 [/ building.qbk
 104   Copyright 2006, 2007, 2008, 2010 John Maddock and Paul A. Bristow.
 105   Distributed under the Boost Software License, Version 1.0.
 106   (See accompanying file LICENSE_1_0.txt or copy at
 107   http://www.boost.org/LICENSE_1_0.txt).
 108 ]