Backport lots of new features from the 1.41.0 branch.
[boost:cmake.git] / tools / build / CMake / docs / build / html / _sources / exported_targets.txt
1 .. index:: targets, exported
2 .. index:: uninstalled tree, building against
3 .. _exported_targets:
4
5 Developing with Boost.CMake
6 ===========================
7
8 Boost.CMake *exports* its targets, making developing independent
9 projects against an installed boost, or simply against a build tree
10 sitting on disk.  There are a variety of ways to use these to ease
11 configuration of boost in your external project.
12
13 You only need to do three things:
14
15 1.  Add the appropriate include directory.  This is either
16     ``${``:ref:`CMAKE_INSTALL_PREFIX`\ ``}/include``, if installed, or the
17     toplevel of the boost source directory if not.
18
19 2.  ``include`` the generated ``Boost.cmake`` file containing the
20     exported targets.  In an installation, this file is in directory
21     ``${``:ref:`CMAKE_INSTALL_PREFIX`\ ``}/lib/cmake/Boost.cmake`` [#libsuffix]_, and
22     in a not-installed build tree it is located in
23     ``${``:ref:`CMAKE_BINARY_DIR`\ ``}/lib/cmake/Boost.cmake``
24 3.  Tell cmake about your link dependencies with
25     ``target_link_libraries``.  Note that you use the **names of the
26     cmake targets**, not the shorter names that the libraries have on
27     disk.   ``make help`` shows a list::
28
29        % make help | grep signals
30        ... boost_signals
31        ... boost_signals-mt-shared
32        ... boost_signals-mt-shared-debug
33        ... boost_signals-mt-static
34        ... boost_signals-mt-static-debug
35               
36     See also :ref:`fixme` for details on the naming conventions.
37
38
39 .. index:: Building against uninstalled boost
40 .. _uninstalled:
41
42 With an uninstalled build
43 ^^^^^^^^^^^^^^^^^^^^^^^^^
44
45 You only need to do three things:
46
47 1.  Add the appropriate include directory.  This is either
48     ``${``:ref:`CMAKE_INSTALL_PREFIX`\ ``}/include``, if installed, or the
49     toplevel of the boost source directory if not.
50
51 2.  ``include`` the generated ``Boost.cmake`` from the build tree
52     containing the exported targets.  I is located in
53     ``${``:ref:`CMAKE_BINARY_DIR`\ ``}/lib/cmake/Boost.cmake``
54
55 3.  Tell cmake about your link dependencies with
56     ``target_link_libraries``.  Note that you use the **names of the
57     cmake targets**, not the shorter names that the libraries have on
58     disk.   ``make help`` shows a list::
59
60        % make help | grep signals
61        ... boost_signals
62        ... boost_signals-mt-shared
63        ... boost_signals-mt-shared-debug
64        ... boost_signals-mt-static
65        ... boost_signals-mt-static-debug
66               
67     See also :ref:`fixme` for details on the naming conventions.
68
69 Since these are exported targets, CMake will add appropriate *rpaths*
70 as necessary; fiddling with ``LD_LIBRARY_PATH`` should not be
71 necessary.
72
73 Example
74 -------
75
76 There is an unpacked boost in ``/home/troy/boost-1.41.0/src`` and
77 built boost in directory ``/home/troy/boost/1.41.0/build``. I have a
78 program that builds from one file, ``main.cpp`` and uses boost
79 threads.  My ``CMakeLists.txt`` looks like this::
80
81    include_directories("/home/troy/boost-1.41.0/src")
82    include("/home/troy/boost-1.41.0/build/lib/cmake/Boost.cmake")
83
84    add_executable(my_program main.cpp)
85    target_link_libraries(my_program boost_thread-mt-shared-debug)
86
87 When I build, I see
88 (wrapped, and some output replaced with ... for brevity)::
89
90   % make VERBOSE=1
91   ...
92   [100%] Building CXX object CMakeFiles/main.dir/main.cpp.o
93   /usr/bin/c++ -I/home/troy/boost-1.41.0/src -o CMakeFiles/main.dir/main.cpp.o -c /home/troy/myproject/main.cpp
94   ...
95   linking CXX executable main
96   /usr/bin/c++ -fPIC CMakeFiles/main.dir/main.cpp.o -o main -rdynamic /home/troy/boost-1.41.0/build/lib/libboost_thread-mt-d.so.1.41.0 -lpthread -lrt -Wl,-rpath,/home/troy/boost-1.41.0/build/lib 
97   ...
98   [100%] Built target main
99
100 With an installed boost
101 ^^^^^^^^^^^^^^^^^^^^^^^
102
103 There is an easy way, and a hard way, depending on your your boost was
104 installed.  
105
106 The Easy Way
107 ------------
108
109 If your boost was installed with
110 :ref:`BOOST_INSTALL_FINDBOOST_CMAKE_DRIVERS` on and an appropriate
111 :ref:`BOOST_CMAKE_INFRASTRUCTURE_DIR`, cmake's ``find_package`` will
112 find without setting any particular path::
113
114   set(Boost_USE_MULTITHREADED ON)
115   find_package(Boost 1.41.0 COMPONENTS thread NO_MODULE)
116
117   include(${Boost_INCLUDE_DIR})
118   add_executable(main main.cpp)
119   target_link_libraries(main ${Boost_LIBRARIES})
120
121 .. rubric:: Note 
122
123 the ``NO_MODULE`` is required if your cmake is older than (FIXME,
124 currently required with all versions, modification to the
125 FindBoost.cmake distributed with cmake itself is required).
126
127 Here, having installed to ``/usr/local/boost-1.41.0``, I see::
128
129   % make VERBOSE=1
130   ...
131   [100%] Building CXX object CMakeFiles/main.dir/main.cpp.o
132   /usr/bin/c++    -I/usr/local/boost-1.41.0/include   -o CMakeFiles/main.dir/main.cpp.o -c /home/troy/Projects/boost/cmake/proj/main.cpp
133   ...
134   Linking CXX executable main
135   /usr/bin/c++     -fPIC CMakeFiles/main.dir/main.cpp.o  -o main -rdynamic /usr/local/boost-1.41.0/lib/libboost_thread-mt-d.so.1.41.0 -lpthread -lrt -Wl,-rpath,/usr/local/boost-1.41.0/lib 
136   ...
137   [100%] Built target main
138
139 See also the documentation for ``FindBoost.cmake``.
140
141 The Somewhat harder way
142 -----------------------
143
144 If your boost installation does *not* come with the file installed
145 when :ref:`BOOST_INSTALL_FINDBOOST_CMAKE_DRIVERS`, you will need to
146 specify the path to the Boost.cmake file installed in
147 :ref:`BOOST_LIB_INSTALL_DIR <install_paths>` (try
148 ``$CMAKE_INSTALL_PREFIX/lib/boost/cmake/Boost.cmake``
149
150
151 .. rubric:: Footnotes
152
153 .. [#libsuffix] If your distribution specifies a :ref:`LIB_SUFFIX`
154                 (e.g. if it installs libraries to
155                 ``${``:ref:`CMAKE_INSTALL_PREFIX`\ ``/lib64``, you
156                 will find `Boost.cmake` there.  If the installation is
157                 'versioned', the ``Boost.cmake`` file may be in a
158                 versioned subdirectory of lib, e.g. ``lib/boost-1.41.0``.