1 ,-------------------------------------------------.
3 | | __ ) ___ ___ ___| |_ _ __ ___ | || | |
4 | | _ \ / _ \ / _ \/ __| __| | '_ ` _ \| || |_ |
5 | | |_) | (_) | (_) \__ \ |_ _| | | | | |__ _| |
6 | |____/ \___/ \___/|___/\__(_)_| |_| |_| |_| |
8 `-------------------------------------------------'
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.
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
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
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.:
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
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 LIBS or
60 progname_LIBS, but for libraries you must use LDADD or libname_LDADD.
64 This section documents the various macros provided by boost.m4.
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
72 Here are some examples:
73 # Do not require any specific minimum version
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])
80 This macro defines the Make symbol BOOST_CPPFLAGS.
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
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
103 Thus you can invoke BOOST_FOREACH (for instance). It will check that
104 <boost/foreach.hpp> works and define the preprocessor symbol
105 HAVE_BOOST_FOREACH_HPP. For each of the libraries mentioned above, a couple
106 of headers are checked (the most important ones) and preprocessor symbols are
107 defined in an identical fashion.
108 If the check fails, configure with abort with a fatal error.
110 Boost libraries requiring linking
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112 For the other Boost libraries that (may) requiring linking to an installed
113 library (shared or not), the macro to invoke is BOOST_<LIB-NAME> (surprise!)
114 but this time the macro can take an optional argument to specify the runtime
115 options you'd like to have. Most of the time, Boost libraries are compiled
116 in several flavors, such as with or without debug, with a multi-thread
117 runtime or not, etc. The macro will try to find a library that match your
118 requirements but may fall back to another flavor of the library if the one you
119 asked for isn't available.
120 The following libraries are supported:
125 Thus you can invoke BOOST_GRAPH (for instance) or BOOST_THREADS([mt-d]).
126 The optional argument is made of one or more of the following letters:
127 sgdpn (in that order)
131 g = debug/diagnostic runtime
133 n = (unsure) STLPort build without iostreams from STLPort
134 (it looks like `n' must always be used along with `p').
135 Additionally, it can start with `mt-' to indicate that there is a preference
136 for multi-thread builds.
138 If the check is successful, at least one header has been checked and the
139 corresponding preprocessor symbol HAVE_BOOST_*_HPP is defined, along with the
140 compilation flags BOOST_<LIB-NAME>_LDFLAGS and BOOST_<LIB-NAME>_LIBS.
142 Writing your own checks / supporting more Boost libraries
143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
144 All the pre-existing library checks are written with help of
145 BOOST_FIND_HEADER and BOOST_FIND_LIB. These two macros are very easy to use
146 and are documented in boost.m4. Reading their documentation and reading the
147 existing library checks should help you to easily write your own additional
148 checks. Please contribute them to me by email to <tsuna at lrde.epita.fr>.
150 You can checkout the Git source tree of this package at
151 http://repo.or.cz/w/boost.m4.git
152 Or simply download the latest version:
153 wget 'http://repo.or.cz/w/boost.m4.git?a=blob_plain;f=build-aux/boost.m4;hb=HEAD' -O boost.m4