M4 macros to use Boost with the autotools
* build-aux/boost.m4 (_BOOST_PTHREAD_FLAG): Documentation changes. (BOOST_FLYWEIGHT): New.
|build-aux||boost.m4: introduce Boost.Flyweight check|
|tests||boost.m4: introduce Boost.Flyweight check|
|COPYING||Add the GPLv3+ license.|
|ChangeLog||Prioritize GCC 4.3 now that it has been released and add support for …|
|Makefile.am||Install boost.m4 into a place where it's useful.|
|NEWS||Add GPL license exception.|
|README||boost.m4: introduce Boost.Flyweight check|
|THANKS||Add support for Boost.Chrono.|
|configure.ac||Bump configure.ac to version 0.2 and show a better usage example.|
,-------------------------------------------------. | ____ _ _ _ | | | __ ) ___ ___ ___| |_ _ __ ___ | || | | | | _ \ / _ \ / _ \/ __| __| | '_ ` _ \| || |_ | | | |_) | (_) | (_) \__ \ |_ _| | | | | |__ _| | | |____/ \___/ \___/|___/\__(_)_| |_| |_| |_| | | | `-------------------------------------------------' This package provides a set of M4 macros to use with GNU Autoconf. The purpose of these macros is to be able to easily find and test the various Boost libraries of a given version for a given compiler. This package is released under GPLv3+. This macro requires that you use GNU Libtool and assumes that you already use GNU Automake. If you don't already use Libtool, the step 3 below explains how to set it up. HOWTO ----- 1. If you have an invocation of AC_CONFIG_AUX_DIR in your configure.ac, then copy build-aux/boost.m4 in the directory specified by AC_CONFIG_AUX_DIR. Otherwise, copy the file at the root of your project. 2. In your top-level Makefile.am (this supposes that you use automake, which you most likely do) add: ACLOCAL_AMFLAGS = -I <dir> where `<dir>' is the (relative) path to the directory where you copied boost.m4 (set it to `.' if you put boost.m4 in the same, top-level directory). 3. If you don't use GNU Libtool already, then time has come to do the switch. Add AC_PROG_LIBTOOL to your configure.ac then, in all the Makefile.am of your project, change *_LIBRARIES to *_LTLIBRARIES (notice the extra `LT') for each of your library that depends on Boost. This way, Automake will delegate the build of your libraries to Libtool which will do the necessary magic so that you won't have to deal with LD_LIBRARY_PATH issues and so on. For programs however, you don't have anything special to do, Libtool will take care of them. 4. Then, add a call to BOOST_REQUIRE to your configure.ac as well as other calls to the various BOOST_* macros that check for the libraries you need. 5. Adjust your Makefile.am where you build targets that depend on Boost so that they use $(BOOST_CPPFLAGS), $(BOOST_*_LDFLAGS) and $(BOOST_*_LIBS) where appropriate (where `*' is the capitalized name of one of the libraries you checked for, e.g.: $(BOOST_THREAD_LDFLAGS)). E.g.: bin_PROGRAMS = foo foo_SOURCES = foo.cc foo_CPPFLAGS = $(BOOST_CPPFLAGS) foo_LDFLAGS = $(BOOST_THREAD_LDFLAGS) foo_LIBS = $(BOOST_THREAD_LIBS) Or if you have more than one target in the same Makefile.am and your targets don't have per-target specific flags (such as foo_LIBS) and you want all your targets to use the same set of Boost libraries, you can do the following instead: bin_PROGRAMS = foo bar foo_SOURCES = foo.cc bar_SOURCES = bar.cc AM_CPPFLAGS = $(BOOST_CPPFLAGS) AM_LDFLAGS = $(BOOST_THREAD_LDFLAGS) LIBS = $(BOOST_THREAD_LIBS) Remember that for targets that are programs, you must use LDADD or progname_LDADD, but for libraries you must use LIBS or libname_LIBS. MACROS ------ This section documents the various macros provided by boost.m4. BOOST_REQUIRE([VERSION]) ~~~~~~~~~~~~~~~~~~~~~~~~ The first, most important macro, is BOOST_REQUIRE. You should invoke it before other BOOST_* macros if you want to check that Boost has a minimum given version. Here are some examples: # Do not require any specific minimum version BOOST_REQUIRE # Require at least 1.34.1 BOOST_REQUIRE([1.34.1]) # Require a version number known at runtime BOOST_REQUIRE([$some_shell_variable]) This macro defines the Make symbol BOOST_CPPFLAGS. There are various predefined macros to check for common Boost libraries. They are ordered in two categories: the Boost libraries that are only made of headers, and the Boost libraries that (may) require linking to an installed library. Header-only Boost libraries ~~~~~~~~~~~~~~~~~~~~~~~~~~~ For each of the Boost libraries that are only made of headers, the macro to invoke is BOOST_<LIB-NAME> where <LIB-NAME> is the capitalized name of the library. Here is the list of libraries for which checks have been implemented: - Array - Asio - Bind - Conversion - CRC - Flyweight (with a dependency on pthread) - Foreach - Format - Function - Geometry - Hash (aka Functional/Hash) - Lambda - Math - MultiArray - NumericConversion - Preprocessor - PointerContainer - Utility - Ref - Signals2 - SmartPtr - StringAlgo - Tokenizer - Tribool - Tuple - Variant - Xpressive Thus you can invoke BOOST_FOREACH (for instance). It will check that <boost/foreach.hpp> works and define the preprocessor symbol HAVE_BOOST_FOREACH_HPP. For each of the libraries mentioned above, a couple of headers are checked (the most important ones) and preprocessor symbols are defined in an identical fashion. If the check fails, configure with abort with a fatal error. Boost libraries requiring linking ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For the other Boost libraries that (may) requiring linking to an installed library (shared or not), the macro to invoke is BOOST_<LIB-NAME> (surprise!) but this time the macro can take an optional argument to specify the runtime options you'd like to have. Most of the time, Boost libraries are compiled in several flavors, such as with or without debug, with a multi-thread runtime or not, etc. The macro will try to find a library that matches your requirements but may fall back to another flavor of the library if the one you asked for isn't available. The following libraries are supported: - Chrono - Date_Time - Filesystem - Graph - IOStreams - Program_options - Regex - Serialization - Signals - System - Test (aka Unit Test Framework) - Thread - Wave Thus you can invoke BOOST_GRAPH (for instance) or BOOST_THREAD([mt-d]). The optional argument is made of one or more of the following letters: sgdpn (in that order) where: s = static runtime d = debug build g = debug/diagnostic runtime p = STLPort build n = (unsure) STLPort build without iostreams from STLPort (it looks like `n' must always be used along with `p'). Additionally, it can start with `mt-' to indicate that there is a preference for multi-thread builds. If the check is successful, at least one header has been checked and the corresponding preprocessor symbol HAVE_BOOST_*_HPP is defined, along with the compilation flags BOOST_<LIB-NAME>_LDFLAGS and BOOST_<LIB-NAME>_LIBS. Small pitfall: BOOST_TEST generates BOOST_UNIT_TEST_FRAMEWORK_LDFLAGS and BOOST_UNIT_TEST_FRAMEWORK_LIBS, not BOOST_TEST_LFDLAGS and BOOST_TEST_LIBS. Sorry for the inconsistency. NOTE: If you intend to use Wave/Spirit with thread support, make sure you call BOOST_THREAD first. Writing your own checks / supporting more Boost libraries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All the pre-existing library checks are written with help of BOOST_FIND_HEADER and BOOST_FIND_LIB. These two macros are very easy to use and are documented in boost.m4. Reading their documentation and reading the existing library checks should help you to easily write your own additional checks. Please contribute them to me by email to <tsuna at lrde.epita.fr>. You can checkout the Git source tree of this package at http://github.com/tsuna/boost.m4 Or simply download the latest version: wget http://github.com/tsuna/boost.m4/raw/master/build-aux/boost.m4 Patches welcome. LICENSE ------- The code of boost.m4 is released under GPLv3+ with the following additional clause: Additional permission under section 7 of the GNU General Public License, version 3 ("GPLv3"): If you convey this file as part of a work that contains a configuration script generated by Autoconf, you may do so under terms of your choice. This clause has been written by FSF lawyers for Autotools. If you have any concerns about legal issues, do not contact me as I Am Not A Lawyer. I *think* you can get advices at <copyright-clerk at fsf dot org>. The intent here is to keep the code Free but to allow anyone to *use* it.