diff --git a/getting_started.html b/getting_started.html index 6a69396..62d669e 100644 --- a/getting_started.html +++ b/getting_started.html @@ -1,952 +1,12 @@ - - - + - - -Boost Getting Started - + -
-

Getting Started

- - - -
-

1   Introduction

-

Welcome to the Boost libraries! By the time you've completed this -tutorial, you'll be at least somewhat comfortable with the contents -of a Boost distribution and how to go about using it.

-
-

1.1   What's Here

-

This document is designed to be an extremely gentle introduction, -so we included a fair amount of material that may already be very -familiar to you. To keep things simple, we also left out some -information intermediate and advanced users will probably want. At -the end of this document, we'll refer you on to resources that can -help you pursue these topics further.

-
-
-

1.2   Preliminaries

-

We use one typographic convention that might not be immediately -obvious: italic text in examples is meant as a descriptive -placeholder for something else, usually information that you'll -provide. For example:

-
-$ echo "My name is your name"
-
-

Here you're expected to imagine replacing the text “your name” with -your actual name.

-

We identify Unix and its variants such as Linux, FreeBSD, and MacOS -collectively as *nix. If you're not targeting Microsoft Windows, -the instructions for *nix users will probably work for you. -Cygwin users working from the Cygwin bash prompt should also -follow the *nix instructions. To use your Cygwin compiler from -the Windows command prompt, follow the instructions for Windows -users.

-

Although Boost supports a wide variety of Windows compilers -(including older Microsoft compilers), most instructions for -Windows users cover only the Visual Studio .NET 2003 and Visual -Studio 2005. We hope that gives you enough information to adapt -them for your own compiler or IDE.

-
-
-
-

2   Get Boost

-

There are basically three ways to get Boost on your system:

-
    -
  1. Windows Installer: Boost Consulting provides an installer -for Windows platforms that installs a complete Boost -distribution, plus optional precompiled library binaries for -Visual Studio, and (optionally) a prebuilt version of the -bjam build tool.

    -
  2. -
  3. Download: users of other platforms—and Windows -users who prefer to build everything from scratch—can download -a complete Boost distribution from SourceForge.

    - -
      -
    • Windows: Download and run boost_1_34_0.exe -to unpack the distribution.1

      -
    • -
    • *nix: Download boost_1_34_0.tar.bz2. Then, in the -directory where you want to put the Boost installation, -execute

      -
      -tar --bzip2 -xf /path/to/boost_1_34_0.tar.bz2
      -
      -
    • -
    -
  4. -
  5. Boost packages from RedHat, Debian, or some other -distribution packager: these instructions may not work for you -if you use 3rd party packages, because other packagers sometimes -choose to break Boost up into several packages or to reorganize -the directory structure of the Boost distribution.2

    -
  6. -
-
-
-

3   The Structure of a Boost Distribution

-

This is is a sketch of the directory structure you'll get when you -unpack your Boost installation (windows users replace forward -slashes with backslashes):

-
-boost_1_34_0/ .................The “boost root directory”
-   index.htm .........A copy of www.boost.org starts here
-   boost/ .........................All Boost Header files
-   libs/ ............Tests, .cpps, docs, etc., by library3
-     index.html ........Library documentation starts here
-     algorithm/
-     any/
-     array/
-                     …more libraries…
-   status/ .........................Boost-wide test suite
-   tools/ ...........Utilities, e.g. bjam, quickbook, bcp
-   more/ ..........................Policy documents, etc.
-   doc/ ...............A subset of all Boost library docs
-
- -

A few things are worth noting right off the bat:

-
    -
  1. The path to the “boost root directory” is sometimes referred to -as $BOOST_ROOT in documentation and mailing lists. If you -used the Windows installer, that will usually be C: \Program`` \ ``Files\boost\boost_1_34_0.

    -
  2. -
  3. To compile anything in Boost, you need a directory containing -the boost/ subdirectory in your #include path. For most -compilers, that means adding

    -
    --I/path/to/boost_1_34_0
    -
    -

    to the command line. Specific steps for setting up #include -paths in Microsoft Visual Studio follow later in this document; -if you use another IDE, please consult your product's -documentation for instructions.

    -
  4. -
  5. Since all of Boost's header files have the .hpp extension, -and live in the boost/ subdirectory of the boost root, your -Boost #include directives will look like:

    -
    -#include <boost/whatever.hpp>
    -
    -

    or

    -
    -#include "boost/whatever.hpp"
    -
    -
  6. -
-
-depending on your religion as regards the use of angle bracket -includes. Even Windows users can use forward slashes in -#include directives; your compiler doesn't care.
-
    -
  1. Don't be distracted by the doc/ subdirectory; it only -contains a subset of the Boost documentation. Start with -libs/index.html if you're looking for the whole enchilada.
  2. -
-
-
-

4   Header-Only Libraries

-

The first thing many people want to know is, “how do I build -Boost?” The good news is that often, there's nothing to build.

-
-

Nothing to Build

-

Most Boost libraries are header-only: they consist entirely -of header files containing templates and inline functions, and -require no separately-compiled library binaries or special -treatment when linking.

-
-

The only Boost libraries that can't be used without separate -compilation are:

- -

The DateTime library has a separately-compiled component that -is only needed if you're using its to/from_string and/or -serialization features or if you're targeting Visual C++ 6.x or -Borland. The Graph library also has a separately-compiled part, -but you won't need it unless you intend to parse GraphViz -files.

- -
-
-

5   Build a Simple Program Using Boost

-

To keep things simple, let's start by using a header-only library. -The following program reads a sequence of integers from standard -input, uses Boost.Lambda to multiply each number by three, and -writes them to standard output:

-
-#include <boost/lambda/lambda.hpp>
-#include <iostream>
-#include <iterator>
-#include <algorithm>
-
-int main()
-{
-    using namespace boost::lambda;
-    typedef std::istream_iterator<int> in;
-
-    std::for_each(
-        in(std::cin), in(), std::cout << (_1 * 3) << " " );
-}
-
-

Copy the text of this program into a file called example.cpp.

-
-

5.1   Build on *nix

-

In the directory where you saved example.cpp, issue the -following command:

-
-c++ -I /path/to/boost_1_34_0 example.cpp -o example
-
-

To test the result, type:

-
-echo 1 2 3 | ./example
-
-

next...

-
-
-

5.2   Build from the Visual Studio Command Prompt

-

From your computer's Start menu, if you are a Visual -Studio 2005 user, select

-
-All Programs > Microsoft Visual Studio 2005 -> Visual Studio Tools > Visual Studio 2005 Command Prompt
-

or, if you're a Visual Studio .NET 2003 user, select

-
-All Programs > Microsoft Visual Studio .NET 2003 -> Visual Studio .NET Tools > Visual Studio .NET 2003 Command Prompt
-

to bring up a special command prompt window set up for the Visual -Studio compiler. In that window, type the following command and -hit the return key:

-
-cl /EHsc /Ipath\to\boost_1_34_0 path\to\example.cpp
-
-

To test the result, type:

-
-echo 1 2 3 | example
-
-

next...

-
-
-

5.3   Build in the Visual Studio IDE

-
    -
  • From Visual Studio's File menu, select New > Project…
  • -
  • In the left-hand pane of the resulting New Project dialog, -select Visual C++ > Win32.
  • -
  • In the right-hand pane, select Win32 Console Application -(VS8.0) or Win32 Console Project (VS7.1).
  • -
  • In the name field, enter “example”
  • -
  • Right-click example in the Solution Explorer pane and -select Properties from the resulting pop-up menu
  • -
  • In Configuration Properties > C/C++ > General > Additional Include -Directories, enter the path to the Boost root directory, e.g. -C: \Program`` \ ``Files\boost\boost_1_34_0.
  • -
  • In Configuration Properties > C/C++ > Precompiled Headers, change -Use Precompiled Header (/Yu) to Not Using Precompiled -Headers.5
  • -
  • Replace the contents of the example.cpp generated by the IDE -with the example code above.
  • -
  • From the Build menu, select Build Solution.
  • -
-

To test your application, hit the F5 key and type the following -into the resulting window, followed by the return key:

-
-1 2 3
-
-

Then hold down the control key and press "Z", followed by the -return key.

-
-
-

5.4   Errors and Warnings

-

Don't be alarmed if you see compiler warnings from Boost headers. -We try to eliminate them, but doing so isn't always practical.4

-

Errors are another matter. If you're seeing compilation errors at -this point in the tutorial, check to be sure you've copied the -example program correctly and that you've correctly identified the -Boost root directory.

-
-
-
-

6   Get Boost Library Binaries

-

If you want to use any of the separately-compiled Boost libraries, -you'll need library binaries.

-
-

6.1   Install Visual Studio Binaries

-

The Windows installer supplied by Boost Consulting will download -and install pre-compiled binaries into the lib\ subdirectory of -the boost root, typically C: \Program`` \ ``Files\boost\boost_1_34_0\lib\.

-

next...

-
-
-

6.2   Build and Install *nix Binaries

-

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

-
-$ cd /path/to/boost_1_34_0
-$ ./configure --help
-
-

Select your configuration options and invoke ./configure again. -Unless you have write permission in your system's /usr/local/ -directory, you'll probably want to at least use

-
-$ ./configure --prefix=path/to/installation/prefix
-
-

to install somewhere else. Finally,

-
-$ make install
-
-

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

-
-
-

6.3   Build and Install Other Binaries

-

If you're not using Visual C++ 7.1 or 8.0, or you're a *nix user -who wants want to build with a toolset other than your system's -default, or if you want a nonstandard variant build of Boost -(e.g. optimized, but with debug symbols), you'll need to use -Boost.Build to create your own binaries.

-

Boost.Build is a text-based system for developing, testing, and -installing software. To use it, you'll need an executable called -bjam.

-
-

Get bjam

-

bjam is the command-line tool that drives the Boost Build -system. To build Boost binaries, you'll invoke bjam from the -Boost root.

-

Boost provides pre-compiled bjam executables for a variety of platforms. -Alternatively, you can build bjam yourself using these -instructions.

-
-
-

Identify Your Toolset

-

First, find the toolset corresponding to your compiler in the -following table.

- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Toolset -NameVendorNotes
accHewlett PackardOnly very recent versions are -known to work well with Boost
borlandBorland 
comoComeau ComputingUsing this toolset may -require configuring another -toolset to act as its backend
cwMetrowerks/FreeScaleThe CodeWarrior compiler. We -have not tested versions of -this compiler produced since -it was sold to FreeScale.
dmcDigital MarsAs of this Boost release, no -version of dmc is known to -handle Boost well.
darwinApple ComputerApple's version of the GCC -toolchain with support for -Darwin and MacOS X features -such as frameworks.
gccThe Gnu ProjectIncludes support for Cygwin -and MinGW compilers.
hp_cxxHewlett PackardTargeted at the Tru64 -operating system.
intelIntel 
kylixBorland 
msvcMicrosoft 
qccQNX Software Systems 
sunSunOnly very recent versions are -known to work well with -Boost.
vacppIBMThe VisualAge C++ compiler.
-

If you have multiple versions of a particular compiler installed, -you can apend the version number to the toolset name, preceded by a -hyphen, e.g. msvc-7.1 or gcc-3.4.

-
-

Note

-

if you built bjam yourself, you may -have selected a toolset name for that purpose, but that does not -affect this step in any way; you still need to select a Boost.Build -toolset from the table.

-
-
-
-

Select a Build Directory

-

Boost.Build will place all intermediate files it generates while -building into the build directory. If your Boost root -directory is writable, this step isn't strictly necessary: by -default Boost.Build will create a bin.v2/ subdirectory for that -purpose in your current working directory.

-
-
-

Invoke bjam

-

Change your current directory to the Boost root directory and -invoke bjam as follows:

-
-bjam --build-dir=build-directory \
-     --toolset=toolset-name stage
-
-

For example, on Windows, your session might look like:

-
-C:WINDOWS> cd C: \Program`` \ ``Files\boost\boost_1_34_0
-C: \Program`` \ ``Files\boost\boost_1_34_0> bjam \
-  --build-dir=%TEMP%\build-boost          \
-  --toolset=msvc stage
-
-

And on Unix:

-
-$ cd ~/boost_1_34_0
-$ bjam --build-dir=~/build-boost --prefix=~/boost
-
-

In either case, Boost.Build will place the Boost binaries in the -stage/ subdirectory of your build directory.

-
-

Note

-

bjam is case-sensitive; it is important that all the -parts shown in bold type above be entirely lower-case.

-
-

For a description of other options you can pass when invoking -bjam, type:

-
-bjam --help
-
-
-
-
-

6.4   Expected Build Output

-

During the process of building Boost libraries, you can expect to -see some messages printed on the console. These may include

-
    -
  • Notices about Boost library configuration—for example, the Regex -library outputs a message about ICU when built without Unicode -support, and the Python library may be skipped without error (but -with a notice) if you don't have Python installed.

    -
  • -
  • Messages from the build tool that report the number of targets -that were built or skipped. Don't be surprised if those numbers -don't make any sense to you; there are many targets per library.

    -
  • -
  • Build action messages describing what the tool is doing, which -look something like:

    -
    -toolset-name.c++ long/path/to/file/being/built
    -
    -
  • -
  • Compiler warnings.

    -
  • -
-
-
-

6.5   In Case of Build Errors

-

The only error messages you see when building Boost—if any—should -be related to the IOStreams library's support of zip and bzip2 -formats as described here. Install the relevant development -packages for libz and libbz2 if you need those features. Other -errors when building Boost libraries are cause for concern.

-

If it seems like the build system can't find your compiler and/or -linker, consider setting up a user-config.jam file as described -in the Boost.Build documentation. If that isn't your problem or -the user-config.jam file doesn't work for you, please address -questions about configuring Boost for your compiler to the -Boost.Build mailing list.

-
-
-
-

7   Link Your Program to a Boost Library

-

To demonstrate linking with a Boost binary library, we'll use the -following simple program that extracts the subject lines from -emails. It uses the Boost.Regex library, which has a -separately-compiled binary component.

-
-#include <boost/regex.hpp>
-#include <iostream>
-#include <string>
-
-int main()
-{
-    std::string line;
-    boost::regex pat( "^Subject: (Re: |Aw: )*(.*)" );
-
-    while (std::cin)
-    {
-        std::getline(std::cin, line);
-        boost::smatch matches;
-        if (boost::regex_match(line, matches, pat))
-            std::cout << matches[2] << std::endl;
-    }
-}
-
-

There are two main challenges associated with linking:

-
    -
  1. Tool configuration, e.g. choosing command-line options or IDE -build settings.
  2. -
  3. Identifying the library binary, among all the build variants, -whose compile configuration is compatible with the rest of your -project.
  4. -
-
-

Note

-

Boost.Python users should read that library's own build -documentation as there are several library-specific issues to -consider.

-
-
-

7.1   Link to a Boost Library on Windows

-

Most Windows compilers and linkers have so-called “auto-linking -support,” which eliminates the second challenge. Special code in -Boost header files detects your compiler options and uses that -information to encode the name of the correct library into your -object files; the linker selects the library with that name from -the directories you've told it to search.

-
-

Link to a Boost Library from the Visual Studio Command Prompt

-

For example, we can compile and link the above program from the -Visual C++ command-line by simply adding the bold text below to -the command line we used earlier, assuming your Boost binaries are -in C: \Program`` \ ``Files\boost\boost_1_34_0\lib:

-
-cl /EHsc /I path\to\boost_1_34_0 example.cpp   \
-     /link /LIBPATH: C:\Program Files\boost\boost_1_34_0\lib
-
-

next...

-
-
-

Link to a Boost Library in the Visual Studio IDE

-

Starting with the header-only example project we created -earlier:

-
    -
  1. Right-click example in the Solution Explorer pane and -select Properties from the resulting pop-up menu
  2. -
  3. In Configuration Properties > Linker > Additional Library -Directories, enter the path to the Boost binaries, -e.g. C: \Program`` \ ``Files\boost\boost_1_34_0\lib\.
  4. -
  5. From the Build menu, select Build Solution.
  6. -
-

next...

-
-
-
-

7.2   Link to a Boost Library On *nix

-

There are two main ways to link to libraries:

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

    -
    -$ c++ -I /path/to/boost_1_34_0 example.cpp -o example \
    -   ~/boost/lib/libboost_regex-gcc-3.4-mt-d-1_34.a
    -
    -
  2. -
  3. You can separately specify a directory to search (with -Ldirectory) and a library name to search for (with -llibrary,6 dropping the filename's leading lib and trailing -suffix (.a in this case):

    -
    -$ c++ -I /path/to/boost_1_34_0 example.cpp -o example \
    -   -L~/boost/lib/ -lboost_regex-gcc-3.4-mt-d-1_34
    -
    -

    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.

    -
  4. -
-

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

-
-
-

7.3   Library Naming

-

When auto-linking is not available, you need to know how Boost -binaries are named so you can choose the right one for your build -configuration. Each library filename is composed of a common -sequence of elements that describe how it was built. For example, -libboost_regex-vc71-mt-d-1_34.lib can be broken down into the -following elements:

-
-
lib
-
Prefix: except on Microsoft Windows, every Boost library -name begins with this string. On Windows, only ordinary static -libraries use the lib prefix; import libraries and DLLs do -not.7
-
boost_regex
-
Library name: all boost library filenames begin with boost_.
-
-vc71
-
Toolset tag: identifies the toolset and version used to build -the binary.
-
-mt
-
Threading tag: indicates that the library was -built with multithreading support enabled. Libraries built -without multithreading support can be identified by the absence -of -mt.
-
-d
-

ABI tag: encodes details that affect the library's -interoperability with other compiled code. For each such -feature, a single letter is added to the tag:

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyUse this library when:
slinking statically to the C++ standard library and compiler runtime support -libraries.
gusing debug versions of the standard and runtime support libraries.
yusing a special debug build of Python.
dbuilding a debug version of your code.8
pusing the STLPort standard library rather than the default one supplied with -your compiler.
nusing STLPort's deprecated “native iostreams” feature.9
-

For example, if you build a debug version of your code for use -with debug versions of the static runtime library and the -STLPort standard library in “native iostreams” mode, -the tag would be: -sgdpn. If none of the above apply, the -ABI tag is ommitted.

-
-
-1_34
-
Version tag: the full Boost release number, with periods -replaced by underscores. For example, version 1.31.1 would be -tagged as "-1_31_1".
-
.lib
-
Extension: determined according to the -operating system's usual convention. On most *nix platforms the extensions are -.a and .so for static libraries (archives) and shared -libraries, respectively. On Windows—except for libraries built -by gcc toolset, which always uses the *nix -convention—``.dll`` indicates a shared library and .lib -indicates a static or import library. Where supported by *nix -toolsets, a full version extension is added (e.g. ".so.1.34"); a -symbolic link to the library file, named without the trailing -version number, will also be created.
-
-
-
-

7.4   Test Your Program

-

To test our subject extraction, we'll filter the following text -file. Copy it out of your browser and save it as jayne.txt:

-
-To: George Shmidlap
-From: Rita Marlowe
-Subject: Will Success Spoil Rock Hunter?
----
-See subject.
-
-
-

Test Your Program on Microsoft Windows

-

In a command prompt window, type:

-
-path\to\compiled\example < path\to\jayne.txt
-
-

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

-
-
-

Test Your Program on *nix

-

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?”

-
-
-
-
-

8   Conclusion and Further Resources

-

This concludes your introduction to Boost and to integrating it -with your programs. As you start using Boost in earnest, there are -surely a few additional points you'll wish we had covered. One day -we may have a “Book 2 in the Getting Started series” that addresses -them. Until then, we suggest you pursue the following resources. -If you can't find what you need, or there's anything we can do to -make this document clearer, please post it to the Boost Users' -mailing list.

- -
-

Onward

-
-

Good luck, and have fun!

-

—the Boost Developers

-
-
-
-
-

9   Appendix: Using command-line tools in Windows

-

In Windows, a command-line tool is invoked by typing its name, -optionally followed by arguments, into a Command Prompt window -and pressing the Return (or Enter) key.

-

To open Command Prompt, click the Start menu button, click -Run, type “cmd”, and then click OK.

-

All commands are executed within the context of a current -directory in the filesystem. To set the current directory, -type:

-
-cd path\to\some\directory
-
-

followed by Return. For example,

-
-cd C: \Program`` \ ``Files\boost\boost_1_34_0
-
-

One way to name a directory you know about is to write

-
-%HOMEDRIVE%%HOMEPATH%\directory-name
-
-

which indicates a sibling folder of your “My Documents” folder.

-

Long commands can be continued across several lines by typing -backslashes at the ends of all but the last line. Many of the -examples on this page use that technique to save horizontal -space.

-
- - - - - -
[1]If you prefer not to download executable programs, download -boost_1_34_0.zip and use an external tool to decompress -it. We don't recommend using Windows' built-in decompression as -it can be painfully slow for large archives.
- - - - - -
[2]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.
- - - - - -
[3]If you used the Windows installer from Boost -Consulting and deselected “Source and Documentation” (it's -selected by default), you won't see the libs/ subdirectory. -That won't affect your ability to use precompiled binaries, but -you won't be able to rebuild libraries from scratch.
- - - - - -
[4]Remember that warnings are specific to each compiler -implementation. The developer of a given Boost library might -not have access to your compiler. Also, some warnings are -extremely difficult to eliminate in generic code, to the point -where it's not worth the trouble. Finally, some compilers don't -have any source code mechanism for suppressing warnings.
- - - - - -
[5]There's no problem using Boost with precompiled headers; -these instructions merely avoid precompiled headers because it -would require Visual Studio-specific changes to the source code -used in the examples.
- - - - - -
[6]That option is a dash followed by a lowercase “L” -character, which looks very much like a numeral 1 in some fonts.
- - - - - -
[7]This convention distinguishes the static version of -a Boost library from the import library for an -identically-configured Boost DLL, which would otherwise have the -same name.
- - - - - -
[8]These libraries were compiled without optimization -or inlining, with full debug symbols enabled, and without -NDEBUG #defined. All though it's true that sometimes -these choices don't affect binary compatibility with other -compiled code, you can't count on that with Boost libraries.
- - - - - -
[9]This feature of STLPort is deprecated because it's -impossible to make it work transparently to the user; we don't -recommend it.
-
-
- +Automatically loading index page... if nothing happens, please go to +getting_started/index.html. + + +