From 853fbfe45b954234aa69b8beedeeb156b3c45c3e Mon Sep 17 00:00:00 2001 From: "Troy D. Straszheim" Date: Sun, 1 Feb 2009 21:29:46 +0000 Subject: [PATCH] Further quickbookization of the wiki [SVN r50959] --- CMake/doc/cmake.qbk | 383 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 379 insertions(+), 4 deletions(-) diff --git a/CMake/doc/cmake.qbk b/CMake/doc/cmake.qbk index 9ce0cdf8e..49230981d 100644 --- a/CMake/doc/cmake.qbk +++ b/CMake/doc/cmake.qbk @@ -42,7 +42,7 @@ Note that it is *not* necessary to set any environment variable =BOOST=, this is a convention used in this document. [section Check out Boost-CMake] -To get a copy of Boost with the CMake build system, retrieve it from the [wiki:BoostSubversion Boost Subversion repository] with the URL http://svn.boost.org/svn/boost/trunk]. +To get a copy of Boost with the CMake build system, retrieve it from the [@http://needlink Boost Subversion repository] with the URL http://svn.boost.org/svn/boost/trunk]. On unix: [pre @@ -79,7 +79,7 @@ Run CMake by selecting it from the Start menu. * Click ''Configure'' a first time to configure Boost, which will search for various libraries on your system and prepare the build. * You will then be given the opportunity to tune build options in - the CMake GUI (see also [wiki:CMakeBuildConfiguration]. These + the CMake GUI (see also [@http://needlink CMakeBuildConfiguration]. These options will affect what libraries are built and how. They will initially appear red. Click ''Configure'' again when you are done editing them. @@ -291,10 +291,10 @@ More detail on some of these options is available elsewhere. But here is a summ [[=BUILD_VERSIONED=] [Toggles mangling of compiler name and boost version into library names]] [[=BUILD_TESTING= ] [Toggles build of testing]] [[[^ BUILD\_BOOST\_]/library/][Toggles building and testing of [~ library] (e.g. this will appear as [^ BUILD_BOOST_REGEX], [^ BUILD_BOOST_PROGRAM_OPTIONS], etc.)]] - [[=BUILD_=/feature/] [Toggles build of feature /feature/, where /feature/ comes from the list found at *FIXME*, + [[=BUILD_=/feature/] [Toggles build of feature /feature/, where /feature/ comes from the list found at *needlink*, e.g. [^BUILD_RELEASE], [^BUILD_DEBUG], [^BUILD_MULTI_THREADED], etc.]] - [[=TEST_BOOST_=/library/][Toggles testing of /library/ (this option appears only if [^ BUILD_BOOST_]/library/ and [^ BUILD_TESTING] are enabled. See *FIXME*)]] + [[=TEST_BOOST_=/library/][Toggles testing of /library/ (this option appears only if [^ BUILD_BOOST_]/library/ and [^ BUILD_TESTING] are enabled. See *needlink*)]] [[[^ CMAKE_OSX_ARCHITECTURES]][ /Mac OS X users/: to build universal binaries, set this to [^ ppc;i386].]] ] @@ -309,6 +309,381 @@ More detail on some of these options is available elsewhere. But here is a summ [endsect] [endsect] +[endsect] +[section Building individual libraries with cmake] +In a configured cmake workspace, `make help` will display a list of available targets. Example: +[pre +% make help +The following are some of the valid targets for this Makefile: +... all (the default if no target is provided) +... clean +... depend +... edit_cache +... install +... install/local +... install/strip +... list_install_components +... package +... package_source +... rebuild_cache +... boost_date_time +... boost_date_time-mt-shared +... boost_date_time-mt-shared-debug +... boost_date_time-mt-static +... boost_date_time-mt-static-debug +... boost_date_time-shared +... boost_date_time-shared-debug +... boost_date_time-static +... boost_date_time-static-debug +... boost_filesystem +... boost_filesystem-mt-shared +... boost_filesystem-mt-shared-debug +... boost_filesystem-mt-static +... boost_filesystem-mt-static-debug +... boost_filesystem-shared +... boost_filesystem-shared-debug +... boost_filesystem-static +... boost_filesystem-static-debug +[etc\] +] + +You can build any target by passing it as an argument: + +[pre +% make boost_signals-static +[ 0%\] Building CXX object libs/signals/src/CMakeFiles/boost_signals-static.dir/trackable.cpp.o +[ 0%\] Building CXX object libs/signals/src/CMakeFiles/boost_signals-static.dir/connection.cpp.o +[100%\] Building CXX object libs/signals/src/CMakeFiles/boost_signals-static.dir/named_slot_map.cpp.o +[100%\] Building CXX object libs/signals/src/CMakeFiles/boost_signals-static.dir/signal_base.cpp.o +[100%\] Building CXX object libs/signals/src/CMakeFiles/boost_signals-static.dir/slot.cpp.o +Linking CXX static library ../../../lib/libboost_signals-gcc41-1_35.a +[100%\] Built target boost_signals-static +] + +[section Preprocessing] + +In build directories corresponding to a source library containing a =CMakeLists.txt= containing a +=boost_add_library= invocation (e.g. =build/libs/signals/src=, =build/libs/filesystem/src=), +more detailed targets are available: +[pre +% cd libs/signals/src +% make help +The following are some of the valid targets for this Makefile: + ['(many omitted)] +... signal_base.o +... signal_base.i +... signal_base.s +... slot.o +... slot.i +... slot.s +] + +making [^ slot.i] will run [^ slot.cpp] through the preprocessor: +[pre +% make slot.i +Preprocessing CXX source to CMakeFiles/boost_signals-mt-shared.dir/slot.cpp.i +] +If you are always interested in seeing the compiler flags you can enable [^ CMAKE_VERBOSE_MAKEFILES] via [^ ccmake] +, or for a one-off just pass [^ VERBOSE=1] on the command line: +[pre +% make VERBOSE=1 slot.i +make[1\]: Entering directory `/home/troy/Projects/boost/branches/CMake/Boost_1_35_0-build' +Preprocessing CXX source to CMakeFiles/boost_signals-mt-shared.dir/slot.cpp.i +cd /home/troy/Projects/boost/branches/CMake/Boost_1_35_0-build/libs/signals/src && /usr/bin/gcc-4.1 +-DBOOST_ALL_NO_LIB=1 -DBOOST_SIGNALS_NO_LIB=1 -Dboost_signals_mt_shared_EXPORTS -fPIC +-I/home/troy/Projects/boost/branches/CMake/Boost_1_35_0 -O3 -DNDEBUG -DBOOST_SIGNALS_DYN_LINK=1 +-pthread -D_REENTRANT -E /home/troy/Projects/boost/branches/CMake/Boost_1_35_0/libs/signals/src/slot.cpp > CMakeFiles/boost_signals-mt-shared.dir/slot.cpp.i +] + +[endsect] + +[endsect] + +[section Adding a Boost Library with CMake] + +This page describes how to introduce a new Boost library into the +CMake-based build system. Any Boost library that provides a library +binary (e.g., [^ boost_signals.dll]) or has regression tests (hopefully, +every Boost library!) will need to be part of the build system. + +To introduce a new library, which resides in the subdirectory [^ libs/libname], follow these steps: + +Create a new file [^ libs/libname/CMakeLists.txt] with your favorite +text editor. This file will contain an invocation of the +[^ boost_library_project] macro, which +identifies each Boost library to the build system. The invocation of +the [^ boost_library_project] will look like this: + +[pre + boost_library_project( + Libname + SRCDIRS src + TESTDIRS test + ) +] + +where [^ Libname] is the properly-capitalization library name, e.g., +[^ Signals] or [^ Smart_ptr]. The [^ SRCDIRS src] line should only +be present if your Boost library actually needs to compile a library +binary; header-only libraries can skip this step. The [^ TESTDIRS +test] line indicates that the subdirectory [^ test] contains +regression tests for your library. Every Boost library should have +these. + +Re-run CMake to reconfigure the source tree, causing CMake to find +the new Boost library. CMake can be re-run either from the command +line (by invoking [^ cmake /path/to/boost] or [^ ccmake /path/to/boost]) +or, on Windows, using the CMake GUI. Once you have reconfigured and +generated new makefiles or project files, CMake knows about your +library. + +If your library has compiled sources (i.e., it is not a header-only +library), follow the instructions on adding a compiled library to +get CMake building and installing your library. + +If your library has regression tests (it ['does] have regression +tests, right?), follow the instructions on adding regression tests +to get CMake to build and run regression tests for your library. + +[endsect] + +[section Adding a Compiled Library to CMake] + +This page describes how to add a new, compiled library to the +CMake-based build system. If your library is a "header-only" library, +and does not require separate compilation of object files into a +library binary, you can safely skip this step. Before adding compiled +libraries to CMake, make sure you have already followed the directions +for *needlink* adding a library to CMake, so that the +CMake system recognizes your Boost library. + +In this page, we will assume that your library resides in the +subdirectory `libs/libname`, and that we want to create the compiled +library `boost_libname`. We will also assume that the sources for this +library reside in the subdirectory `libs/libname/src`. The source +directory should be listed via `SRCDIRS` in the use of the +[@http://needlink boost_library_project macro], as described +in the previous section, [@http://needlink "Adding a Library +to CMake"]. Follow these steps to add this new library into Boost's +build system. If your library has multiple source directories listed +after `SRCDIRS`, follow these steps for each one. + +Create a new file `libs/libname/src/CMakeLists.txt` with your +favorite text editor. This file will contain build rules for your +compiled library. In this file, we will create one or more invocations +of the [@http://needlink boost_add_library macro], which adds a +compiled Boost library to the CMake system. The `boost_add_library` +macro provides the name of the library, the source files from which +the library will be built, and any specific compiler and linker +options needed to help build the library. Let's start by adding a +simple library with a few source files: + +[pre + boost_add_library(boost_libname + mysrc1.cpp mysrc2.cpp + ) +] + +This invocation will build several variants of the =boost_libname= +library from the source files [^ mysrc1.cpp] and [^ mysrc2.cpp]. For +example, it will build both static and shared library, single- and +multi-threaded, debug and release, etc. This invocation also handles +the installation of these libraries. + +For simple libraries, that's it! Rebuilding via CMake (e.g., running +`make` or reloading and rebuilding the Boost project in your IDE) will +build the new library, including several different variants for +different compilation options. Your Boost library will also be +included when the user installs Boost or builds a binary package of +Boost. Within the CMake configuration, you will also see an option +`BUILD_LIBNAME`, which allows the user to decide whether or not to +build this Boost library. + +Many libraries will need specific compilation options when building, +need to link against other libraries (Boost or otherwise), or rely on +certain features of the compilation process to proceed. Follow the +instructions in the remaining part of this page to address these +library-specific needs. + +[section Compilation Flags] + +Many libraries require certain compilation flags when we are building +the library binaries themselves (rather than when the library headers +are included by the user). For example, we want to define the macro +"BUILDING_BOOST_LIBNAME" when building the library. We can do so by +passing the `COMPILE_FLAGS` option to `boost_add_library`: +[pre +boost_add_library(boost_libname + mysrc1.cpp mysrc2.cpp + COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1" +] +Now when CMake builds the library, it will pass the flag `-DBUILDING_BOOST_LIBNAME=1` to the compiler. + +On Windows, shared libraries are built very differently from static +libraries. In particular, when building a shared library, one needs to +be sure to export the right symbols from the DLL using +`dllexport`. When users use the shared library, these symbols will be +imported (via `dllimport`). The typical way to handle this is to +define a macro (say, `BOOST_LIBNAME_DYN_LINK`) when building the +shared library. This macro instructs the library headers to +`dllexport` everything that needs to be exported. We can do this with +variant-specific compile flags, e.g., + +[pre +boost_add_library(boost_libname + mysrc1.cpp mysrc2.cpp + COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1" + SHARED_COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1" +] + + +When building a shared library, the `SHARED_COMPILE_FLAGS` options +will be combined with the `COMPILE_FLAGS` options. When building a +static library, the `SHARED_COMPILE_FLAGS` options will be +ignored. There are other options that can be specified per-feature, +such as `LINK_FLAGS` and `LINK_LIBS`; refer to the +[@http://needlink boost_add_library macro reference] for more +information. +[endsect] + +[section Linking to Other Boost Libraries] + +Some Boost libraries depends on other Boost libraries. For example, +perhaps our library uses the Boost.Filesystem library under the +hood. We can use the `DEPENDS` feature of the [@http://needlink +boost_add_library macro] to state which libraries our library depends +on. In this example, we'll link against `boost_filesystem`: + +[pre +boost_add_library(boost_libname + mysrc1.cpp mysrc2.cpp + COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1" + SHARED_COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1" + DEPENDS boost_filesystem +] + +Now, each variant of the `boost_libname` library will link against the +appropriate `boost_filesystem` library variant. Whenever +`boost_filesystem` changes, our library will be relinked +appropriately. + +[endsect] + +[section Linking External Libraries/Optional Sources] + +Sometimes, Boost libraries need to link against other libraries +supplied by the system. The primary challenge in linking against these +libraries is /finding/ those libraries, and their associated +headers, on the system. If the library is found, we usually want to +pass some extra compilation flags to our library and add in additional +sources. Otherwise, we just skip these extra sources. + +CMake already contains modules that search for many common system +libraries and tools; search the +[@http://www.cmake.org/HTML/Documentation.html CMake Documentation] for +existing modules that do what you need. For example, say we want to +link against the system's `PNG` (portable network graphics) library. +We can use the supplied `FindPNG` module by adding the following early +in our `CMakeLists.txt` file: + +[pre +include(FindPNG) +] + +Documentation for CMake modules is typically found in the module file +itself. Look into the `Modules` subdirectory of your CMake +installation, either in `Program Files\CMake` (on Windows) or +`/usr/share/cmake-version` (on Unix variants) to find the module of +the same name. The module will typically set a variable that indicates +whether the library was found. For the `FindPNG` module, this variable +is called `PNG_FOUND`. We can use this variable to optionally add +sources to a variable `EXTRA_SOURCES`: + +[pre +include(FindPNG) +set(EXTRA_SOURCES) +if (PNG_FOUND) + list(APPEND EXTRA_SOURCES png.cpp) +endif (PNG_FOUND) +] + +CMake modules also typically define macros specifying the include +directories needed for the library, any compile-time definitions +required to use the library, and linking information for the library +binary. For the `FindPNG` module, these variables are called +`PNG_INCLUDE_DIR`, `PNG_DEFINITIONS` and `PNG_LIBRARY`, respectively. + +The include directory should be added via the CMake `include_directories` macro, e.g., + +[pre +include_directories(${PNG_INCLUDE_DIR}) +] + +The `PNG_DEFINITIONS` value should be added to the `COMPILE_FLAGS` and +the `PNG_LIBRARIES` value to the `LINK_LIBS` option to the +[@http://needlink boost_add_library macro]. Using these features +together, we can search for the `PNG` library on the system and +optionally include PNG support into our library: + +[pre +include(FindPNG) +set(EXTRA_SOURCES) +if (PNG_FOUND) + include_directories(${PNG_PNG_INCLUDE_DIR}) + list(APPEND EXTRA_SOURCES png.cpp) +endif (PNG_FOUND) + +boost_add_library(boost_libname + mysrc1.cpp mysrc2.cpp + ${EXTRA_SOURCES} + COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1 ${PNG_DEFINITIONS}" + LINK_LIBS "${PNG_LIBRARIES}" + SHARED_COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1" + DEPENDS boost_filesystem +] + +If CMake does not provide a module to search for the library you need, +don't worry! You can write your own module relatively easily, +following the examples from the CMake `Modules` directory or some of +the Boost-specific examples, such as +[http://svn.boost.org/svn/boost/branches/CMake/Boost_1_35_0/tools/build/CMake/FindICU.cmake +tools/build/CMake/FindICU.cmake]. For a real-life example of finding +system libraries and using that information to add optional, extra +capabilities to a Boost library, check out the build rules for the +Boost.IOStreams library at +[http://svn.boost.org/svn/boost/branches/CMake/Boost_1_35_0/libs/iostreams/src/CMakeLists.txt +libs/iostreams/src/CMakeLists.txt]. + +[endsect] +[section Build Variants] + +The Boost build system defines many different [@http://needlink +build features], which describe specific properties of certain +builds. For example, the `SHARED` feature indicates that we are +building a shared library, while the `MULTI_THREADED` feature +indicates that we are building a multi-threaded library. A specific +set of features is called a *variant*, e.g., `RELEASE` and +`MULTI_THREADED` and `SHARED`. By default, the CMake-based build +system builds several different variants of each Boost library. + +Since some features conflict with certain libraries (a threading +library cannot be `SINGLE_THREADED`!), one can pass additional flags +to [@http://needlink boost_add_library] stating which features +should the library cannot be built with. For example, say that our +library cannot be built as a multi-threaded library, because it uses +thread-unsafe routines from the underlying C library. To disable +multi-threaded variants of the library, pass the option +`NOT_MULTI_THREADED`: + +[pre +boost_add_library(boost_libname + mysrc1.cpp mysrc2.cpp + COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1" + SHARED_COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1" + DEPENDS boost_filesystem + NOT_MULTI_THREADED +] +[endsect] [endsect]