README

   1   ,-------------------------------------------------.
   2   |   ____                  _               _  _    |
   3   |  | __ )  ___   ___  ___| |_   _ __ ___ | || |   |
   4   |  |  _ \ / _ \ / _ \/ __| __| | '_ ` _ \| || |_  |
   5   |  | |_) | (_) | (_) \__ \ |_ _| | | | | |__   _| |
   6   |  |____/ \___/ \___/|___/\__(_)_| |_| |_|  |_|   |
   7   |                                                 |
   8   `-------------------------------------------------'
   9
  10 This package provides a set of M4 macros to use with GNU Autoconf.  The
  11 purpose of these macros is to be able to easily find and test the various
  12 Boost libraries of a given version for a given compiler.  This package is
  13 released under GPLv3+.
  14 This macro requires that you use GNU Libtool and assumes that you already
  15 use GNU Automake.  If you don't already use Libtool, the step 3 below
  16 explains how to set it up.
  17
  18 HOWTO
  19 -----
  20
  21 1. If you have an invocation of AC_CONFIG_AUX_DIR in your configure.ac, then
  22    copy build-aux/boost.m4 in the directory specified by AC_CONFIG_AUX_DIR.
  23    Otherwise, copy the file at the root of your project.
  24 2. In your top-level Makefile.am (this supposes that you use automake, which
  25    you most likely do) add:
  26      ACLOCAL_AMFLAGS = -I <dir>
  27    where `<dir>' is the (relative) path to the directory where you copied
  28    boost.m4 (set it to `.' if you put boost.m4 in the same, top-level
  29    directory).
  30 3. If you don't use GNU Libtool already, then time has come to do the switch.
  31    Add AC_PROG_LIBTOOL to your configure.ac then, in all the Makefile.am of
  32    your project, change *_LIBRARIES to *_LTLIBRARIES (notice the extra `LT')
  33    for each of your library that depends on Boost.  This way, Automake will
  34    delegate the build of your libraries to Libtool which will do the necessary
  35    magic so that you won't have to deal with LD_LIBRARY_PATH issues and so on.
  36    For programs however, you don't have anything special to do, Libtool will
  37    take care of them.
  38 4. Then, add a call to BOOST_REQUIRE to your configure.ac as well as other
  39    calls to the various BOOST_* macros that check for the libraries you need.
  40 5. Adjust your Makefile.am where you build targets that depend on Boost so
  41    that they use $(BOOST_CPPFLAGS), $(BOOST_*_LDFLAGS) and $(BOOST_*_LIBS)
  42    where appropriate (where `*' is the capitalized name of one of the
  43    libraries you checked for, e.g.: $(BOOST_THREADS_LDFLAGS)). E.g.:
  44       bin_PROGRAMS = foo
  45       foo_SOURCES = foo.cc
  46       foo_CPPFLAGS = $(BOOST_CPPFLAGS)
  47       foo_LDFLAGS = $(BOOST_THREAD_LDFLAGS)
  48       foo_LIBS = $(BOOST_THREAD_LIBS)
  49    Or if you have more than one target in the same Makefile.am and your
  50    targets don't have per-target specific flags (such as foo_LIBS) and you
  51    want all your targets to use the same set of Boost libraries, you can do
  52    the following instead:
  53       bin_PROGRAMS = foo bar
  54       foo_SOURCES = foo.cc
  55       bar_SOURCES = bar.cc
  56       AM_CPPFLAGS = $(BOOST_CPPFLAGS)
  57       AM_LDFLAGS = $(BOOST_THREADS_LDFLAGS)
  58       LIBS = $(BOOST_THREAD_LIBS)
  59    Remember that for targets that are programs, you must use LDADD or
  60    progname_LDADD, but for libraries you must use LIBS or libname_LIBS.
  61
  62 MACROS
  63 ------
  64 This section documents the various macros provided by boost.m4.
  65
  66   BOOST_REQUIRE([VERSION])
  67   ~~~~~~~~~~~~~~~~~~~~~~~~
  68 The first, most important macro, is BOOST_REQUIRE.  You should invoke it
  69 before other BOOST_* macros if you want to check that Boost has a minimum
  70 given version.
  71
  72 Here are some examples:
  73   # Do not require any specific minimum version
  74   BOOST_REQUIRE
  75   # Require at least 1.34.1
  76   BOOST_REQUIRE([1.34.1])
  77   # Require a version number known at runtime
  78   BOOST_REQUIRE([$some_shell_variable])
  79
  80 This macro defines the Make symbol BOOST_CPPFLAGS.
  81
  82
  83 There are various predefined macros to check for common Boost libraries.
  84 They are ordered in two categories: the Boost libraries that are only made of
  85 headers, and the Boost libraries that (may) require linking to an installed
  86 library.
  87
  88   Header-only Boost libraries
  89   ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  90 For each of the Boost libraries that are only made of headers, the macro to
  91 invoke is BOOST_<LIB-NAME> where <LIB-NAME> is the capitalized name of the
  92 library.  Here is the list of libraries for which checks have been
  93 implemented:
  94     - Asio
  95     - Bind
  96     - Conversion
  97     - Foreach
  98     - Format
  99     - Function
 100     - Hash (aka Functional/Hash)
 101     - Lambda
 102     - Preprocessor
 103     - Utility
 104     - Ref
 105     - SmartPtr
 106     - StringAlgo
 107     - Tokenizer
 108     - Tribool
 109     - Tuple
 110     - Variant
 111     - Xpressive
 112 Thus you can invoke BOOST_FOREACH (for instance).  It will check that
 113 <boost/foreach.hpp> works and define the preprocessor symbol
 114 HAVE_BOOST_FOREACH_HPP.  For each of the libraries mentioned above, a couple
 115 of headers are checked (the most important ones) and preprocessor symbols are
 116 defined in an identical fashion.
 117 If the check fails, configure with abort with a fatal error.
 118
 119   Boost libraries requiring linking
 120   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 121 For the other Boost libraries that (may) requiring linking to an installed
 122 library (shared or not), the macro to invoke is BOOST_<LIB-NAME> (surprise!)
 123 but this time the macro can take an optional argument to specify the runtime
 124 options you'd like to have.  Most of the time, Boost libraries are compiled
 125 in several flavors, such as with or without debug, with a multi-thread
 126 runtime or not, etc.  The macro will try to find a library that matches your
 127 requirements but may fall back to another flavor of the library if the one you
 128 asked for isn't available.
 129 The following libraries are supported:
 130   - Date_Time
 131   - Filesystem
 132   - Graph
 133   - IOStreams
 134   - Program_options
 135   - Regex
 136   - Serialization
 137   - Signals
 138   - System
 139   - Test (aka Unit Test Framework)
 140   - Threads
 141   - Wave
 142 Thus you can invoke BOOST_GRAPH (for instance) or BOOST_THREADS([mt-d]).
 143 The optional argument is made of one or more of the following letters:
 144   sgdpn (in that order)
 145 where:
 146   s = static runtime
 147   d = debug build
 148   g = debug/diagnostic runtime
 149   p = STLPort build
 150   n = (unsure) STLPort build without iostreams from STLPort
 151       (it looks like `n' must always be used along with `p').
 152 Additionally, it can start with `mt-' to indicate that there is a preference
 153 for multi-thread builds.
 154
 155 If the check is successful, at least one header has been checked and the
 156 corresponding preprocessor symbol HAVE_BOOST_*_HPP is defined, along with the
 157 compilation flags BOOST_<LIB-NAME>_LDFLAGS and BOOST_<LIB-NAME>_LIBS.
 158
 159 Small pitfall: BOOST_TEST generates BOOST_UNIT_TEST_FRAMEWORK_LDFLAGS and
 160 BOOST_UNIT_TEST_FRAMEWORK_LIBS, not BOOST_TEST_LFDLAGS and BOOST_TEST_LIBS.
 161 Sorry for the inconsistency.
 162
 163 NOTE: If you intend to use Wave/Spirit with thread support, make sure you
 164 call BOOST_THREADS first.
 165
 166   Writing your own checks / supporting more Boost libraries
 167   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 168 All the pre-existing library checks are written with help of
 169 BOOST_FIND_HEADER and BOOST_FIND_LIB.  These two macros are very easy to use
 170 and are documented in boost.m4.  Reading their documentation and reading the
 171 existing library checks should help you to easily write your own additional
 172 checks.  Please contribute them to me by email to <tsuna at lrde.epita.fr>.
 173
 174 You can checkout the Git source tree of this package at
 175 http://repo.or.cz/w/boost.m4.git
 176 Or simply download the latest version:
 177   wget 'http://repo.or.cz/w/boost.m4.git?a=blob_plain;f=build-aux/boost.m4;hb=HEAD' -O boost.m4
 178 Patches welcome.
 179
 180 LICENSE
 181 -------
 182
 183 The code of boost.m4 is released under GPLv3+ with the following additional
 184 clause:
 185
 186  Additional permission under section 7 of the GNU General Public
 187  License, version 3 ("GPLv3"):
 188
 189  If you convey this file as part of a work that contains a
 190  configuration script generated by Autoconf, you may do so under
 191  terms of your choice.
 192
 193 This clause has been written by FSF lawyers for Autotools.  If you have any
 194 concerns about legal issues, do not contact me as I Am Not A Lawyer.  I
 195 *think* you can get advices at <copyright-clerk at fsf dot org>.  The intent
 196 here is to keep the code Free but to allow anyone to *use* it.