1 .. Copyright David Abrahams 2006. Distributed under the Boost
2 .. Software License, Version 1.0. (See accompanying
3 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
5 =============================================
6 |(logo)|__ Getting Started on Unix Variants
7 =============================================
10 :description: Getting Started with Boost on Unix Variants (including Linux and MacOS)
12 .. |(logo)| image:: ../../boost.png
18 .. section-numbering::
20 .. maybe we don't need this
21 .. Admonition:: A note to Cygwin_ and MinGW_ users
23 If you plan to build from the Cygwin_ bash shell, you're in the
24 right place. If you plan to use your tools from the Windows
25 command prompt, you should follow the instructions for `getting
26 started on Windows`_. Other command shells, such as MinGW_\ 's
27 MSYS, are not supported—they may or may not work.
29 .. _`Getting Started on Windows`: windows.html
30 .. _Cygwin: http://www.cygwin.com
31 .. _MinGW: http://mingw.org
38 The most reliable way to get a copy of Boost is to download a
39 distribution from SourceForge_:
41 .. _SourceForge: `sf-download`_
43 1. Download |boost.tar.bz2|_.
45 2. In the directory where you want to put the Boost installation,
50 tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2
52 .. |boost.tar.bz2| replace:: |boost_ver|\ ``.tar.bz2``
54 .. _`boost.tar.bz2`: `sf-download`_
56 .. Admonition:: Other Packages
58 RedHat, Debian, and other distribution packagers supply Boost
59 library packages, however you may need to adapt these
60 instructions if you use third-party packages, because their
61 creators usually choose to break Boost up into several packages,
62 reorganize the directory structure of the Boost distribution,
63 and/or rename the library binaries. [#packagers]_ If you have
64 any trouble, we suggest using an official Boost distribution
67 .. include:: detail/distro.rst
69 .. include:: detail/header-only.rst
71 .. include:: detail/build-simple-head.rst
73 Now, in the directory where you saved ``example.cpp``, issue the
78 c++ -I |root| example.cpp -o example
80 To test the result, type:
84 echo 1 2 3 | ./example
86 .. include:: detail/errors-and-warnings.rst
88 .. include:: detail/binary-head.rst
90 Easy Build and Install
91 ----------------------
93 Issue the following commands in the shell (don't type ``$``; that
94 represents the shell's prompt):
99 **$** ./bootstrap.sh --help
101 Select your configuration options and invoke ``./bootstrap.sh`` again
102 without the ``--help`` option. Unless you have write permission in
103 your system's ``/usr/local/`` directory, you'll probably want to at
108 **$** ./bootstrap.sh **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix*
110 to install somewhere else. Also, consider using the
111 ``--show-libraries`` and ``--with-libraries=``\ *library-name-list* options to limit the
112 long wait you'll experience if you build everything. Finally,
118 will leave Boost binaries in the ``lib/`` subdirectory of your
119 installation prefix. You will also find a copy of the Boost
120 headers in the ``include/`` subdirectory of the installation
121 prefix, so you can henceforth use that directory as an ``#include``
122 path in place of the Boost root directory.
126 __ `Link Your Program to a Boost Library`_
128 Or, Build Custom Binaries
129 -------------------------
131 If you're using a compiler other than your system's default, you'll
132 need to use Boost.Build_ to create binaries.
135 use this method if you need a nonstandard build variant (see the
136 `Boost.Build documentation`_ for more details).
138 .. include:: detail/build-from-source-head.rst
140 For example, your session might look like this:
145 $ b2 **--build-dir=**\ /tmp/build-boost **toolset=**\ gcc stage
147 That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “``--build-type=complete``”.
149 .. include:: detail/build-from-source-tail.rst
151 .. include:: detail/link-head.rst
153 There are two main ways to link to libraries:
155 A. You can specify the full path to each library:
159 $ c++ -I |root| example.cpp -o example **\\**
160 **~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a**
162 B. You can separately specify a directory to search (with ``-L``\
163 *directory*) and a library name to search for (with ``-l``\
164 *library*, [#lowercase-l]_ dropping the filename's leading ``lib`` and trailing
165 suffix (``.a`` in this case):
169 $ c++ -I |root| example.cpp -o example **\\**
170 **-L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36**
172 As you can see, this method is just as terse as method A for one
173 library; it *really* pays off when you're using multiple
174 libraries from the same directory. Note, however, that if you
175 use this method with a library that has both static (``.a``) and
176 dynamic (``.so``) builds, the system may choose one
177 automatically for you unless you pass a special option such as
178 ``-static`` on the command line.
180 In both cases above, the bold text is what you'd add to `the
181 command lines we explored earlier`__.
183 __ `build a simple program using boost`_
188 .. include:: detail/library-naming.rst
190 .. include:: detail/test-head.rst
192 If you linked to a shared library, you may need to prepare some
193 platform-specific settings so that the system will be able to find
194 and load it when your program is run. Most platforms have an
195 environment variable to which you can add the directory containing
196 the library. On many platforms (Linux, FreeBSD) that variable is
197 ``LD_LIBRARY_PATH``, but on MacOS it's ``DYLD_LIBRARY_PATH``, and
198 on Cygwin it's simply ``PATH``. In most shells other than ``csh``
199 and ``tcsh``, you can adjust the variable as follows (again, don't
200 type the ``$``\ —that represents the shell prompt):
204 **$** *VARIABLE_NAME*\ =\ *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }
205 **$** export *VARIABLE_NAME*
207 On ``csh`` and ``tcsh``, it's
211 **$** setenv *VARIABLE_NAME* *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }
213 Once the necessary variable (if any) is set, you can run your
218 **$** *path*\ /\ *to*\ /\ *compiled*\ /\ example < *path*\ /\ *to*\ /\ jayne.txt
220 The program should respond with the email subject, “Will Success
223 .. include:: detail/conclusion.rst
225 ------------------------------
227 .. [#packagers] If developers of Boost packages would like to work
228 with us to make sure these instructions can be used with their
229 packages, we'd be glad to help. Please make your interest known
230 to the `Boost developers' list`_.
232 .. _Boost developers' list: http://www.boost.org/more/mailing_lists.htm#main
234 .. [#lowercase-l] That option is a dash followed by a lowercase “L”
235 character, which looks very much like a numeral 1 in some fonts.
237 .. |build-type-complete| replace:: `` ``
239 .. include:: detail/common-footnotes.rst
240 .. include:: detail/release-variables.rst
241 .. include:: detail/common-unix.rst
242 .. include:: detail/links.rst