Backport lots of new features from the 1.41.0 branch.
[boost:cmake.git] / tools / build / CMake / docs / build / html / _sources / quickstart.txt
1 .. boost-cmake documentation master file, created by
2    sphinx-quickstart on Mon May 11 08:53:19 2009.
3    You can adapt this file completely to your liking, but it should at least
4    contain the root `toctree` directive.
5
6 .. _quickstart:
7
8 Quickstart
9 ==========
10
11 This page describes how to configure and build Boost with CMake. By
12 following these instructions, you should be able to get CMake,
13 configure a Boost build tree to your liking with CMake, and then
14 build, install, and package Boost libraries.
15
16 Download CMake
17 --------------
18
19 You can get it here:  http://www.cmake.org/HTML/Download.html
20
21 There are precompiled binaries for CMake on several different
22 platforms. The installation of these pre-compiled binaries is mostly
23 self-explanatory. If you need to build your own copy of CMake, please
24 see the `CMake installation instructions
25 <http://www.cmake.org/HTML/Install.html>`_.  
26
27 Check out the code
28 ------------------
29
30 The code associated with these docs is available at
31 http://gitorious.org/boost/cmake with tag |release|.  You can clone
32 the repository locally and then check out the tag.  Tarballs and
33 zipfiles corresponding to these tags are avaiable at
34 http://sodium.resophonic.com/boost-cmake.
35
36 In these instructions, we will do things such that the Boost source
37 tree (with CMake build files) is available in the directory
38 ``$BOOST/src`` and that the build will happen in ``$BOOST/build``::
39
40   $BOOST/
41     src/     # (source checked out to here)
42     build/   # (build output here) 
43
44 Note that it is *not* actually necessary to set any environment
45 variable ``BOOST``, this is a convention used in this document.
46  
47 On Unix
48 -------
49
50 Create and change to the directory that will hold the binaries that
51 CMake build::
52
53   mkdir $BOOST/build 
54   cd $BOOST/build
55
56 .. _unix_configure:
57
58 Configure
59 ^^^^^^^^^
60
61 Run the CMake configuration program, providing it with the Boost
62 source directory::
63
64   cmake -DCMAKE_INSTALL_PREFIX=/somewhere $BOOST/src 
65
66 (:ref:`CMAKE_INSTALL_PREFIX` defaults to ``/usr/local`` on unix and
67 ``C:\\Program Files\Boost`` on windows).  Replace ``/somewhere`` above
68 with a path you like if the defaults aren't okay.  You'll see output
69 from ``cmake``.  It looks somewhat like this::
70
71   -- Check for working C compiler: /usr/bin/gcc
72   -- Check for working C compiler: /usr/bin/gcc -- works
73   -- Check size of void*
74   -- Check size of void* - done
75   -- Check for working CXX compiler: /usr/bin/c++
76   -- Check for working CXX compiler: /usr/bin/c++ -- works
77   -- Scanning subdirectories:
78   --  + io
79   --  + any
80   --  + crc
81   --  + mpl
82   
83     (etc, etc)
84   
85   --  + program_options
86   --  + ptr_container
87   --  + type_traits
88   -- Configuring done
89   -- Generating done
90   -- Build files have been written to: $BOOST/build
91
92 The directory ``$BOOST/build`` should now contain a bunch of generated
93 files, including a top level ``Makefile``, something like this::
94
95   % ls
96   CMakeCache.txt           CPackConfig.cmake    Makefile  
97   cmake_install.cmake      libs/                CMakeFiles/     
98   CPackSourceConfig.cmake  bin/                 lib/
99
100 Build and Install
101 ^^^^^^^^^^^^^^^^^
102
103 Now build and install boost::
104
105   make install
106
107 You'll see::
108
109   Scanning dependencies of target boost_date_time-mt-shared
110   [  0%] Building CXX object libs/date_time/src/CMakeFiles/boost_date_time-mt-shared.dir/gregorian/greg_month.cpp.o
111   [  0%] Building CXX object libs/date_time/src/CMakeFiles/boost_date_time-mt-shared.dir/gregorian/greg_weekday.cpp.o
112   [  1%] Building CXX object libs/date_time/src/CMakeFiles/boost_date_time-mt-shared.dir/gregorian/date_generators.cpp.o
113   Linking CXX shared library ../../../lib/libboost_date_time-mt.so
114   [  1%] Built target boost_date_time-mt-shared
115
116   (etc etc)
117
118   [100%] Built bcp
119
120   (etc etc)
121
122   -- Installing: /tmp/flanboost/lib/libboost_wave-mt-d.a
123   -- Installing: /tmp/flanboost/lib/libboost_wave-mt-d.so
124   -- Removed runtime path from "/tmp/flanboost/lib/libboost_wave-mt-d.so"
125   -- Installing: /tmp/flanboost/bin/bcp
126   -- Installing: /tmp/flanboost/bin/inspect
127
128 And you're done. Once the build completes (which make take a while, if
129 you are building all of the Boost libraries), the Boost libraries will
130 be in a predictable layout under the directory passed to
131 :ref:`CMAKE_INSTALL_PREFIX` (default ``/usr/local``)
132
133 Windows
134 -------
135
136 There are two different sets of directions: visual studio, which is
137 quite specific, and nmake, which is much like the Unix version, above.
138
139 .. index:: Visual Studio
140
141 .. _vs_configure:
142
143 Configuration for Visual Studio
144 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
145
146 Run CMake by selecting it from the Start menu. 
147
148 * Use the *Browse...* button next to *Where is the source code* to
149   point CMake at the Boost source code in ``$BOOST\src``.
150 * Use the second *Browse...* button to next to *Where to build the
151   binaries* to select the directory where Boost will build binaries,
152   ``$BOOST\build``.
153 * Click *Configure* a first time to configure Boost, which will search
154   for various libraries on your system and prepare the build.  CMake
155   will ask you what kind of project files or make files to build. If
156   you're using Microsoft Visual Studio, select the appropriate version
157   to generate project files. Otherwise, you can use Borland's make
158   files.  If you're using NMake, see the next section.
159 * On an XP box with VS9 one sees roughly this in the output window at
160   the bottom::
161
162     Check for working C compiler: cl
163     Check for working C compiler: cl -- works
164     Detecting C compiler ABI info
165     Detecting C compiler ABI info - done
166     Check for working CXX compiler: cl
167     Check for working CXX compiler: cl -- works
168     Detecting CXX compiler ABI info
169     Detecting CXX compiler ABI info - done
170     Boost version 1.41.0
171     Found PythonInterp: C:/Python26/python.exe
172     Found PythonLibs: C:/Python26/libs/python26.lib
173     Boost compiler: msvc
174     Boost toolset:  vc90
175     Boost platform: windows
176     Could NOT find Doxygen  (missing:  DOXYGEN_EXECUTABLE)
177     Build name: msvc-9.0-windows
178      + preprocessor
179      + concept_check
180      ...
181      + units
182      + wave
183     Configuring done    
184
185 * The messages about 'missing doxygen' and whatnot are not
186   showstoppers for now, so long as configuration is successful.  You
187   will be given the opportunity to tune build options in the CMake GUI
188   (see :ref:`configure_and_build` for more detail). They will
189   initially appear red.  Click *Configure* again when you are done
190   editing them.  The one thing that you may wish to configure as part
191   of this 'quickstart' is ``CMAKE_INSTALL_PREFIX``.
192 * Finally, click *Generate* to generate project files.  ``Boost.sln``,
193   the VS solution file, will appear in the *where to build the
194   binaries* directory from the cmake gui.
195
196 .. index:: NMake
197 .. _NMake:
198
199 Configuration for NMake
200 ^^^^^^^^^^^^^^^^^^^^^^^
201
202 * Start a `Visual Studio Command Prompt` from the start menu.  This
203   will spawn a command prompt window with certain env variables set.
204   CMake will detect these and automatically choose to generate NMake
205   files.
206
207 * cd to $BOOST/build and execute::
208
209     cmake ..\src
210
211   You will see output very similar to that on unix, see
212   :ref:`unix_configure`.
213
214 Build -- Visual Studio
215 ^^^^^^^^^^^^^^^^^^^^^^
216
217   Start up Visual Studio, load the solution or project ``Boost`` from
218   the Boost build directory you set in the CMake configuration
219   earlier. Then, just click *Build* to build all of Boost.
220
221 Build -- NMake
222 ^^^^^^^^^^^^^^
223
224   Execute ``nmake`` from the command prompt in the build directory.
225
226 Installation
227 ^^^^^^^^^^^^
228
229 The installation of Boost's headers and compiled libraries uses the
230 same tools as building the library. With Microsoft Visual Studio, just
231 load the Boost solution or project and build the 'INSTALL' target to
232 perform the installation.  With NMake, ``nmake install``.
233