boost/more/getting_started/unix-variants.rst

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

=============================================
 |(logo)|__ Getting Started on Unix Variants
=============================================

.. meta::
    :description: Getting Started with Boost on Unix Variants (including Linux and MacOS)

.. |(logo)| image:: ../../boost.png
   :alt: Boost
   :class: boost-logo

__ ../../index.htm

.. section-numbering::

.. maybe we don't need this
   .. Admonition:: A note to Cygwin_ and MinGW_ users

     If you plan to build from the Cygwin_ bash shell, you're in the
     right place.  If you plan to use your tools from the Windows
     command prompt, you should follow the instructions for `getting
     started on Windows`_.  Other command shells, such as MinGW_\ 's
     MSYS, are not supported—they may or may not work.

     .. _`Getting Started on Windows`: windows.html
     .. _Cygwin: http://www.cygwin.com
     .. _MinGW: http://mingw.org

.. Contents:: Index

Get Boost
=========

The most reliable way to get a copy of Boost is to download a
distribution from SourceForge_:

.. _SourceForge: `sf-download`_

1. Download |boost.tar.bz2|_.  

2. In the directory where you want to put the Boost installation,
   execute

   .. parsed-literal::

      tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2

.. |boost.tar.bz2| replace:: |boost_ver|\ ``.tar.bz2``

.. _`boost.tar.bz2`: `sf-download`_

.. Admonition:: Other Packages

   RedHat, Debian, and other distribution packagers supply Boost
   library packages, however you may need to adapt these
   instructions if you use third-party packages, because their
   creators usually choose to break Boost up into several packages,
   reorganize the directory structure of the Boost distribution,
   and/or rename the library binaries. [#packagers]_ If you have
   any trouble, we suggest using an official Boost distribution
   from SourceForge_.

.. include:: detail/distro.rst

.. include:: detail/header-only.rst

.. include:: detail/build-simple-head.rst

Now, in the directory where you saved ``example.cpp``, issue the
following command:

.. parsed-literal::

  c++ -I |root| example.cpp -o example

To test the result, type:

.. parsed-literal::

  echo 1 2 3 | ./example

.. include:: detail/errors-and-warnings.rst

.. include:: detail/binary-head.rst

Easy Build and Install
----------------------

Issue the following commands in the shell (don't type ``$``; that
represents the shell's prompt):

.. parsed-literal::

  **$** cd |root|
  **$** ./bootstrap.sh --help

Select your configuration options and invoke ``./bootstrap.sh`` again
without the ``--help`` option.  Unless you have write permission in
your system's ``/usr/local/`` directory, you'll probably want to at
least use

.. parsed-literal::

  **$** ./bootstrap.sh **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix* 

to install somewhere else.  Also, consider using the
``--show-libraries`` and ``--with-libraries=`` options to limit the
long wait you'll experience if you build everything.  Finally,

.. parsed-literal::

  **$** ./bjam install

will leave Boost binaries in the ``lib/`` subdirectory of your
installation prefix.  You will also find a copy of the Boost
headers in the ``include/`` subdirectory of the installation
prefix, so you can henceforth use that directory as an ``#include``
path in place of the Boost root directory.

|next|__

__ `Link Your Program to a Boost Library`_

Or, Build Custom Binaries
-------------------------

If you're using a compiler other than your system's default, you'll
need to use Boost.Build_ to create binaries.  You'll also
use this method if you need a nonstandard build variant (see the
`Boost.Build documentation`_ for more details).

.. include:: detail/build-from-source-head.rst

For example, your session might look like this:

.. parsed-literal::

   $ cd ~/|boost_ver|
   $ bjam **--build-dir=**\ /tmp/build-boost **toolset=**\ gcc stage

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``”.

.. include:: detail/build-from-source-tail.rst

.. include:: detail/link-head.rst

There are two main ways to link to libraries:

A. You can specify the full path to each library:

   .. parsed-literal::

     $ c++ -I |root| example.cpp -o example **\\**
        **~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a**

B. You can separately specify a directory to search (with ``-L``\
   *directory*) and a library name to search for (with ``-l``\
   *library*, [#lowercase-l]_ dropping the filename's leading ``lib`` and trailing
   suffix (``.a`` in this case): 

   .. parsed-literal::

     $ c++ -I |root| example.cpp -o example **\\**
        **-L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36**

   As you can see, this method is just as terse as method A for one
   library; it *really* pays off when you're using multiple
   libraries from the same directory.  Note, however, that if you
   use this method with a library that has both static (``.a``) and
   dynamic (``.so``) builds, the system may choose one
   automatically for you unless you pass a special option such as
   ``-static`` on the command line.

In both cases above, the bold text is what you'd add to `the
command lines we explored earlier`__.

__ `build a simple program using boost`_

Library Naming
--------------

.. include:: detail/library-naming.rst

.. include:: detail/test-head.rst

If you linked to a shared library, you may need to prepare some
platform-specific settings so that the system will be able to find
and load it when your program is run.  Most platforms have an
environment variable to which you can add the directory containing
the library.  On many platforms (Linux, FreeBSD) that variable is
``LD_LIBRARY_PATH``, but on MacOS it's ``DYLD_LIBRARY_PATH``, and
on Cygwin it's simply ``PATH``.  In most shells other than ``csh``
and ``tcsh``, you can adjust the variable as follows (again, don't
type the ``$``\ —that represents the shell prompt):

.. parsed-literal::

   **$** *VARIABLE_NAME*\ =\ *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }
   **$** export *VARIABLE_NAME*

On ``csh`` and ``tcsh``, it's

.. parsed-literal::

   **$** setenv *VARIABLE_NAME* *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }

Once the necessary variable (if any) is set, you can run your
program as follows:

.. parsed-literal::

   **$** *path*\ /\ *to*\ /\ *compiled*\ /\ example < *path*\ /\ *to*\ /\ jayne.txt

The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”

.. include:: detail/conclusion.rst

------------------------------

.. [#packagers] If developers of Boost packages would like to work
   with us to make sure these instructions can be used with their
   packages, we'd be glad to help.  Please make your interest known
   to the `Boost developers' list`_.

   .. _Boost developers' list: http://www.boost.org/more/mailing_lists.htm#main

.. [#lowercase-l] That option is a dash followed by a lowercase “L”
   character, which looks very much like a numeral 1 in some fonts.

.. |build-type-complete| replace:: `` `` 

.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst
.. include:: detail/common-unix.rst
.. include:: detail/links.rst