README

   1   ,-------------------------------------------------.
   2   |   ____                  _               _  _    |
   3   |  | __ )  ___   ___  ___| |_   _ __ ___ | || |   |
   4   |  |  _ \ / _ \ / _ \/ __| __| | '_ ` _ \| || |_  |
   5   |  | |_) | (_) | (_) \__ \ |_ _| | | | | |__   _| |
   6   |  |____/ \___/ \___/|___/\__(_)_| |_| |_|  |_|   |
   7   |                                                 |
   8   `-------------------------------------------------'
   9
  10 This package provides a set of M4 macros to use with Autoconf.  The purpose
  11 of these macros is to be able to easily find and test the various Boost
  12 libraries of a given version for a given compiler.  This package is released
  13 under GPLv3+.
  14
  15 HOWTO
  16 -----
  17
  18 1. If you have an invocation of AC_CONFIG_AUX_DIR in your configure.ac, then
  19    copy build-aux/boost.m4 in the directory specified by AC_CONFIG_AUX_DIR.
  20    Otherwise, copy the file at the root of your project.
  21 2. In your top-level Makefile.am (this supposes that you use automake, which
  22    you most likely do) add:
  23      ACLOCAL_AMFLAGS = -I <dir>
  24    where `<dir>' is the (relative) path to the directory where you copied
  25    boost.m4 (set it to `.' if you put boost.m4 in the same, top-level
  26    directory).
  27 3. Add a call to BOOST_REQUIRE to your configure.ac as well as other calls to
  28    the various BOOST_* macros that check for the libraries you need.
  29 4. Adjust your Makefile.am where you build targets that depend on Boost so
  30    that they use $(BOOST_CPPFLAGS), $(BOOST_*_LDFLAGS) and $(BOOST_*_LIBS)
  31    where appropriate (where `*' is the capitalized name of one of the
  32    libraries you checked for, e.g.: $(BOOST_THREADS_LDFLAGS)). E.g.:
  33       bin_PROGRAMS = foo
  34       foo_SOURCES = foo.cc
  35       foo_CPPFLAGS = $(BOOST_CPPFLAGS)
  36       foo_LDFLAGS = $(BOOST_THREAD_LDFLAGS)
  37       foo_LIBS = $(BOOST_THREAD_LIBS)
  38    Or if you have more than one target in the same Makefile.am and your
  39    targets don't have per-target specific flags (such as foo_LIBS) and you
  40    want all your targets to use the same set of Boost libraries, you can do
  41    the following instead:
  42       bin_PROGRAMS = foo bar
  43       foo_SOURCES = foo.cc
  44       bar_SOURCES = bar.cc
  45       AM_CPPFLAGS = $(BOOST_CPPFLAGS)
  46       AM_LDFLAGS = $(BOOST_THREADS_LDFLAGS)
  47       LIBS = $(BOOST_THREAD_LIBS)
  48    Remember that for targets that are programs, you must use LIBS or
  49    progname_LIBS, but for libraries you must use LDADD or libname_LDADD.
  50
  51 MACROS
  52 ------
  53 This section documents the various macros provided by boost.m4.
  54
  55   BOOST_REQUIRE([VERSION])
  56   ~~~~~~~~~~~~~~~~~~~~~~~~
  57 The first, most important macro, is BOOST_REQUIRE.  You should invoke it
  58 before other BOOST_* macros if you want to check that Boost has a minimum
  59 given version.
  60
  61 Here are some examples:
  62   # Do not require any specific minimum version
  63   BOOST_REQUIRE
  64   # Require at least 1.34.1
  65   BOOST_REQUIRE([1.34.1])
  66   # Require a version number known at runtime
  67   BOOST_REQUIRE([$some_shell_variable])
  68
  69 This macro defines the Make symbol BOOST_CPPFLAGS.
  70
  71
  72 There are various predefined macros to check for common Boost libraries.
  73 They are ordered in two categories: the Boost libraries that are only made of
  74 headers, and the Boost libraries that (may) require linking to an installed
  75 library.
  76
  77   Header-only Boost libraries
  78   ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79 For each of the Boost libraries that are only made of headers, the macro to
  80 invoke is BOOST_<LIB-NAME> where <LIB-NAME> is the capitalized name of the
  81 library.  Here is the list of libraries for which checks have been
  82 implemented:
  83     - Conversion
  84     - Foreach
  85     - Format
  86     - Utility
  87     - SmartPtr
  88     - StringAlgo
  89     - Tribool
  90     - Tuple
  91     - Variant
  92 Thus you can invoke BOOST_FOREACH (for instance).  It will check that
  93 <boost/foreach.hpp> works and define the preprocessor symbol
  94 HAVE_BOOST_FOREACH_HPP.  For each of the libraries mentioned above, a couple
  95 of headers are checked (the most important ones) and preprocessor symbols are
  96 defined in an identical fashion.
  97 If the check fails, configure with abort with a fatal error.
  98
  99   Boost libraries requiring linking
 100   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 101 For the other Boost libraries that (may) requiring linking to an installed
 102 library (shared or not), the macro to invoke is BOOST_<LIB-NAME> (surprise!)
 103 but this time the macro can take an optional argument to specify the runtime
 104 options you'd like to have.  Most of the time, Boost libraries are compiled
 105 in several flavors, such as with or without debug, with a multi-thread
 106 runtime or not, etc.  The macro will try to find a library that match your
 107 requirements but may fall back to another flavor of the library if the one you
 108 asked for isn't available.
 109 The following libraries are supported:
 110   - Filesystem
 111   - Graph
 112   - Threads
 113 Thus you can invoke BOOST_GRAPH (for instance) or BOOST_THREADS([mt-d]).
 114 The optional argument is made of one or more of the following letters:
 115   sgdpn (in that order)
 116 where:
 117   s = static runtime
 118   d = debug build
 119   g = debug/diagnostic runtime
 120   p = STLPort build
 121   n = (unsure) STLPort build without iostreams from STLPort
 122       (it looks like `n' must always be used along with `p').
 123 Additionally, it can start with `mt-' to indicate that there is a preference
 124 for multi-thread builds.
 125
 126 If the check is successful, at least one header has been checked and the
 127 corresponding preprocessor symbol HAVE_BOOST_*_HPP is defined, along with the
 128 compilation flags BOOST_<LIB-NAME>_LDFLAGS and BOOST_<LIB-NAME>_LIBS.
 129
 130   Writing your own checks / supporting more Boost libraries
 131   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 132 All the pre-existing library checks are written with help of
 133 BOOST_FIND_HEADER and BOOST_FIND_LIB.  These two macros are very easy to use
 134 and are documented in boost.m4.  Reading their documentation and reading the
 135 existing library checks should help you to easily write your own additional
 136 checks.  Please contribute them to me by email to <tsuna at lrde.epita.fr>.
 137
 138 You can checkout the Git source tree of this package at
 139 http://repo.or.cz/w/boost.m4.git
 140 Or simply download the latest version:
 141   wget 'http://repo.or.cz/w/boost.m4.git?a=blob_plain;f=build-aux/boost.m4;hb=HEAD' -O boost.m4
 142 Patches welcome.