more/getting_started/unix-variants.rst

__ Getting Started on Unix Variants

Index

Get Boost

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

1. Download .tar.bz2_.

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

   tar --bzip2 -xf /path/to/.tar.bz2

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.¹ If you have any trouble, we suggest using an official Boost distribution from SourceForge.

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

c++ -I example.cpp -o example

To test the result, type:

echo 1 2 3 | ./example

Easy Build and Install

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

$ cd $ ./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

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

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

$ ./b2 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.

__

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).

For example, your session might look like this:

$ cd ~/ $ b2 --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”.

There are two main ways to link to libraries:

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

   $ c++ -I example.cpp -o example \

   ~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a

2. You can separately specify a directory to search (with -Ldirectory) and a library name to search for (with -llibrary,² dropping the filename's leading lib and trailing suffix (.a in this case):

   $ c++ -I 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.

Library Naming

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):

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

On csh and tcsh, it's

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

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

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

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

---

---

1. 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.↩︎

2. That option is a dash followed by a lowercase “L” character, which looks very much like a numeral 1 in some fonts.↩︎