more/getting_started/unix-variants.rst

   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
  35 Get Boost
  36 =========
  37
  38 The most reliable way to get a copy of Boost is to download a
  39 distribution from SourceForge_:
  40
  41 .. _SourceForge: `sf-download`_
  42
  43 1. Download |boost.tar.bz2|_.
  44
  45 2. 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
  73 Now, in the directory where you saved ``example.cpp``, issue the
  74 following command:
  75
  76 .. parsed-literal::
  77
  78   c++ -I |root| example.cpp -o example
  79
  80 To 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
  90 Easy Build and Install
  91 ----------------------
  92
  93 Issue the following commands in the shell (don't type ``$``; that
  94 represents the shell's prompt):
  95
  96 .. parsed-literal::
  97
  98   **$** cd |root|
  99   **$** ./bootstrap.sh --help
 100
 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
 104 least use
 105
 106 .. parsed-literal::
 107
 108   **$** ./bootstrap.sh **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix*
 109
 110 to install somewhere else.  Also, consider using the
 111 ``--show-libraries`` and ``--with-libraries=`` options to limit the
 112 long wait you'll experience if you build everything.  Finally,
 113
 114 .. parsed-literal::
 115
 116   **$** ./bjam install
 117
 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.
 123
 124 |next|__
 125
 126 __ `Link Your Program to a Boost Library`_
 127
 128 Or, Build Custom Binaries
 129 -------------------------
 130
 131 If you're using a compiler other than your system's default, you'll
 132 need to use Boost.Build_ to create binaries.  You'll also
 133 use this method if you need a nonstandard build variant (see the
 134 `Boost.Build documentation`_ for more details).
 135
 136 .. include:: detail/build-from-source-head.rst
 137
 138 For example, your session might look like this:
 139
 140 .. parsed-literal::
 141
 142    $ cd ~/|boost_ver|
 143    $ bjam **--build-dir=**\ /tmp/build-boost **toolset=**\ gcc stage
 144
 145 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``”.
 146
 147 .. include:: detail/build-from-source-tail.rst
 148
 149 .. include:: detail/link-head.rst
 150
 151 There are two main ways to link to libraries:
 152
 153 A. You can specify the full path to each library:
 154
 155    .. parsed-literal::
 156
 157      $ c++ -I |root| example.cpp -o example **\\**
 158         **~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a**
 159
 160 B. You can separately specify a directory to search (with ``-L``\
 161    *directory*) and a library name to search for (with ``-l``\
 162    *library*, [#lowercase-l]_ dropping the filename's leading ``lib`` and trailing
 163    suffix (``.a`` in this case):
 164
 165    .. parsed-literal::
 166
 167      $ c++ -I |root| example.cpp -o example **\\**
 168         **-L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36**
 169
 170    As you can see, this method is just as terse as method A for one
 171    library; it *really* pays off when you're using multiple
 172    libraries from the same directory.  Note, however, that if you
 173    use this method with a library that has both static (``.a``) and
 174    dynamic (``.so``) builds, the system may choose one
 175    automatically for you unless you pass a special option such as
 176    ``-static`` on the command line.
 177
 178 In both cases above, the bold text is what you'd add to `the
 179 command lines we explored earlier`__.
 180
 181 __ `build a simple program using boost`_
 182
 183 Library Naming
 184 --------------
 185
 186 .. include:: detail/library-naming.rst
 187
 188 .. include:: detail/test-head.rst
 189
 190 If you linked to a shared library, you may need to prepare some
 191 platform-specific settings so that the system will be able to find
 192 and load it when your program is run.  Most platforms have an
 193 environment variable to which you can add the directory containing
 194 the library.  On many platforms (Linux, FreeBSD) that variable is
 195 ``LD_LIBRARY_PATH``, but on MacOS it's ``DYLD_LIBRARY_PATH``, and
 196 on Cygwin it's simply ``PATH``.  In most shells other than ``csh``
 197 and ``tcsh``, you can adjust the variable as follows (again, don't
 198 type the ``$``\ —that represents the shell prompt):
 199
 200 .. parsed-literal::
 201
 202    **$** *VARIABLE_NAME*\ =\ *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }
 203    **$** export *VARIABLE_NAME*
 204
 205 On ``csh`` and ``tcsh``, it's
 206
 207 .. parsed-literal::
 208
 209    **$** setenv *VARIABLE_NAME* *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }
 210
 211 Once the necessary variable (if any) is set, you can run your
 212 program as follows:
 213
 214 .. parsed-literal::
 215
 216    **$** *path*\ /\ *to*\ /\ *compiled*\ /\ example < *path*\ /\ *to*\ /\ jayne.txt
 217
 218 The program should respond with the email subject, “Will Success
 219 Spoil Rock Hunter?”
 220
 221 .. include:: detail/conclusion.rst
 222
 223 ------------------------------
 224
 225 .. [#packagers] If developers of Boost packages would like to work
 226    with us to make sure these instructions can be used with their
 227    packages, we'd be glad to help.  Please make your interest known
 228    to the `Boost developers' list`_.
 229
 230    .. _Boost developers' list: http://www.boost.org/more/mailing_lists.htm#main
 231
 232 .. [#lowercase-l] That option is a dash followed by a lowercase “L”
 233    character, which looks very much like a numeral 1 in some fonts.
 234
 235 .. |build-type-complete| replace:: `` ``
 236
 237 .. include:: detail/common-footnotes.rst
 238 .. include:: detail/release-variables.rst
 239 .. include:: detail/common-unix.rst
 240 .. include:: detail/links.rst