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