boost/build
2
0
Fork 0
mirror of https://github.com/boostorg/build.git synced 2026-02-16 01:12:13 +00:00
Code Issues Projects Releases Wiki Activity

Further quickbookization of the wiki

Browse Source 
[SVN r50959]
This commit is contained in:
Troy D. Straszheim
2009-02-01 21:29:46 +00:00
parent 4884de06a2
commit 853fbfe45b
1 changed files with 379 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

383
CMake/doc/cmake.qbk
View File

@@ -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]