Backport lots of new features from the 1.41.0 branch.
[boost:cmake.git] / tools / build / CMake / docs / build / html / _sources / add_compiled_library.txt
1 .. _add_compiled_library:
2
3 Adding a Compiled Library to CMake
4 ==================================
5
6 This page describes how to add a new, compiled library to the
7 CMake-based build system. If your library is a "header-only" library,
8 and does not require separate compilation of object files into a
9 library binary, you can safely skip this step. Before adding compiled
10 libraries to CMake, make sure you have already followed the directions
11 for :ref:`boost_library_project_macro`, so that the CMake system recognizes your
12 Boost library.
13
14 We will assume that your library resides in the subdirectory
15 ``libs/libname``, and that we want to create the compiled library
16 ``boost_libname``. We will also assume that the sources for this
17 library reside in the subdirectory ``libs/libname/src``. The source
18 directory should be listed via ``SRCDIRS`` in the use of the
19 :ref:`boost_library_project_macro` macro, as described in the previous
20 section. Follow these steps to add this new
21 library into Boost's build system. If your library has multiple source
22 directories listed after ``SRCDIRS``, follow these steps for each one.
23
24 1. Create a new file ``libs/libname/src/CMakeLists.txt`` with your
25    favorite text editor. This file will contain build rules for your
26    compiled library. In this file, we will create one or more
27    invocations of the :ref:`boost_add_library_macro` macro, which adds a
28    compiled Boost library to the CMake system. This macro provides the
29    name of the library, the source files from which the library will
30    be built, and any specific compiler and linker options needed to
31    help build the library. Let's start by adding a simple library with
32    a few source files::
33
34      boost_add_library(boost_libname
35         mysrc1.cpp mysrc2.cpp
36         )
37
38    This invocation will build several variants of the
39    ``boost_libname`` library from the source files ``mysrc1.cpp`` and
40    ``mysrc2.cpp``. For example, it will build both static and shared
41    library, single- and multi-threaded, debug and release, etc. This
42    invocation also handles the installation of these libraries.
43
44 2. For simple libraries, that's it! Rebuilding via CMake (e.g.,
45    running ``make`` or reloading and rebuilding the Boost project in
46    your IDE) will build the new library, including several different
47    variants for different compilation options. Your Boost library will
48    also be included when the user installs Boost or builds a binary
49    package of Boost. Within the CMake configuration, you will also see
50    an option ``BUILD_LIBNAME``, which allows the user to decide
51    whether or not to build this Boost library.
52
53 3. Many libraries will need specific compilation options when
54    building, need to link against other libraries (Boost or
55    otherwise), or rely on certain features of the compilation process
56    to proceed. Follow the instructions in the remaining part of this
57    page to address these library-specific needs.
58
59
60 Compilation Flags
61 -----------------
62
63 Many libraries require certain compilation flags when we are building
64 the library binaries themselves (rather than when the library headers
65 are included by the user). For example, we want to define the macro
66 ``BUILDING_BOOST_LIBNAME`` when building the library. We can do so by
67 passing the ``COMPILE_FLAGS`` option to ``boost_add_library``::
68
69   boost_add_library(boost_libname
70       mysrc1.cpp mysrc2.cpp
71       COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1"
72       )
73
74 Now when CMake builds the library, it will pass the flag
75 ``-DBUILDING_BOOST_LIBNAME=1`` to the compiler.
76
77 On Windows, shared libraries are built very differently from static
78 libraries. In particular, when building a shared library, one needs to
79 be sure to export the right symbols from the DLL using
80 ``dllexport``. When users use the shared library, these symbols will be
81 imported (via ``dllimport``). The typical way to handle this is to
82 define a macro (say, ``BOOST_LIBNAME_DYN_LINK``) when building the
83 shared library. This macro instructs the library headers to
84 ``dllexport`` everything that needs to be exported. We can do this with
85 variant-specific compile flags, e.g., ::
86
87   boost_add_library(boost_libname
88       mysrc1.cpp mysrc2.cpp
89       COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1"
90       SHARED_COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1"
91       )
92  
93 When building a shared library, the ``SHARED_COMPILE_FLAGS`` options
94 will be combined with the ``COMPILE_FLAGS`` options. When building a
95 static library, the ``SHARED_COMPILE_FLAGS`` options will be
96 ignored. There are other options that can be specified per-feature,
97 such as ``LINK_FLAGS`` and ``LINK_LIBS``; refer to the
98 [wiki:CMakeAddLibrary boost_add_library macro reference] for more
99 information.
100
101 Linking to Other Boost Libraries
102 --------------------------------
103
104 Some Boost libraries depends on other Boost libraries. For example,
105 perhaps our library uses the Boost.Filesystem library under the
106 hood. We can use the ``DEPENDS`` feature of the [wiki:CMakeAddLibrary
107 boost_add_library macro] to state which libraries our library depends
108 on. In this example, we'll link against ``boost_filesystem``::
109
110   
111   boost_add_library(boost_libname
112       mysrc1.cpp mysrc2.cpp
113       COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1"
114       SHARED_COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1"
115       DEPENDS boost_filesystem
116       )
117
118 Now, each variant of the ``boost_libname`` library will link against
119 the appropriate ``boost_filesystem`` library variant. Whenever
120 ``boost_filesystem`` changes, our library will be relinked
121 appropriately.
122
123 Linking External Libraries/Optional Sources
124 -------------------------------------------
125
126 Sometimes, Boost libraries need to link against other libraries
127 supplied by the system. The primary challenge in linking against these
128 libraries is *finding* those libraries, and their associated headers,
129 on the system. If the library is found, we usually want to pass some
130 extra compilation flags to our library and add in additional
131 sources. Otherwise, we just skip these extra sources.
132
133 CMake already contains modules that search for many common system
134 libraries and tools; search the
135 [http://www.cmake.org/HTML/Documentation.html CMake Documentation] for
136 existing modules that do what you need. For example, say we want to
137 link against the system's ``PNG`` (portable network graphics) library.
138 We can use the supplied ``FindPNG`` module by adding the following
139 early in our ``CMakeLists.txt`` file: ::
140
141   include(FindPNG)
142
143 Documentation for CMake modules is typically found in the module file
144 itself. Look into the ``Modules`` subdirectory of your CMake
145 installation, either in ``Program Files\CMake`` (on Windows) or
146 ``/usr/share/cmake-version`` (on Unix variants) to find the module of
147 the same name. The module will typically set a variable that indicates
148 whether the library was found. For the ``FindPNG`` module, this variable
149 is called ``PNG_FOUND``. We can use this variable to optionally add
150 sources to a variable ``EXTRA_SOURCES``::
151
152   include(FindPNG)
153   set(EXTRA_SOURCES)
154   if (PNG_FOUND)
155     list(APPEND EXTRA_SOURCES png.cpp)
156   endif (PNG_FOUND)
157
158
159 CMake modules also typically define macros specifying the include
160 directories needed for the library, any compile-time definitions
161 required to use the library, and linking information for the library
162 binary. For the ``FindPNG`` module, these variables are called
163 ``PNG_INCLUDE_DIR``, ``PNG_DEFINITIONS`` and ``PNG_LIBRARY``, respectively.
164
165 The include directory should be added via the CMake
166 ``include_directories`` macro, e.g., ::
167
168   include_directories(${PNG_INCLUDE_DIR})
169
170 The ``PNG_DEFINITIONS`` value should be added to the ``COMPILE_FLAGS``
171 and the ``PNG_LIBRARIES`` value to the ``LINK_LIBS`` option to the
172 [wiki:CMakeAddLibrary boost_add_library macro]. Using these features
173 together, we can search for the ``PNG`` library on the system and
174 optionally include PNG support into our library::
175
176   include(FindPNG)
177   set(EXTRA_SOURCES)
178   if (PNG_FOUND)
179     include_directories(${PNG_PNG_INCLUDE_DIR})
180     list(APPEND EXTRA_SOURCES png.cpp)
181   endif (PNG_FOUND)
182   
183   boost_add_library(boost_libname
184     mysrc1.cpp mysrc2.cpp
185     ${EXTRA_SOURCES}
186     COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1 ${PNG_DEFINITIONS}"
187     LINK_LIBS "${PNG_LIBRARIES}"
188     SHARED_COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1"
189     DEPENDS boost_filesystem
190     )
191
192 If CMake does not provide a module to search for the library you need,
193 don't worry! You can write your own module relatively easily,
194 following the examples from the CMake ``Modules`` directory or some of
195 the Boost-specific examples, such as
196 http://svn.boost.org/svn/boost/branches/release/tools/build/CMake/FindICU.cmake
197 For a real-life example of finding system libraries and using that
198 information to add optional, extra capabilities to a Boost library,
199 check out the build rules for the Boost.IOStreams library at
200 http://svn.boost.org/svn/boost/branches/release/libs/iostreams/src/CMakeLists.txt
201
202 .. index:: Variants
203
204 Build Variants
205 --------------
206
207 The Boost build system defines many different :ref:`VARIANTS`, which
208 describe specific properties of certain builds. For example, the
209 ``SHARED`` feature indicates that we are building a shared library,
210 while the ``MULTI_THREADED`` feature indicates that we are building a
211 multi-threaded library. A specific set of features is called a
212 ``````variant``````, e.g., ``RELEASE`` and ``MULTI_THREADED`` and
213 ``SHARED``. By default, the CMake-based build system builds several
214 different variants of each Boost library.
215
216 Since some features conflict with certain libraries (a threading
217 library cannot be ``SINGLE_THREADED``!), one can pass additional flags
218 to :ref:`boost_add_library_macro` stating which features should the library
219 cannot be built with.  For example, say that our library cannot be
220 built as a multi-threaded library, because it uses thread-unsafe
221 routines from the underlying C library. To disable multi-threaded
222 variants of the library, pass the option ``NOT_MULTI_THREADED``::
223
224   boost_add_library(boost_libname
225       mysrc1.cpp mysrc2.cpp
226       COMPILE_FLAGS "-DBUILDING_BOOST_LIBNAME=1"
227       SHARED_COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1"
228       DEPENDS boost_filesystem
229       NOT_MULTI_THREADED
230       )
231