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) 4 5============================================= 6 |(logo)|__ Getting Started on Unix Variants 7============================================= 8 9.. meta:: 10 :description: Getting Started with Boost on Unix Variants (including Linux and MacOS) 11 12.. |(logo)| image:: ../../boost.png 13 :alt: Boost 14 :class: boost-logo 15 16__ ../../index.htm 17 18.. section-numbering:: 19 20.. maybe we don't need this 21 .. Admonition:: A note to Cygwin_ and MinGW_ users 22 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. 28 29 .. _`Getting Started on Windows`: windows.html 30 .. _Cygwin: http://www.cygwin.com 31 .. _MinGW: http://mingw.org 32 33.. Contents:: Index 34 35Get Boost 36========= 37 38The most reliable way to get a copy of Boost is to download a 39distribution from SourceForge_: 40 41.. _SourceForge: `sf-download`_ 42 431. Download |boost.tar.bz2|_. 44 452. In the directory where you want to put the Boost installation, 46 execute 47 48 .. parsed-literal:: 49 50 tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2 51 52.. |boost.tar.bz2| replace:: |boost_ver|\ ``.tar.bz2`` 53 54.. _`boost.tar.bz2`: `sf-download`_ 55 56.. Admonition:: Other Packages 57 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 65 from SourceForge_. 66 67.. include:: detail/distro.rst 68 69.. include:: detail/header-only.rst 70 71.. include:: detail/build-simple-head.rst 72 73Now, in the directory where you saved ``example.cpp``, issue the 74following command: 75 76.. parsed-literal:: 77 78 c++ -I |root| example.cpp -o example 79 80To test the result, type: 81 82.. parsed-literal:: 83 84 echo 1 2 3 | ./example 85 86.. include:: detail/errors-and-warnings.rst 87 88.. include:: detail/binary-head.rst 89 90Easy Build and Install 91---------------------- 92 93Issue the following commands in the shell (don't type ``$``; that 94represents the shell's prompt): 95 96.. parsed-literal:: 97 98 **$** cd |root| 99 **$** ./bootstrap.sh --help 100 101Select your configuration options and invoke ``./bootstrap.sh`` again 102without the ``--help`` option. Unless you have write permission in 103your system's ``/usr/local/`` directory, you'll probably want to at 104least use 105 106.. parsed-literal:: 107 108 **$** ./bootstrap.sh **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix* 109 110to install somewhere else. Also, consider using the 111``--show-libraries`` and ``--with-libraries=``\ *library-name-list* options to limit the 112long wait you'll experience if you build everything. Finally, 113 114.. parsed-literal:: 115 116 **$** ./b2 install 117 118will leave Boost binaries in the ``lib/`` subdirectory of your 119installation prefix. You will also find a copy of the Boost 120headers in the ``include/`` subdirectory of the installation 121prefix, so you can henceforth use that directory as an ``#include`` 122path in place of the Boost root directory. 123 124|next|__ 125 126__ `Link Your Program to a Boost Library`_ 127 128Or, Build Custom Binaries 129------------------------- 130 131If you're using a compiler other than your system's default, you'll 132need to use Boost.Build_ to create binaries. 133 134You'll also 135use this method if you need a nonstandard build variant (see the 136`Boost.Build documentation`_ for more details). 137 138.. include:: detail/build-from-source-head.rst 139 140For example, your session might look like this: 141 142.. parsed-literal:: 143 144 $ cd ~/|boost_ver| 145 $ b2 **--build-dir=**\ /tmp/build-boost **toolset=**\ gcc stage 146 147That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “``--build-type=complete``”. 148 149.. include:: detail/build-from-source-tail.rst 150 151.. include:: detail/link-head.rst 152 153There are two main ways to link to libraries: 154 155A. You can specify the full path to each library: 156 157 .. parsed-literal:: 158 159 $ c++ -I |root| example.cpp -o example **\\** 160 **~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a** 161 162B. 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): 166 167 .. parsed-literal:: 168 169 $ c++ -I |root| example.cpp -o example **\\** 170 **-L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36** 171 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. 179 180In both cases above, the bold text is what you'd add to `the 181command lines we explored earlier`__. 182 183__ `build a simple program using boost`_ 184 185Library Naming 186-------------- 187 188.. include:: detail/library-naming.rst 189 190.. include:: detail/test-head.rst 191 192If you linked to a shared library, you may need to prepare some 193platform-specific settings so that the system will be able to find 194and load it when your program is run. Most platforms have an 195environment variable to which you can add the directory containing 196the library. On many platforms (Linux, FreeBSD) that variable is 197``LD_LIBRARY_PATH``, but on MacOS it's ``DYLD_LIBRARY_PATH``, and 198on Cygwin it's simply ``PATH``. In most shells other than ``csh`` 199and ``tcsh``, you can adjust the variable as follows (again, don't 200type the ``$``\ —that represents the shell prompt): 201 202.. parsed-literal:: 203 204 **$** *VARIABLE_NAME*\ =\ *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ } 205 **$** export *VARIABLE_NAME* 206 207On ``csh`` and ``tcsh``, it's 208 209.. parsed-literal:: 210 211 **$** setenv *VARIABLE_NAME* *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ } 212 213Once the necessary variable (if any) is set, you can run your 214program as follows: 215 216.. parsed-literal:: 217 218 **$** *path*\ /\ *to*\ /\ *compiled*\ /\ example < *path*\ /\ *to*\ /\ jayne.txt 219 220The program should respond with the email subject, “Will Success 221Spoil Rock Hunter?” 222 223.. include:: detail/conclusion.rst 224 225------------------------------ 226 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`_. 231 232 .. _Boost developers' list: http://www.boost.org/more/mailing_lists.htm#main 233 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. 236 237.. |build-type-complete| replace:: `` `` 238 239.. include:: detail/common-footnotes.rst 240.. include:: detail/release-variables.rst 241.. include:: detail/common-unix.rst 242.. include:: detail/links.rst 243
