[Boost-commit] svn:boost r50959 - trunk/tools/build/CMake/doc

Subject: [Boost-commit] svn:boost r50959 - trunk/tools/build/CMake/doc
From: troy_at_[hidden]
Date: 2009-02-01 16:29:47

Author: troy
Date: 2009-02-01 16:29:46 EST (Sun, 01 Feb 2009)
New Revision: 50959
URL: http://svn.boost.org/trac/boost/changeset/50959

Log:

Further quickbookization of the wiki

Text files modified: 
   trunk/tools/build/CMake/doc/cmake.qbk |   383 +++++++++++++++++++++++++++++++++++++++ 
   1 files changed, 379 insertions(+), 4 deletions(-)

Modified: trunk/tools/build/CMake/doc/cmake.qbk
==============================================================================
--- trunk/tools/build/CMake/doc/cmake.qbk	(original)
+++ trunk/tools/build/CMake/doc/cmake.qbk	2009-02-01 16:29:46 EST (Sun, 01 Feb 2009)
@@ -42,7 +42,7 @@
 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 @@
 * 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 @@
  [[=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 @@
 
 [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]