From 053821406232e0b87badc400767778eceba423ab Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Fri, 22 Dec 2006 14:52:22 +0000 Subject: [PATCH] Factored getting started guide into separate windows and *nix documents [SVN r36493] --- more/getting_started.html | 997 +--------------- more/getting_started.rst | 1042 ----------------- more/getting_started/Jamfile.v2 | 23 + more/getting_started/detail/binary-head.rst | 10 + .../detail/build-from-source-head.rst | 123 ++ .../detail/build-from-source-tail.rst | 66 ++ .../detail/build-simple-head.rst | 28 + .../detail/common-footnotes.rst | 26 + more/getting_started/detail/common-unix.rst | 21 + .../getting_started/detail/common-windows.rst | 29 + more/getting_started/detail/common.rst | 5 + more/getting_started/detail/conclusion.rst | 39 + more/getting_started/detail/distro.rst | 88 ++ .../detail/errors-and-warnings.rst | 16 + more/getting_started/detail/header-only.rst | 45 + .../getting_started/detail/library-naming.rst | 80 ++ more/getting_started/detail/link-head.rst | 39 + more/getting_started/detail/links.rst | 16 + .../detail/release-variables.rst | 12 + more/getting_started/detail/test-head.rst | 16 + more/getting_started/index.html | 58 + more/getting_started/index.rst | 60 + more/getting_started/unix-variants.html | 786 +++++++++++++ more/getting_started/unix-variants.rst | 236 ++++ more/getting_started/windows.html | 876 ++++++++++++++ more/getting_started/windows.rst | 315 +++++ 26 files changed, 3020 insertions(+), 2032 deletions(-) delete mode 100644 more/getting_started.rst create mode 100644 more/getting_started/Jamfile.v2 create mode 100644 more/getting_started/detail/binary-head.rst create mode 100644 more/getting_started/detail/build-from-source-head.rst create mode 100644 more/getting_started/detail/build-from-source-tail.rst create mode 100644 more/getting_started/detail/build-simple-head.rst create mode 100644 more/getting_started/detail/common-footnotes.rst create mode 100644 more/getting_started/detail/common-unix.rst create mode 100644 more/getting_started/detail/common-windows.rst create mode 100644 more/getting_started/detail/common.rst create mode 100644 more/getting_started/detail/conclusion.rst create mode 100644 more/getting_started/detail/distro.rst create mode 100644 more/getting_started/detail/errors-and-warnings.rst create mode 100644 more/getting_started/detail/header-only.rst create mode 100644 more/getting_started/detail/library-naming.rst create mode 100644 more/getting_started/detail/link-head.rst create mode 100644 more/getting_started/detail/links.rst create mode 100644 more/getting_started/detail/release-variables.rst create mode 100644 more/getting_started/detail/test-head.rst create mode 100644 more/getting_started/index.html create mode 100644 more/getting_started/index.rst create mode 100644 more/getting_started/unix-variants.html create mode 100644 more/getting_started/unix-variants.rst create mode 100644 more/getting_started/windows.html create mode 100644 more/getting_started/windows.rst diff --git a/more/getting_started.html b/more/getting_started.html index 665efff3ec..62d669e763 100644 --- a/more/getting_started.html +++ b/more/getting_started.html @@ -1,995 +1,12 @@ - - - + - - -Boost Getting Started - + -
-

Getting Started

- -
-

Contents

- -
- -
-

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

-

To get Boost, choose one of the following methods:

-
    -

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

  2. Source 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
-
      -
      • -
    -
    3. -

  3. Boost packages are available from RedHat, Debian, and other -distribution packagers. You may need to adapt these -instructions if you use this method, because other packagers -usually choose to break Boost up into several packages, -reorganize the directory structure of the Boost distribution, -and/or rename the library binaries.2 If you have -trouble, we suggest going back to method 2.

    -
    4. -
-
-
-

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

Header Organization

-

The organization of Boost library headers isn't entirely uniform, -but most libraries follow a few patterns:

-
    -
  • Some older libraries and most very small libraries place all -public headers directly into boost/.
    • -
  • Most libraries' public headers live in a subdirectory of -boost/ named after the library. For example, you'll find -the Type Traits Library's is_void.hpp header in -boost/type_traits/is_void.hpp.
    • -
  • Some libraries have an “aggregate header” in boost/ that -#includes all of the library's other headers. For -example, Boost.Python's aggregate header is -boost/python.hpp.
    • -
  • Most libraries place private headers in a subdirectory called -detail/ or aux_/. Don't -expect to find anything you can use in these directories.
    • -
-
-

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

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

    -
    3. -

  3. 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"
-
    -
    4. -
-
-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 must be built separately are:

- -

A few libraries have optional separately-compiled binaries:

-
    -
  • Boost.DateTime has a binary component that is only needed if -you're using its to_string/from_string or serialization -features, or if you're targeting Visual C++ 6.x or Borland.
    • -
  • Boost.Graph also has a binary component that is only needed if -you intend to parse GraphViz files.
    • -
  • Boost.Test ... Waiting for Gennadiy to tell me what to say here.
    • -
- -
-
-

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 on Windows

-
-

The Windows Command Prompt

-

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

Long commands can be continued across several lines by typing a -caret (^) at the end of all but the last line. Some examples -on this page use that technique to save horizontal space.

-
-

To build the examples in this guide, you can use an Integrated -Development Environment (IDE) like Visual Studio or you can follow -a shorter path by issuing commands from the command prompt.

-
-

From 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, for example

    -
    -

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

    -
    • -

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

-

next...

-
-
-

From the 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 /I path\to\boost_1_34_0 path\to\example.cpp
-
-

To test the result, type:

-
-echo 1 2 3 | example
-
-
-
-
-

5.3   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   Prepare to Use a Boost Library Binary

-

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. Also, consider using the ---show-libraries and --with-libraries= options to limit the -long wait you'll experience if you build everything. Finally,

-
-$ make 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...

-
-
-

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 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 this:5

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

And on Unix:

-
-$ cd ~/boost_1_34_0
-$ bjam --build-dir=/tmp/build-boost --toolset=gcc
-
-

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

In particular, to limit the amount of time spent building, you may -be interested in:

-
    -
  • reviewing the list of library names with --show-libraries
    • -
  • limiting which libraries get built with the --with-library-name or --without-library-name options
    • -
  • choosing a specific build variant by adding release or -debug to the command line.
    • -
-
-
-
-

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. -
  2. Identifying the library binary, among all the build variants, -whose compile configuration is compatible with the rest of your -project.
    3. -
-
-

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. -
  2. 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\.
    3. -
  3. From the Build menu, select Build Solution.
    4. -
-

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

  2. You can separately specify a directory to search (with -Ldirectory) and a library name to search for (with -llibrary,7 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.

    -
    3. -
-

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.8
-
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.9
pusing the STLPort standard library rather than the default one supplied with -your compiler.
nusing STLPort's deprecated “native iostreams” feature.10
-

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, .dll indicates a shared library -and—except for static libraries built by gcc toolset, whose -names always end in .a``— ``.lib indicates a static or import -library. Where supported by *nix toolsets, a full version -extension is added (e.g. ".so.1.34") and 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

-
-
-
- - - - - -
[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]In this example, the caret character ^ is a -way of continuing the command on multiple lines. The command -prompt responds with More? to prompt for more input. Feel -free to omit the carets and subsequent newlines; we used them so -the example would fit on a page of reasonable width.
- - - - - -
[6]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.
- - - - - -
[7]That option is a dash followed by a lowercase “L” -character, which looks very much like a numeral 1 in some fonts.
- - - - - -
[8]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.
- - - - - -
[9]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.
- - - - - -
[10]This feature of STLPort is deprecated because it's -impossible to make it work transparently to the user; we don't -recommend it.
-
-
-
-
-View document source. -Generated on: 2006-12-13 23:45 UTC. -Generated by Docutils from reStructuredText source. - -
+Automatically loading index page... if nothing happens, please go to +getting_started/index.html. + + + diff --git a/more/getting_started.rst b/more/getting_started.rst deleted file mode 100644 index 4a9fcba077..0000000000 --- a/more/getting_started.rst +++ /dev/null @@ -1,1042 +0,0 @@ -============================ - |(logo)|__ Getting Started -============================ - -.. |(logo)| image:: ../boost.png - :alt: Boost - :class: boost-logo - -__ ../index.htm - - -.. section-numbering:: - :depth: 2 - -.. contents:: Contents - :depth: 2 - :class: sidebar small - -.. ## Update this substitution for each release - -.. |boost_ver| replace:: ``boost_1_34_0`` -.. |boost_ver-bold| replace:: **boost_1_34_0** - -.. |root| replace:: ``/``\ *path*\ ``/``\ *to*\ ``/``\ |boost_ver| -.. |winroot| replace:: *path*\ ``\``\ *to*\ ``\``\ |boost_ver| -.. |winroot-default| replace:: ``C:\``\ ``Program`` ``Files\boost\``\ |boost_ver| -.. |bold-winroot-default| replace:: **C:\\Program Files\\boost\\**\ |boost_ver-bold| - -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. - -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. - -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: - -.. parsed-literal:: - - **$** 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. - -Get Boost -========= - -To get Boost, choose one of the following methods: - -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. - - .. _Windows installer: http://www.boost-consulting.com/download.html - .. |Windows installer| replace:: **Windows installer** - .. _Boost Consulting: http://boost-consulting.com - .. _installer: `Windows installer`_ - - -2. **Source Download**: users of other platforms—and Windows - users who prefer to build everything from scratch—can `download - a complete Boost distribution`__ from SourceForge. - - .. ## Update this link for each release - __ http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=376197 - - - **Windows**: Download and run |boost_ver|\ ``.exe`` - to unpack the distribution. [#zip]_ - - - ***nix**: Download |boost_ver|\ ``.tar.bz2``. Then, in the - directory where you want to put the Boost installation, - execute - - .. parsed-literal:: - - tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2 - -3. **Boost packages** are available from RedHat, Debian, and other - distribution packagers. You may need to adapt these - instructions if you use this method, because other packagers - 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 - trouble, we suggest going back to method 2. - -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): - -.. parsed-literal:: - - |boost_ver-bold|\ **/** .................\ *The “boost root directory”* - **index.htm** .........\ *A copy of www.boost.org starts here* - **boost/** .........................\ *All Boost Header files* - **libs/** ............\ *Tests, .cpp*\ s\ *, docs, etc., by library* [#installer-src]_ - **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* - -.. sidebar:: Header Organization - :class: small - - The organization of Boost library headers isn't entirely uniform, - but most libraries follow a few patterns: - - * Some older libraries and most very small libraries place all - public headers directly into ``boost/``. - - * Most libraries' public headers live in a subdirectory of - ``boost/`` named after the library. For example, you'll find - the Type Traits Library's ``is_void.hpp`` header in - ``boost/type_traits/is_void.hpp``. - - * Some libraries have an “aggregate header” in ``boost/`` that - ``#include``\ s all of the library's other headers. For - example, Boost.Python_'s aggregate header is - ``boost/python.hpp``. - - * Most libraries place private headers in a subdirectory called - ``detail/`` or ``aux_/``. Don't - expect to find anything you can use in these directories. - -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 |winroot-default|. - -2. To compile anything in Boost, you need a directory containing - the ``boost/`` subdirectory in your ``#include`` path. For most - compilers, that means adding - - .. parsed-literal:: - - -I\ |root| - - 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. - -3. 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: - - .. parsed-literal:: - - #include - - or - - .. parsed-literal:: - - #include "boost/\ *whatever*\ .hpp" - - 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. - -4. 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. - -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. - -.. admonition:: 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. - -.. _separate: - -The only Boost libraries that *must* be built separately are: - -* Boost.Filesystem_ -* Boost.IOStreams_ -* Boost.ProgramOptions_ -* Boost.Python_ -* Boost.Regex_ -* Boost.Serialization_ -* Boost.Signals_ -* Boost.Thread_ -* Boost.Wave_ - -A few libraries have optional separately-compiled binaries: - -* Boost.DateTime_ has a binary component that is only needed if - you're using its ``to_string``\ /\ ``from_string`` or serialization - features, or if you're targeting Visual C++ 6.x or Borland. - -* Boost.Graph_ also has a binary component that is only needed if - you intend to `parse GraphViz files`__. - -* Boost.Test_ can be used in “header-only” or “separately compiled” - mode, although separate compilation is recommended for serious use. - -__ ../libs/graph/doc/read_graphviz.html - -.. ## Keep the list of non-header-only libraries up-to-date - -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 - #include - #include - #include - - int main() - { - using namespace boost::lambda; - typedef std::istream_iterator in; - - std::for_each( - in(std::cin), in(), std::cout << (_1 * 3) << " " ); - } - -Copy the text of this program into a file called ``example.cpp``. - -.. _unix-header-only: - -Build on \*nix --------------- - -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 - -.. |next| replace:: *next...* - -|next|__ - -__ `Errors and Warnings`_ - -Build on Windows ----------------- - -.. _`command prompt`: -.. _`command-line tool`: - -.. sidebar:: The Windows Command Prompt - :class: small - - 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: - - .. parsed-literal:: - - cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory* - - followed by Return. For example, - - .. parsed-literal:: - - cd |winroot-default| - - Long commands can be continued across several lines by typing a - caret (``^``) at the end of all but the last line. Some examples - on this page use that technique to save horizontal space. - -To build the examples in this guide, you can use an Integrated -Development Environment (IDE) like Visual Studio or you can follow -a shorter path by issuing commands from the command prompt. - -.. _vs-header-only: - -From 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, for example - - |winroot-default| - -* In *Configuration Properties* > *C/C++* > *Precompiled Headers*, change - *Use Precompiled Header (/Yu)* to *Not Using Precompiled - Headers*. [#pch]_ -* 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. - -|next|__ - -__ `Errors and Warnings`_ - - -From the 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: - -.. parsed-literal:: - - cl /EHsc /I |winroot| *path*\ \\\ *to*\ \\example.cpp - -To test the result, type: - -.. parsed-literal:: - - echo 1 2 3 | example - -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. -[#warnings]_ - -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. - -Prepare to Use a Boost Library Binary -===================================== - -If you want to use any of the separately-compiled Boost libraries, -you'll need library binaries. - -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 |winroot-default|\ ``\lib\``. - -|next|__ - -__ `Link Your Program to a Boost Library`_ - -Build and Install \*nix Binaries --------------------------------- - -Issue the following commands in the shell (don't type ``$``; it -represents the shell's prompt): - -.. parsed-literal:: - - **$** cd |root| - **$** ./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 - -.. parsed-literal:: - - **$** ./configure **--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:: - - **$** make 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|__ - -__ `Expected Build Output`_ - -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 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``. - -.. |precompiled-bjam| replace:: pre-compiled ``bjam`` executables - - -.. _precompiled-bjam: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941 -.. _Boost.Jam documentation: Boost.Jam_ -.. _Boost.Build: ../tools/build/index.html -.. _Boost.Jam: ../tools/jam/index.html -.. _Boost.Build documentation: Boost.Build_ - -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 |precompiled-bjam|_ for a variety of platforms. -Alternatively, you can build ``bjam`` yourself using `these -instructions`__. - -__ http://www.boost.org/doc/html/jam/building.html - - -.. _toolset: -.. _toolset-name: - -Identify Your Toolset -..................... - -First, find the toolset corresponding to your compiler in the -following table. - -+-----------+--------------------+-----------------------------+ -|Toolset |Vendor |Notes | -|Name | | | -+===========+====================+=============================+ -|``acc`` |Hewlett Packard |Only very recent versions are| -| | |known to work well with Boost| -+-----------+--------------------+-----------------------------+ -|``borland``|Borland | | -+-----------+--------------------+-----------------------------+ -|``como`` |Comeau Computing |Using this toolset may | -| | |require configuring__ another| -| | |toolset to act as its backend| -+-----------+--------------------+-----------------------------+ -|``cw`` |Metrowerks/FreeScale|The CodeWarrior compiler. We| -| | |have not tested versions of | -| | |this compiler produced since | -| | |it was sold to FreeScale. | -+-----------+--------------------+-----------------------------+ -|``dmc`` |Digital Mars |As of this Boost release, no | -| | |version of dmc is known to | -| | |handle Boost well. | -+-----------+--------------------+-----------------------------+ -|``darwin`` |Apple Computer |Apple's version of the GCC | -| | |toolchain with support for | -| | |Darwin and MacOS X features | -| | |such as frameworks. | -+-----------+--------------------+-----------------------------+ -|``gcc`` |The Gnu Project |Includes support for Cygwin | -| | |and MinGW compilers. | -+-----------+--------------------+-----------------------------+ -|``hp_cxx`` |Hewlett Packard |Targeted at the Tru64 | -| | |operating system. | -+-----------+--------------------+-----------------------------+ -|``intel`` |Intel | | -+-----------+--------------------+-----------------------------+ -|``kylix`` |Borland | | -+-----------+--------------------+-----------------------------+ -|``msvc`` |Microsoft | | -+-----------+--------------------+-----------------------------+ -|``qcc`` |QNX Software Systems| | -+-----------+--------------------+-----------------------------+ -|``sun`` |Sun |Only very recent versions are| -| | |known to work well with | -| | |Boost. | -+-----------+--------------------+-----------------------------+ -|``vacpp`` |IBM |The VisualAge C++ compiler. | -+-----------+--------------------+-----------------------------+ - -__ Boost.Build_ - -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. - -.. _build directory: -.. _build-directory: - -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`` -............... - -.. |build-directory| replace:: *build-directory* -.. |toolset-name| replace:: *toolset-name* - -Change your current directory to the Boost root directory and -invoke ``bjam`` as follows: - -.. parsed-literal:: - - bjam **--build-dir=**\ |build-directory|_ **--toolset=**\ |toolset-name|_ stage - -For example, on Windows, your session might look like this: [#continuation]_ - -.. parsed-literal:: - - C:\WINDOWS> cd |winroot-default| - |winroot-default|> bjam **^** - More? **--build-dir=**\ %TEMP%\\build-boost **^** - More? **--toolset=**\ msvc stage - -And on Unix: - -.. parsed-literal:: - - $ cd ~/|boost_ver| - $ bjam **--build-dir=**\ /tmp/build-boost **--toolset=**\ gcc - -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 - -In particular, to limit the amount of time spent building, you may -be interested in: - -* reviewing the list of library names with ``--show-libraries`` -* limiting which libraries get built with the ``--with-``\ - *library-name* or ``--without-``\ *library-name* options -* choosing a specific build variant by adding ``release`` or - ``debug`` to the command line. - - - -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: - - .. parsed-literal:: - - *toolset-name*.c++ *long*\ /\ *path*\ /\ *to*\ /\ *file*\ /\ *being*\ /\ *built* - -* Compiler warnings. - -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`_. - -__ file:///home/dave/src/boost/libs/iostreams/doc/installation.html - -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 - #include - #include - - 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. Identifying the library binary, among all the build variants, - whose compile configuration is compatible with the rest of your - project. - -Link to a Boost Library on Windows ----------------------------------- - -.. _auto-linking: - -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 |winroot-default|\ ``\lib``: - -.. parsed-literal:: - - cl /EHsc /I |winroot| example.cpp **^** - **/link /LIBPATH:** |bold-winroot-default|\ **\\lib** - -|next|__ - -__ `Test Your Program`_ - -Link to a Boost Library in the Visual Studio IDE -................................................ - -Starting with the `header-only example project`__ we created -earlier: - -__ vs-header-only_ - -1. Right-click **example** in the *Solution Explorer* pane and - select *Properties* from the resulting pop-up menu -2. In *Configuration Properties* > *Linker* > *Additional Library - Directories*, enter the path to the Boost binaries, - e.g. |winroot-default|\ ``\lib\``. -3. From the *Build* menu, select *Build Solution*. - -|next|__ - -__ `Test Your Program`_ - -Link to a Boost Library on \*nix --------------------------------- - -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/lib/libboost_regex-gcc-3.4-mt-d-1_34.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/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. - -In both cases above, the bold text is what you'd add to `the -command lines we explored earlier`__. - -__ unix-header-only_ - -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. [#distinct]_ - -``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: - - +-----+------------------------------------------------------------------------------+ - |Key |Use this library when: | - +=====+==============================================================================+ - |``s``|linking statically to the C++ standard library and compiler runtime support | - | |libraries. | - +-----+------------------------------------------------------------------------------+ - |``g``|using debug versions of the standard and runtime support libraries. | - +-----+------------------------------------------------------------------------------+ - |``y``|using a special `debug build of Python`__. | - +-----+------------------------------------------------------------------------------+ - |``d``|building a debug version of your code. [#debug-abi]_ | - +-----+------------------------------------------------------------------------------+ - |``p``|using the STLPort standard library rather than the default one supplied with | - | |your compiler. | - +-----+------------------------------------------------------------------------------+ - |``n``|using STLPort's deprecated “native iostreams” feature. [#native]_ | - +-----+------------------------------------------------------------------------------+ - - 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, ``.dll`` indicates a shared library - and—except for static libraries built by ``gcc`` toolset, whose - names always end in ``.a``— ``.lib`` indicates a static or import - library. Where supported by \*nix toolsets, a full version - extension is added (e.g. ".so.1.34") and a symbolic link to the - library file, named without the trailing version number, will - also be created. - -.. _Boost.Build toolset names: toolset-name_ - -__ ../libs/python/doc/building.html#variants - -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: - -.. parsed-literal:: - - *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): - -.. 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?” - -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`_. - -* `Boost.Build reference manual`_ -* `Boost.Jam reference manual`_ -* `Boost Users' mailing list`_ -* `Boost.Build mailing list`_ -* `Boost.Build Wiki`_ -* `Index of all Boost library documentation`_ -* Library-specific Configuration and Build Details - - - Boost.Python__ - - __ ../libs/python/doc/building.html - - - **Library authors need to send me the links for their - libraries** - - - -.. _Index of all Boost library documentation: ../libs/index.html - -.. Admonition:: Onward - - .. epigraph:: - - Good luck, and have fun! - - -- the Boost Developers - -.. _Boost.Build reference manual: ../tools/build/v2 -.. _Boost.Jam reference manual: `Boost.Jam`_ -.. _Boost Users' mailing list: mailing_lists.htm#users -.. _Boost.Build Wiki: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2 -.. _Boost.Build mailing list: mailing_lists.htm#jamboost - ------------------------------- - -.. [#zip] If you prefer not to download executable programs, download - |boost_ver|\ ``.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. - -.. [#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: mailing_lists.htm#main - -.. [#installer-src] 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. - -.. [#warnings] 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. - -.. [#continuation] In this example, the caret character ``^`` is a - way of continuing the command on multiple lines. The command - prompt responds with ``More?`` to prompt for more input. Feel - free to omit the carets and subsequent newlines; we used them so - the example would fit on a page of reasonable width. - -.. [#pch] 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. - -.. [#lowercase-l] That option is a dash followed by a lowercase “L” - character, which looks very much like a numeral 1 in some fonts. - -.. [#distinct] 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. - -.. [#debug-abi] These libraries were compiled without optimization - or inlining, with full debug symbols enabled, and without - ``NDEBUG`` ``#define``\ d. 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. - -.. [#native] This feature of STLPort is deprecated because it's - impossible to make it work transparently to the user; we don't - recommend it. - -.. _Boost.DateTime: ../libs/date_time/index.html -.. _Boost.Filesystem: ../libs/filesystem/index.html -.. _Boost.Graph: ../libs/graph/index.html -.. _Boost.IOStreams: ../libs/iostreams/index.html -.. _Boost.ProgramOptions: ../libs/program_options/index.html -.. _Boost.Python: ../libs/python/index.html -.. _Boost.Regex: ../libs/regex/index.html -.. _Boost.Serialization: ../libs/serialization/index.html -.. _Boost.Signals: ../libs/signals/index.html -.. _Boost.Test: ../libs/test/index.html -.. _Boost.Thread: ../libs/thread/index.html -.. _Boost.Wave: ../libs/wave/index.html diff --git a/more/getting_started/Jamfile.v2 b/more/getting_started/Jamfile.v2 new file mode 100644 index 0000000000..770aae934d --- /dev/null +++ b/more/getting_started/Jamfile.v2 @@ -0,0 +1,23 @@ +# 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) +import docutils ; + +import path ; +sources = [ path.glob . : *.rst ] ; +bases = $(sources:S=) ; + +# This is a path relative to the html/ subdirectory where the +# generated output will eventually be moved. +stylesheet = "--stylesheet=../../rst.css" ; + +for local b in $(bases) +{ + html $(b) : $(b).rst : + + "--link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet) + ; +} + +alias htmls : $(bases) ; +stage . : $(bases) ; diff --git a/more/getting_started/detail/binary-head.rst b/more/getting_started/detail/binary-head.rst new file mode 100644 index 0000000000..21f32aba72 --- /dev/null +++ b/more/getting_started/detail/binary-head.rst @@ -0,0 +1,10 @@ +.. 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) + +Prepare to Use a Boost Library Binary +===================================== + +If you want to use any of the separately-compiled Boost libraries, +you'll need to acquire library binaries. + diff --git a/more/getting_started/detail/build-from-source-head.rst b/more/getting_started/detail/build-from-source-head.rst new file mode 100644 index 0000000000..7e55da83b1 --- /dev/null +++ b/more/getting_started/detail/build-from-source-head.rst @@ -0,0 +1,123 @@ +.. 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) + +Boost.Build_ is a text-based system for developing, testing, and +installing software. To use it, you'll need an executable called +``bjam``. + +.. |precompiled-bjam| replace:: pre-compiled ``bjam`` executables + + +.. _precompiled-bjam: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941 +.. _Boost.Jam documentation: Boost.Jam_ +.. _Boost.Build: ../../tools/build/index.html +.. _Boost.Jam: ../../tools/jam/index.html +.. _Boost.Build documentation: Boost.Build_ + +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 |precompiled-bjam|_ for a variety of platforms. +Alternatively, you can build ``bjam`` yourself using `these +instructions`__. + +__ ../../doc/html/jam/building.html + + +.. _toolset: +.. _toolset-name: + +Identify Your Toolset +..................... + +First, find the toolset corresponding to your compiler in the +following table. + ++-----------+--------------------+-----------------------------+ +|Toolset |Vendor |Notes | +|Name | | | ++===========+====================+=============================+ +|``acc`` |Hewlett Packard |Only very recent versions are| +| | |known to work well with Boost| ++-----------+--------------------+-----------------------------+ +|``borland``|Borland | | ++-----------+--------------------+-----------------------------+ +|``como`` |Comeau Computing |Using this toolset may | +| | |require configuring__ another| +| | |toolset to act as its backend| ++-----------+--------------------+-----------------------------+ +|``cw`` |Metrowerks/FreeScale|The CodeWarrior compiler. We| +| | |have not tested versions of | +| | |this compiler produced since | +| | |it was sold to FreeScale. | ++-----------+--------------------+-----------------------------+ +|``dmc`` |Digital Mars |As of this Boost release, no | +| | |version of dmc is known to | +| | |handle Boost well. | ++-----------+--------------------+-----------------------------+ +|``darwin`` |Apple Computer |Apple's version of the GCC | +| | |toolchain with support for | +| | |Darwin and MacOS X features | +| | |such as frameworks. | ++-----------+--------------------+-----------------------------+ +|``gcc`` |The Gnu Project |Includes support for Cygwin | +| | |and MinGW compilers. | ++-----------+--------------------+-----------------------------+ +|``hp_cxx`` |Hewlett Packard |Targeted at the Tru64 | +| | |operating system. | ++-----------+--------------------+-----------------------------+ +|``intel`` |Intel | | ++-----------+--------------------+-----------------------------+ +|``kylix`` |Borland | | ++-----------+--------------------+-----------------------------+ +|``msvc`` |Microsoft | | ++-----------+--------------------+-----------------------------+ +|``qcc`` |QNX Software Systems| | ++-----------+--------------------+-----------------------------+ +|``sun`` |Sun |Only very recent versions are| +| | |known to work well with | +| | |Boost. | ++-----------+--------------------+-----------------------------+ +|``vacpp`` |IBM |The VisualAge C++ compiler. | ++-----------+--------------------+-----------------------------+ + +__ Boost.Build_ + +If you have multiple versions of a particular compiler installed, +you can append 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. + +.. _build directory: +.. _build-directory: + +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`` +............... + +.. |build-directory| replace:: *build-directory* +.. |toolset-name| replace:: *toolset-name* + +Change your current directory to the Boost root directory and +invoke ``bjam`` as follows: + +.. parsed-literal:: + + bjam **--build-dir=**\ |build-directory|_ **--toolset=**\ |toolset-name|_ stage diff --git a/more/getting_started/detail/build-from-source-tail.rst b/more/getting_started/detail/build-from-source-tail.rst new file mode 100644 index 0000000000..1fd88559c7 --- /dev/null +++ b/more/getting_started/detail/build-from-source-tail.rst @@ -0,0 +1,66 @@ +.. 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) + +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 + +In particular, to limit the amount of time spent building, you may +be interested in: + +* reviewing the list of library names with ``--show-libraries`` +* limiting which libraries get built with the ``--with-``\ + *library-name* or ``--without-``\ *library-name* options +* choosing a specific build variant by adding ``release`` or + ``debug`` to the command line. + +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: + + .. parsed-literal:: + + *toolset-name*.c++ *long*\ /\ *path*\ /\ *to*\ /\ *file*\ /\ *being*\ /\ *built* + +* Compiler warnings. + +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. + +__ ../../libs/iostreams/doc/installation.html + +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`_. + diff --git a/more/getting_started/detail/build-simple-head.rst b/more/getting_started/detail/build-simple-head.rst new file mode 100644 index 0000000000..487610e344 --- /dev/null +++ b/more/getting_started/detail/build-simple-head.rst @@ -0,0 +1,28 @@ +.. 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) + +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 + #include + #include + #include + + int main() + { + using namespace boost::lambda; + typedef std::istream_iterator in; + + std::for_each( + in(std::cin), in(), std::cout << (_1 * 3) << " " ); + } + +Copy the text of this program into a file called ``example.cpp``. + diff --git a/more/getting_started/detail/common-footnotes.rst b/more/getting_started/detail/common-footnotes.rst new file mode 100644 index 0000000000..e7b1fa23f8 --- /dev/null +++ b/more/getting_started/detail/common-footnotes.rst @@ -0,0 +1,26 @@ +.. 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) + +.. [#warnings] 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. + +.. [#distinct] 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. + +.. [#debug-abi] These libraries were compiled without optimization + or inlining, with full debug symbols enabled, and without + ``NDEBUG`` ``#define``\ d. 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. + +.. [#native] This feature of STLPort is deprecated because it's + impossible to make it work transparently to the user; we don't + recommend it. + diff --git a/more/getting_started/detail/common-unix.rst b/more/getting_started/detail/common-unix.rst new file mode 100644 index 0000000000..77fa0420bc --- /dev/null +++ b/more/getting_started/detail/common-unix.rst @@ -0,0 +1,21 @@ +.. 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) + +.. |//| replace:: **/** +.. |/| replace:: ``/`` + +.. |default-root| replace:: ``/usr/local/``\ |boost_ver| +.. |default-root-bold| replace:: **/usr/local/**\ |boost_ver-bold| + +.. |root| replace:: *path/to/*\ |boost_ver| + +.. |forward-slashes| replace:: `` `` + +.. |precompiled-dir| replace:: `` `` + +.. |include-paths| replace:: `` `` + +.. |command-line tool| replace:: command-line tool + +.. include:: common.rst diff --git a/more/getting_started/detail/common-windows.rst b/more/getting_started/detail/common-windows.rst new file mode 100644 index 0000000000..f7dc50e048 --- /dev/null +++ b/more/getting_started/detail/common-windows.rst @@ -0,0 +1,29 @@ +.. 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) + +.. |//| replace:: **\\** +.. |/| replace:: ``\`` + +.. |default-root| replace:: ``C:\Program Files\boost\``\ |boost_ver| +.. |default-root-bold| replace:: **C:\\Program Files\\boost\\**\ |boost_ver-bold| + +.. |root| replace:: *path\\to\\*\ |boost_ver| + +.. |include-paths| replace:: 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. + +.. |forward-slashes| replace:: Even Windows users can (and, for + portability reasons, probably should) use forward slashes in + ``#include`` directives; your compiler doesn't care. + +.. |precompiled-dir| replace:: + + **lib**\ |//| .....................\ *precompiled library binaries* + + +.. |command-line tool| replace:: `command-line tool`_ + +.. include:: common.rst diff --git a/more/getting_started/detail/common.rst b/more/getting_started/detail/common.rst new file mode 100644 index 0000000000..591c05b175 --- /dev/null +++ b/more/getting_started/detail/common.rst @@ -0,0 +1,5 @@ +.. 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) + +.. |next| replace:: *skip to the next step* diff --git a/more/getting_started/detail/conclusion.rst b/more/getting_started/detail/conclusion.rst new file mode 100644 index 0000000000..b9ee3411ea --- /dev/null +++ b/more/getting_started/detail/conclusion.rst @@ -0,0 +1,39 @@ +.. 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) + +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`_. + +* `Boost.Build reference manual`_ +* `Boost.Jam reference manual`_ +* `Boost Users' mailing list`_ +* `Boost.Build mailing list`_ +* `Boost.Build Wiki`_ +* `Index of all Boost library documentation`_ + +.. _Index of all Boost library documentation: ../../libs/index.html + +.. Admonition:: Onward + + .. epigraph:: + + Good luck, and have fun! + + -- the Boost Developers + +.. _Boost.Build reference manual: ../tools/build/v2 +.. _Boost.Jam reference manual: `Boost.Jam`_ +.. _Boost Users' mailing list: ../../more/mailing_lists.htm#users +.. _Boost.Build Wiki: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2 +.. _Boost.Build mailing list: ../../more/mailing_lists.htm#jamboost + diff --git a/more/getting_started/detail/distro.rst b/more/getting_started/detail/distro.rst new file mode 100644 index 0000000000..bf429a1009 --- /dev/null +++ b/more/getting_started/detail/distro.rst @@ -0,0 +1,88 @@ +.. 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) + +The Boost Distribution +====================== + +This is is a sketch of the directory structure you'll end up with: + +.. parsed-literal:: + + |boost_ver-bold|\ |//| .................\ *The “boost root directory”* + **index.htm** .........\ *A copy of www.boost.org starts here* + **boost**\ |//| .........................\ *All Boost Header files* + |precompiled-dir| + **libs**\ |//| ............\ *Tests, .cpp*\ s\ *, docs, etc., by library* + **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* + +.. sidebar:: Header Organization + + .. class:: pre-wrap + + The organization of Boost library headers isn't entirely uniform, + but most libraries follow a few patterns: + + * Some older libraries and most very small libraries place all + public headers directly into ``boost``\ |/|. + + * Most libraries' public headers live in a subdirectory of + ``boost``\ |/|, named after the library. For example, you'll find + the Python library's ``def.hpp`` header in + + .. parsed-literal:: + + ``boost``\ |/|\ ``python``\ |/|\ ``def.hpp``. + + * Some libraries have an “aggregate header” in ``boost``\ |/| that + ``#include``\ s all of the library's other headers. For + example, Boost.Python_'s aggregate header is + + .. parsed-literal:: + + ``boost``\ |/|\ ``python.hpp``. + + * Most libraries place private headers in a subdirectory called + ``detail``\ |/|, or ``aux_``\ |/|. Don't expect to find + anything you can use in these directories. + +It's important to note the following: + +.. _Boost root directory: + +1. The path to the **boost root directory** (often |default-root|) is + sometimes referred to as ``$BOOST_ROOT`` in documentation and + mailing lists . + +2. To compile anything in Boost, you need a directory containing + the ``boost``\ |/| subdirectory in your ``#include`` path. |include-paths| + +3. 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: + + .. parsed-literal:: + + #include + + or + + .. parsed-literal:: + + #include "boost/\ *whatever*\ .hpp" + + depending on your religion as regards the use of angle bracket + includes. |forward-slashes| + +4. 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. + diff --git a/more/getting_started/detail/errors-and-warnings.rst b/more/getting_started/detail/errors-and-warnings.rst new file mode 100644 index 0000000000..770d46eae3 --- /dev/null +++ b/more/getting_started/detail/errors-and-warnings.rst @@ -0,0 +1,16 @@ +.. 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) + +Errors and Warnings +------------------- + +Don't be alarmed if you see compiler warnings originating in Boost +headers. We try to eliminate them, but doing so isn't always +practical. [#warnings]_ **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`_. + +__ `Build a Simple Program Using Boost`_ + diff --git a/more/getting_started/detail/header-only.rst b/more/getting_started/detail/header-only.rst new file mode 100644 index 0000000000..13d7e3fd7d --- /dev/null +++ b/more/getting_started/detail/header-only.rst @@ -0,0 +1,45 @@ +.. 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) + +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. + +.. admonition:: 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. + +.. _separate: + +The only Boost libraries that *must* be built separately are: + +* Boost.Filesystem_ +* Boost.IOStreams_ +* Boost.ProgramOptions_ +* Boost.Python_ +* Boost.Regex_ +* Boost.Serialization_ +* Boost.Signals_ +* Boost.Thread_ +* Boost.Wave_ + +A few libraries have optional separately-compiled binaries: + +* Boost.DateTime_ has a binary component that is only needed if + you're using its ``to_string``\ /\ ``from_string`` or serialization + features, or if you're targeting Visual C++ 6.x or Borland. + +* Boost.Graph_ also has a binary component that is only needed if + you intend to `parse GraphViz files`__. + +* Boost.Test_ can be used in “header-only” or “separately compiled” + mode, although **separate compilation is recommended for serious + use**. + +__ ../../libs/graph/doc/read_graphviz.html diff --git a/more/getting_started/detail/library-naming.rst b/more/getting_started/detail/library-naming.rst new file mode 100644 index 0000000000..bf777a04bb --- /dev/null +++ b/more/getting_started/detail/library-naming.rst @@ -0,0 +1,80 @@ +.. 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) + +In order to choose the right binary for your build configuration +you need to know how Boost binaries are named. 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. [#distinct]_ + +``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: + + +-----+------------------------------------------------------------------------------+ + |Key |Use this library when: | + +=====+==============================================================================+ + |``s``|linking statically to the C++ standard library and compiler runtime support | + | |libraries. | + +-----+------------------------------------------------------------------------------+ + |``g``|using debug versions of the standard and runtime support libraries. | + +-----+------------------------------------------------------------------------------+ + |``y``|using a special `debug build of Python`__. | + +-----+------------------------------------------------------------------------------+ + |``d``|building a debug version of your code. [#debug-abi]_ | + +-----+------------------------------------------------------------------------------+ + |``p``|using the STLPort standard library rather than the default one supplied with | + | |your compiler. | + +-----+------------------------------------------------------------------------------+ + |``n``|using STLPort's deprecated “native iostreams” feature. [#native]_ | + +-----+------------------------------------------------------------------------------+ + + 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, ``.dll`` indicates a shared library + and—except for static libraries built by ``gcc`` toolset, whose + names always end in ``.a``— ``.lib`` indicates a static or import + library. Where supported by \*nix toolsets, a full version + extension is added (e.g. ".so.1.34") and a symbolic link to the + library file, named without the trailing version number, will + also be created. + +.. _Boost.Build toolset names: toolset-name_ + +__ ../../libs/python/doc/building.html#variants + diff --git a/more/getting_started/detail/link-head.rst b/more/getting_started/detail/link-head.rst new file mode 100644 index 0000000000..c4a59958be --- /dev/null +++ b/more/getting_started/detail/link-head.rst @@ -0,0 +1,39 @@ +.. 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) + +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 + #include + #include + + 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. Identifying the library binary, among all the build variants, + whose compile configuration is compatible with the rest of your + project. + diff --git a/more/getting_started/detail/links.rst b/more/getting_started/detail/links.rst new file mode 100644 index 0000000000..21d111000f --- /dev/null +++ b/more/getting_started/detail/links.rst @@ -0,0 +1,16 @@ +.. 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) + +.. _Boost.DateTime: ../../libs/date_time/index.html +.. _Boost.Filesystem: ../../libs/filesystem/index.html +.. _Boost.Graph: ../../libs/graph/index.html +.. _Boost.IOStreams: ../../libs/iostreams/index.html +.. _Boost.ProgramOptions: ../../libs/program_options/index.html +.. _Boost.Python: ../../libs/python/doc/building.html +.. _Boost.Regex: ../../libs/regex/index.html +.. _Boost.Serialization: ../../libs/serialization/index.html +.. _Boost.Signals: ../../libs/signals/index.html +.. _Boost.Test: ../../libs/test/index.html +.. _Boost.Thread: ../../libs/thread/index.html +.. _Boost.Wave: ../../libs/wave/index.html diff --git a/more/getting_started/detail/release-variables.rst b/more/getting_started/detail/release-variables.rst new file mode 100644 index 0000000000..c8dc919531 --- /dev/null +++ b/more/getting_started/detail/release-variables.rst @@ -0,0 +1,12 @@ +.. 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) + +.. This file contains all the definitions that need to be updated +.. for each new release of Boost. + +.. |boost-version-number| replace:: 1.34.0 +.. |boost_ver| replace:: ``boost_1_34_0`` +.. |boost_ver-bold| replace:: **boost_1_34_0** + +.. _sf-download: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=376197 \ No newline at end of file diff --git a/more/getting_started/detail/test-head.rst b/more/getting_started/detail/test-head.rst new file mode 100644 index 0000000000..90e1ce7557 --- /dev/null +++ b/more/getting_started/detail/test-head.rst @@ -0,0 +1,16 @@ +.. 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) + +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. + diff --git a/more/getting_started/index.html b/more/getting_started/index.html new file mode 100644 index 0000000000..c72e124216 --- /dev/null +++ b/more/getting_started/index.html @@ -0,0 +1,58 @@ + + + + + + +Boost Getting Started + + + +
+

Getting Started

+ + + + +
+

Welcome

+

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.

+
+
+

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.

+
+
+

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.

+
+
+

Ready?

+

Let's go!

+
+
+
+
+
+
Next: Getting Started on Microsoft Windows
+
or: Getting Started on Unix variants (e.g. Linux, MacOS)
+
+ +
+ + diff --git a/more/getting_started/index.rst b/more/getting_started/index.rst new file mode 100644 index 0000000000..23bfa7bd0b --- /dev/null +++ b/more/getting_started/index.rst @@ -0,0 +1,60 @@ +.. 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 +============================ + +.. |(logo)| image:: ../../boost.png + :alt: Boost + :class: boost-logo + +__ ../../index.htm + +Welcome +------- + +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. + +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. + +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: + +.. parsed-literal:: + + **$** echo "My name is *your name*\ " + +Here you're expected to imagine replacing the text “your name” with +your actual name. + +Ready? +------ + +Let's go! + +.. footer:: + .. class:: nextpage + + | **Next:** `Getting Started on Microsoft Windows`__ + | **or:** `Getting Started on Unix variants (e.g. Linux, MacOS)`__ + +__ windows.html +__ unix-variants.html + diff --git a/more/getting_started/unix-variants.html b/more/getting_started/unix-variants.html new file mode 100644 index 0000000000..2a2a876436 --- /dev/null +++ b/more/getting_started/unix-variants.html @@ -0,0 +1,786 @@ + + + + + + +Boost Getting Started on Unix Variants + + + + +
+

Getting Started on Unix Variants

+ + + + + +
+

Index

+ +
+
+

1   Get Boost

+

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

+
    +

  1. Download boost_1_34_0.tar.bz2.

    +
    2. +

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

    +
    +tar --bzip2 -xf /path/to/boost_1_34_0.tar.bz2
+
    +
    3. +
+
+

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

+
+ + + +
+
+

2   The Boost Distribution

+

This is is a sketch of the directory structure you'll end up with:

+
+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 library
+     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
+
+
+

Header Organization

+

The organization of Boost library headers isn't entirely uniform, +but most libraries follow a few patterns:

+
    +

  • Some older libraries and most very small libraries place all +public headers directly into boost/.

    +
    • +

  • Most libraries' public headers live in a subdirectory of +boost/, named after the library. For example, you'll find +the Python library's def.hpp header in

    +
    +boost/python/def.hpp.
+
    +
    • +

  • Some libraries have an “aggregate header” in boost/ that +#includes all of the library's other headers. For +example, Boost.Python's aggregate header is

    +
    +boost/python.hpp.
+
    +
    • +

  • Most libraries place private headers in a subdirectory called +detail/, or aux_/. Don't expect to find +anything you can use in these directories.

    +
    • +
+
+

It's important to note the following:

+
    +

  1. The path to the boost root directory (often /usr/local/boost_1_34_0) is +sometimes referred to as $BOOST_ROOT in documentation and +mailing lists .

    +
    2. +

  2. To compile anything in Boost, you need a directory containing +the boost/ subdirectory in your #include path.

    +
    3. +

  3. 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"
+
    +

    depending on your religion as regards the use of angle bracket +includes.

    +
    4. +

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

    +
    5. +
+ + + +
+
+

3   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 must be built separately are:

+ +

A few libraries have optional separately-compiled binaries:

+
    +
  • Boost.DateTime has a binary component that is only needed if +you're using its to_string/from_string or serialization +features, or if you're targeting Visual C++ 6.x or Borland.
    • +
  • Boost.Graph also has a binary component that is only needed if +you intend to parse GraphViz files.
    • +
  • Boost.Test can be used in “header-only” or “separately compiled” +mode, although separate compilation is recommended for serious +use.
    • +
+ + + +
+
+

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

+

Now, 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
+
+ + + +
+

4.1   Errors and Warnings

+

Don't be alarmed if you see compiler warnings originating in Boost +headers. We try to eliminate them, but doing so isn't always +practical.3 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.

+ + + +
+
+
+

5   Prepare to Use a Boost Library Binary

+

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

+
+

5.1   Easy Build and Install

+

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

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

Select your configuration options and invoke ./configure 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

+
+$ ./configure --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,

+
+$ make 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.

+

skip to the next step

+
+
+

5.2   Or, Custom Build and Install

+

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

+ + + +

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

+
+

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

+
+
+

5.2.2   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 append 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.

+
+
+
+

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

+
+
+

5.2.4   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, your session might look like this:

+
+$ cd ~/boost_1_34_0
+$ bjam --build-dir=/tmp/build-boost --toolset=gcc
+
+ + + +

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
+
+

In particular, to limit the amount of time spent building, you may +be interested in:

+
    +
  • reviewing the list of library names with --show-libraries
    • +
  • limiting which libraries get built with the --with-library-name or --without-library-name options
    • +
  • choosing a specific build variant by adding release or +debug to the command line.
    • +
+
+
+
+

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

    +
    • +
+
+
+

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

+ + + +
+
+
+

6   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. +
  2. Identifying the library binary, among all the build variants, +whose compile configuration is compatible with the rest of your +project.
    3. +
+

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

  2. You can separately specify a directory to search (with -Ldirectory) and a library name to search for (with -llibrary,2 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.

    +
    3. +
+

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

+
+

6.1   Library Naming

+ + + +

In order to choose the right binary for your build configuration +you need to know how Boost binaries are named. 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.4
+
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.5
pusing the STLPort standard library rather than the default one supplied with +your compiler.
nusing STLPort's deprecated “native iostreams” feature.6
+
+

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, .dll indicates a shared library +and—except for static libraries built by gcc toolset, whose +names always end in .a``— ``.lib indicates a static or import +library. Where supported by *nix toolsets, a full version +extension is added (e.g. ".so.1.34") and a symbolic link to the +library file, named without the trailing version number, will +also be created.
+
+ + + +
+
+

6.2   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.
+
+

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

+ + + +
+
+
+

7   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

+
+
+
+ + + + + +
[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.
+ + + + + + + + +
[3]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.
+ + + + + +
[4]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.
+ + + + + +
[5]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.
+ + + + + +
[6]This feature of STLPort is deprecated because it's +impossible to make it work transparently to the user; we don't +recommend it.
+ + + + + + + + + + + + + + +
+
+ + diff --git a/more/getting_started/unix-variants.rst b/more/getting_started/unix-variants.rst new file mode 100644 index 0000000000..6924468c96 --- /dev/null +++ b/more/getting_started/unix-variants.rst @@ -0,0 +1,236 @@ +.. 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| + **$** ./configure --help + +Select your configuration options and invoke ``./configure`` 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:: + + **$** ./configure **--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:: + + **$** make 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, Custom Build and Install +---------------------------- + +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 + +.. 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/lib/libboost_regex-gcc-3.4-mt-d-1_34.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/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. + +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: ../../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. + +.. include:: detail/common-footnotes.rst +.. include:: detail/release-variables.rst +.. include:: detail/common-unix.rst +.. include:: detail/links.rst diff --git a/more/getting_started/windows.html b/more/getting_started/windows.html new file mode 100644 index 0000000000..8d7b7952b7 --- /dev/null +++ b/more/getting_started/windows.html @@ -0,0 +1,876 @@ + + + + + + +Boost Getting Started on Windows + + + +
+

Getting Started on Windows

+ + + + +
+

A note to Cygwin and MinGW users

+

If you plan to use your tools from the Windows command prompt, +you're in the right place. If you plan to build from the Cygwin +bash shell, you're actually running on a POSIX platform and +should follow the instructions for getting started on Unix +variants. Other command shells, such as MinGW's MSYS, are +not supported—they may or may not work.

+
+
+

Index

+ +
+
+

1   Get Boost

+

The easiest way to get a copy of Boost is to use the installer +provided by Boost Consulting. We especially recommend this +method if you use Microsoft Visual Studio .NET 2003 or Microsoft +Visual Studio 2005, because the installer can download and install +precompiled library binaries, saving you the trouble of building +them yourself. To complete this tutorial, you'll need to at least +install the Boost.Regex binaries when given the option.

+

If you're using an earlier version of Visual Studio or some other +compiler, or if you prefer to build everything yourself, you can +download boost_1_34_0.exe and run it to install a complete Boost +distribution.1

+ + + +
+
+

2   The Boost Distribution

+

This is is a sketch of the directory structure you'll end up with:

+
+boost_1_34_0\ .................The “boost root directory”
+   index.htm .........A copy of www.boost.org starts here
+   boost\ .........................All Boost Header files
+   lib\ .....................precompiled library binaries
+   libs\ ............Tests, .cpps, docs, etc., by library
+     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
+
+
+

Header Organization

+

The organization of Boost library headers isn't entirely uniform, +but most libraries follow a few patterns:

+
    +

  • Some older libraries and most very small libraries place all +public headers directly into boost\.

    +
    • +

  • Most libraries' public headers live in a subdirectory of +boost\, named after the library. For example, you'll find +the Python library's def.hpp header in

    +
    +boost\python\def.hpp.
+
    +
    • +

  • Some libraries have an “aggregate header” in boost\ that +#includes all of the library's other headers. For +example, Boost.Python's aggregate header is

    +
    +boost\python.hpp.
+
    +
    • +

  • Most libraries place private headers in a subdirectory called +detail\, or aux_\. Don't expect to find +anything you can use in these directories.

    +
    • +
+
+

It's important to note the following:

+
    +

  1. The path to the boost root directory (often C:\Program Files\boost\boost_1_34_0) is +sometimes referred to as $BOOST_ROOT in documentation and +mailing lists .

    +
    2. +

  2. To compile anything in Boost, you need a directory containing +the boost\ subdirectory in your #include path. 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.

    +
    3. +

  3. 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"
+
    +

    depending on your religion as regards the use of angle bracket +includes. Even Windows users can (and, for +portability reasons, probably should) use forward slashes in +#include directives; your compiler doesn't care.

    +
    4. +

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

    +
    5. +
+ + + +
+
+

3   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 must be built separately are:

+ +

A few libraries have optional separately-compiled binaries:

+
    +
  • Boost.DateTime has a binary component that is only needed if +you're using its to_string/from_string or serialization +features, or if you're targeting Visual C++ 6.x or Borland.
    • +
  • Boost.Graph also has a binary component that is only needed if +you intend to parse GraphViz files.
    • +
  • Boost.Test can be used in “header-only” or “separately compiled” +mode, although separate compilation is recommended for serious +use.
    • +
+ + + +
+
+

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

+
+

Note

+

To build the examples in this guide, you can use an +Integrated Development Environment (IDE) like Visual Studio, or +you can issue commands from the command prompt. Since every +IDE and compiler has different options and Microsoft's are by +far the dominant compilers on Windows, we only give specific +directions here for Visual Studio 2005 and .NET 2003 IDEs and +their respective command prompt compilers (using the command +prompt is a bit simpler). If you are using another compiler or +IDE, it should be relatively easy to adapt these instructions to +your environment.

+
+
+

Command Prompt Basics

+

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 a generic 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
+
+

Long commands can be continued across several lines by typing a +caret (^) at the end of all but the last line. Some examples +on this page use that technique to save horizontal space.

+
+
+

4.1   Build From 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, for example

    +
    +

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

    +
    • +

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

+

skip to the next step

+
+
+

4.2   Or, Build From the 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, set the current +directory to a suitable location for creating some temporary +files and type the following command followed by the Return key:

+
+cl /EHsc /I path\to\boost_1_34_0 path\to\example.cpp
+
+

To test the result, type:

+
+echo 1 2 3 | example
+
+ + + +
+
+

4.3   Errors and Warnings

+

Don't be alarmed if you see compiler warnings originating in Boost +headers. We try to eliminate them, but doing so isn't always +practical.5 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.

+ + + +
+
+
+

5   Prepare to Use a Boost Library Binary

+

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

+
+

5.1   Install Visual Studio (2005 or .NET 2003) Binaries

+

The 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\. If you installed +all variants of the Boost.Regex binary, you're done with this +step. Otherwise, please run the installer again and install them +now.

+

skip to the next step

+
+
+

5.2   Or, Build and Install Binaries From Source

+

If you're using an earlier version of Visual C++, or a compiler +from another vendor, 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.

+
+

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

+
+
+

5.2.2   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 append 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.

+
+
+
+

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

+
+
+

5.2.4   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, your session might look like this:4

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

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
+
+

In particular, to limit the amount of time spent building, you may +be interested in:

+
    +
  • reviewing the list of library names with --show-libraries
    • +
  • limiting which libraries get built with the --with-library-name or --without-library-name options
    • +
  • choosing a specific build variant by adding release or +debug to the command line.
    • +
+
+
+
+

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

    +
    • +
+
+
+

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

+ + + +
+
+
+

6   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. +
  2. Identifying the library binary, among all the build variants, +whose compile configuration is compatible with the rest of your +project.
    3. +
+
+

Auto-Linking

+

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.

+
+
+

6.1   Link From Within 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. +
  2. 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\.
    3. +
  3. From the Build menu, select Build Solution.
    4. +
+

skip to the next step

+
+
+

6.2   Or, Link From the 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
+
+
+

Note

+

If—like Visual C++—your compiler supports auto-linking, +you can probably ignore the next section.

+

skip to the next step

+
+
+
+

6.3   Library Naming

+
+

Note

+

If, like Visual C++, your compiler supports auto-linking, +you can probably skip to the next step.

+
+
+
+ + + +

In order to choose the right binary for your build configuration +you need to know how Boost binaries are named. 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.6
+
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.7
pusing the STLPort standard library rather than the default one supplied with +your compiler.
nusing STLPort's deprecated “native iostreams” feature.8
+
+

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, .dll indicates a shared library +and—except for static libraries built by gcc toolset, whose +names always end in .a``— ``.lib indicates a static or import +library. Where supported by *nix toolsets, a full version +extension is added (e.g. ".so.1.34") and a symbolic link to the +library file, named without the trailing version number, will +also be created.
+
+ + + +
+
+

6.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.
+
+

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

+ + + +
+
+
+

7   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

+
+
+
+ + + + + +
[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 you used the 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.
+ + + + + +
[3]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.
+ + + + + +
[4]In this example, the caret character ^ is a +way of continuing the command on multiple lines. The command +prompt responds with More? to prompt for more input. Feel +free to omit the carets and subsequent newlines; we used them so +the example would fit on a page of reasonable width.
+ + + + + + + + +
[5]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.
+ + + + + +
[6]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.
+ + + + + +
[7]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.
+ + + + + +
[8]This feature of STLPort is deprecated because it's +impossible to make it work transparently to the user; we don't +recommend it.
+ + + + + + + + + + + + + + +
+
+ + diff --git a/more/getting_started/windows.rst b/more/getting_started/windows.rst new file mode 100644 index 0000000000..0c820fd9b0 --- /dev/null +++ b/more/getting_started/windows.rst @@ -0,0 +1,315 @@ +.. 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 Windows +======================================= + +.. |(logo)| image:: ../../boost.png + :alt: Boost + :class: boost-logo + +__ ../../index.htm + +.. section-numbering:: + +.. Admonition:: A note to Cygwin_ and MinGW_ users + + If you plan to use your tools from the Windows command prompt, + you're in the right place. If you plan to build from the Cygwin_ + bash shell, you're actually running on a POSIX platform and + should follow the instructions for `getting started on Unix + variants`_. Other command shells, such as MinGW_\ 's MSYS, are + not supported—they may or may not work. + + .. _`Getting Started on Unix Variants`: unix-variants.html + .. _Cygwin: http://www.cygwin.com + .. _MinGW: http://mingw.org + +.. Contents:: Index + +Get Boost +========= + +The easiest way to get a copy of Boost is to use the `installer`_ +provided by `Boost Consulting`_. We especially recommend this +method if you use Microsoft Visual Studio .NET 2003 or Microsoft +Visual Studio 2005, because the installer can download and install +precompiled library binaries, saving you the trouble of building +them yourself. To complete this tutorial, you'll need to at least +install the Boost.Regex_ binaries when given the option. + +.. _installer: http://www.boost-consulting.com/download/windows +.. _Boost Consulting: http://www.boost-consulting.com + +If you're using an earlier version of Visual Studio or some other +compiler, or if you prefer to build everything yourself, you can +download |boost.exe|_ and run it to install a complete Boost +distribution. [#zip]_ + +.. |boost.exe| replace:: |boost_ver|\ ``.exe`` + +.. _`boost.exe`: `sf-download`_ + +.. include:: detail/distro.rst + +.. include:: detail/header-only.rst + +.. include:: detail/build-simple-head.rst + +.. _`command prompt`: +.. _`command-line tool`: + +.. Note:: To build the examples in this guide, you can use an + Integrated Development Environment (IDE) like Visual Studio, or + you can issue commands from the `command prompt`_. Since every + IDE and compiler has different options and Microsoft's are by + far the dominant compilers on Windows, we only give specific + directions here for Visual Studio 2005 and .NET 2003 IDEs and + their respective command prompt compilers (using the command + prompt is a bit simpler). If you are using another compiler or + IDE, it should be relatively easy to adapt these instructions to + your environment. + +.. sidebar:: Command Prompt Basics + :class: small + + 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 a generic *Command Prompt*, click the *Start* menu + button, click *Run*, type “cmd”, and then click *OK*. + + .. _current directory: + + All commands are executed within the context of a **current + directory** in the filesystem. To set the current directory, + type: + + .. parsed-literal:: + + cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory* + + followed by Return. For example, + + .. parsed-literal:: + + cd |default-root| + + Long commands can be continued across several lines by typing a + caret (``^``) at the end of all but the last line. Some examples + on this page use that technique to save horizontal space. + +.. _vs-header-only: + +Build From 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, for example + + |default-root| + +* In *Configuration Properties* > *C/C++* > *Precompiled Headers*, change + *Use Precompiled Header (/Yu)* to *Not Using Precompiled + Headers*. [#pch]_ +* 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. + +|next|__ + +__ `Errors and Warnings`_ + +Or, Build From the 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, set the `current +directory`_ to a suitable location for creating some temporary +files and type the following command followed by the Return key: + +.. parsed-literal:: + + cl /EHsc /I |root| *path*\ \\\ *to*\ \\example.cpp + +To test the result, type: + +.. parsed-literal:: + + echo 1 2 3 | example + +.. include:: detail/errors-and-warnings.rst + +.. include:: detail/binary-head.rst + +Install Visual Studio (2005 or .NET 2003) Binaries +-------------------------------------------------- + +The installer_ supplied by Boost Consulting will download and +install pre-compiled binaries into the ``lib\`` subdirectory of the +boost root, typically |default-root|\ ``\lib\``. If you installed +all variants of the Boost.Regex_ binary, you're done with this +step. Otherwise, please run the installer again and install them +now. + +|next|__ + +__ `Link Your Program to a Boost Library`_ + +Or, Build and Install Binaries From Source +------------------------------------------ + +If you're using an earlier version of Visual C++, or a compiler +from another vendor, you'll need to use Boost.Build_ to create your +own binaries. + +.. include:: detail/build-from-source-head.rst + +For example, your session might look like this: [#continuation]_ + +.. parsed-literal:: + + C:\WINDOWS> cd |default-root| + |default-root|> bjam **^** + More? **--build-dir=**\ %TEMP%\\build-boost **^** + More? **--toolset=**\ msvc stage + +.. include:: detail/build-from-source-tail.rst + +.. include:: detail/link-head.rst + +.. Admonition:: Auto-Linking + + 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 From Within the Visual Studio IDE +-------------------------------------- + +Starting with the `header-only example project`__ we created +earlier: + +__ vs-header-only_ + +1. Right-click **example** in the *Solution Explorer* pane and + select *Properties* from the resulting pop-up menu +2. In *Configuration Properties* > *Linker* > *Additional Library + Directories*, enter the path to the Boost binaries, + e.g. |default-root|\ ``\lib\``. +3. From the *Build* menu, select *Build Solution*. + +|next|__ + +__ `Test Your Program`_ + +Or, Link From the 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 |default-root|\ ``\lib``: + +.. parsed-literal:: + + cl /EHsc /I |root| example.cpp **^** + **/link /LIBPATH:** |default-root-bold|\ **\\lib** + + +.. Note:: If—like Visual C++—your compiler supports auto-linking, + you can probably ignore the next section. + + |next|__ + + __ `Test Your Program`_ + +Library Naming +-------------- + +.. Note:: If, like Visual C++, your compiler supports auto-linking, + you can probably |next|__. + + __ `Test Your Program`_ + +.. include:: detail/library-naming.rst + +.. include:: detail/test-head.rst + +Now, in a `command prompt`_ window, type: + +.. 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 + +------------------------------ + +.. [#zip] If you prefer not to download executable programs, + download |boost.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. + +.. [#installer-src] If you used the 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. + +.. [#pch] 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. + +.. [#continuation] In this example, the caret character ``^`` is a + way of continuing the command on multiple lines. The command + prompt responds with ``More?`` to prompt for more input. Feel + free to omit the carets and subsequent newlines; we used them so + the example would fit on a page of reasonable width. + +.. |boost.zip| replace:: |boost_ver|\ ``.zip`` + +.. _`boost.zip`: `sf-download`_ + + +.. include:: detail/common-footnotes.rst +.. include:: detail/release-variables.rst +.. include:: detail/common-windows.rst +.. include:: detail/links.rst