From 4cc371f9821966adb79d3de96c68cb4003909781 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Mon, 11 Dec 2006 05:16:00 +0000 Subject: [PATCH 01/15] specify unified diffs rather than context diffs [SVN r36325] --- bugs.htm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bugs.htm b/bugs.htm index 7c1ce18..bb85a8d 100644 --- a/bugs.htm +++ b/bugs.htm @@ -64,7 +64,7 @@ a bug in the file intentional_bug.hpp:
  • Make sure that the bug is still present in the code.
  • Copy the file intentional_bug.hpp to a file called intentional_bug.hpp.orig.
  • Apply your changes to intentional_bug.hpp.
    • -
  • Run "diff -c intentional_bug.hpp.orig intentional_bug.hpp > intentional_bug.hpp.patch" from the command prompt.
    • +
  • Run "diff -du intentional_bug.hpp.orig intentional_bug.hpp > intentional_bug.hpp.patch" from the command prompt.
  • Submit the patch file together with an explanation of the bug and the proposed fix; and don't forget to include the word patch or bug in the subject if you're submitting to the boost mailing list.
    From 8d3aebdf61310236efc3df957f01af99032dd84d Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Mon, 11 Dec 2006 20:38:41 +0000 Subject: [PATCH 02/15] Massive overhaul of Getting Started guide. [SVN r36333] --- getting_started.html | 697 ++++++++++++++++++++++++------------------ getting_started.rst | 700 ++++++++++++++++++++++++++----------------- 2 files changed, 834 insertions(+), 563 deletions(-) diff --git a/getting_started.html b/getting_started.html index 3cab7ff..01f0d0c 100644 --- a/getting_started.html +++ b/getting_started.html @@ -4,109 +4,142 @@ -Getting Started With Boost Boost +Boost Getting Started -
  • 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 +example, Boost.Python's aggregate header is boost/python.hpp.
  • Most libraries place private headers in a subdirectory called detail/ or aux_/. Don't look in these directories and @@ -177,21 +210,23 @@ contains a subset of the Boost documentation. Start with
    -

    3   Building a Simple Boost Program

    +

    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.

    -
    -

    Header-Only Libraries

    -

    Nearly all Boost libraries are header-only. That is, most -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 are not header-only are:

    +
    +

    Nothing to Build

    +

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

    +
    +

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

    • Boost.Filesystem
    • Boost.IOStreams
    • Boost.ProgramOptions
      • -
    • Boost.Python
      • +
    • Boost.Python
    • Boost.Regex
    • Boost.Serialization
    • Boost.Signals
      • @@ -199,16 +234,20 @@ or special treatment when linking.

    • Boost.Thread
    • Boost.Wave
    -

    The DateTime library has a separately-compiled -binary which is only needed if you're using a “legacy -compiler”(such as?). The Graph library has a -separately-compiled binary, but you won't need it unless you -intend to parse GraphViz files.

    -
    +

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

    -

    The following program reads a sequence of integers from standard -input, uses Boost.Lambda (a header-only library) to multiply each -one by three, and writes them to standard output:

    +
    +
    +

    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>
@@ -224,45 +263,45 @@ int main()
         in(std::cin), in(), std::cout << (_1 * 3) << " " );
 }
    -

    Start by copying the text of this program into a file called -example.cpp.

    +

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

    -

    3.1   *nix (e.g. Unix, Linux, MacOS, Cygwin)

    -

    Simply issue the following command ($ represents the -prompt issued by the shell, so don't type that):

    +

    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
+c++ -I /path/to/boost_1_34_0 example.cpp -o example

    To test the result, type:

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

    next...

    -

    3.2   Microsoft Windows Command-Line using Visual C++

    -

    From your computer's Start menu, select if you are a Visual +

    5.2   Build from the Visual Studio Command Prompt

    +

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

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

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

    +

    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 +

    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 (C:\PROMPT> represents the prompt issued by -the shell, so don't type that):

    +hit the return key:

    -C:PROMPT> cl /EHsc /I C:\path\to\boost_1_34_0 example.cpp
+cl /EHsc /Ipath\to\boost_1_34_0 path\to\example.cpp

    To test the result, type:

    -C:PROMPT> echo 1 2 3 | example
+echo 1 2 3 | example
    +

    next...

    -

    3.3   Visual Studio .NET 2003 or Visual Studio 2005

    +

    5.3   Build in the Visual Studio IDE

    • From Visual Studio's File menu, select New > Project…
    • In the left-hand pane of the resulting New Project dialog, @@ -277,7 +316,7 @@ Directories, enter the path to the Boost root directory, e.g. C:\Program Files\boost\boost_1_34_0.
    • In Configuration Properties > C/C++ > Precompiled Headers, change Use Precompiled Header (/Yu) to Not Using Precompiled -Headers.3
      • +Headers.5
    • Replace the contents of the example.cpp generated by the IDE with the example code above.
    • From the Build menu, select Build Solution.
      • @@ -291,26 +330,30 @@ into the resulting window, followed by the return key:

      return key.

    -

    3.4   Other Compilers/Environments

    -

    Consult your vendor's documentation; if you have trouble adapting -these instructions to your build environment, request assistance on -the Boost Users' mailing list.

    +

    5.4   Errors and Warnings

    +

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

    +

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

    -

    4   Getting Boost Library Binaries

    +

    6   Get Boost Library Binaries

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

    +you'll need library binaries.

    -

    4.1   Microsoft Visual C++ 8.0 or 7.1 (Visual Studio 2005/.NET 2003) 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...

    -

    4.2   *nix (e.g. Unix, Linux, MacOS, Cygwin) Binaries

    -

    Issue the following commands in the shell (again, $ represents -the shell's prompt):

    +

    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
@@ -330,71 +373,29 @@ 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...
    -

    4.3   Other Compilers/Environments

    +

    6.3   Build and Install Other Binaries

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

    -
    +

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

    -

    4.4   Building Boost Binaries with Boost.Build

    -

    Like an IDE, Boost.Build is a system for developing, testing, and -installing software. Instead of using a GUI, though, Boost.Build -is text-based, like make. Boost.Build is written in the -interpreted Boost.Jam language.

    -

    To use Boost.Build, you'll need an executable called bjam, the -Boost.Jam interpreter.

    - -
    -

    4.4.1   Getting bjam

    -
    -

    Using command-line tools in Windows

    -

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

    -

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

    -

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

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

    followed by Return. For example,

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

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

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

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

    -

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

    -
    +

    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 the -instructions given in the Boost.Jam documentation.

    -

    bjam is a command-line tool. To build Boost binaries, you'll -invoke bjam with the current directory set to the Boost root, -and with options described in the following sections.

    +Alternatively, you can build bjam yourself using these +instructions.

    -

    4.4.2   Identify Your Toolset

    +

    Identify Your Toolset

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

    @@ -439,9 +440,17 @@ it was sold to FreeScale. version of dmc is known to handle Boost well. + + + + - + @@ -466,7 +475,9 @@ operating system. - + @@ -486,7 +497,7 @@ toolset from the table.

    -

    4.4.3   Select a 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 @@ -494,78 +505,80 @@ default Boost.Build will create a

    -

    4.4.4   Invoke bjam

    +

    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
+bjam --build-dir=build-directory \
+     --toolset=toolset-name stage

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

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

    And on Unix:

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

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

    Note

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

    -

    And on Unix:

    +

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

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

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

    -
    -
    -

    4.4.5   stage

    -

    You already have the Boost headers on your system (in the -boost/ subdirectory of your Boost distribution), so if you -prefer not to create an additional copy, instead of installing -Boost you can simply “stage” the Boost binaries, which leaves them -in the stage/ subdirectory of your chosen build directory:

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

    4.4.6   Select a Prefix Directory

    -

    Choose a prefix directory. The installation process will -leave you with the following subdirectories of the prefix directory:

    -
      -
    • lib, containing the Boost binaries
      • -
    • include/boost_1_34_0, containing the Boost headers.
      • +

      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.

        +
      -

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

      -
      -bjam --build-dir=build-directory   \
-     --toolset=toolset-name        \
-      --prefix=prefix-directory install
-
      -

      For example, on Windows your session might look like:

      -
      -C:WINDOWS> cd C:\Program Files\boost\boost_1_34_0
-C:\Program Files\boost\boost_1_34_0> bjam   \
-    --build-dir=C:\TEMP\build-boost         \
-    --prefix=C:\boost
-
      -

      And on Unix:

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

    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.

    -

    5   Linking A Program with a Boost Library

    +

    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 @@ -585,7 +598,7 @@ int main() std::getline(std::cin, line); boost::smatch matches; if (boost::regex_match(line, matches, pat)) - std::cout << matches[2]; + std::cout << matches[2] << std::endl; } } @@ -597,46 +610,35 @@ build settings. whose compile configuration is compatible with the rest of your project. +

    +

    Note

    +

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

    +
    -

    5.1   Microsoft Windows

    -

    Most Windows compilers and linkers have so called “auto-linking +

    7.1   Link to a Boost Library on Windows

    +

    Most Windows compilers and linkers have so called “auto-linking support,” which is used by many Boost libraries to eliminate 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.

    -
    -

    Note

    -

    As of this writing, a few Boost libraries don't support -auto-linking:

    -
      -
    • Boost.Python
      • -
    • …others?…
      • -
    -
    -

    5.1.1   Visual C++ Command Line

    +

    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:

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

    To link with a library that doesn't use auto-linking support, you -need to specify the library name. For example,

    -
    -C:PROMPT> cl /EHsc /I C:\path\to\boost_1_34_0 example.cpp   \
-     /link /LIBPATH: C:\Program Files\boost\boost_1_34_0    \
-     boost_regex-msvc-7.1-mt-d-1_34.lib
-
    -

    See Library Naming for details about how to select the right -library name.

    +

    next...

    -

    5.1.2   Visual Studio IDE

    +

    Link to a Boost Library in the Visual Studio IDE

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

      @@ -647,61 +649,56 @@ Directories, enter the path to the Boost binaries, e.g. C:\Program Files\boost\boost_1_34_0\lib\.
    1. From the Build menu, select Build Solution.
    -

    To link with a library that doesn't use auto-linking support, -before building (step 3 above), you also need to specify the library -name:

    -
      -
    • In Configuration Properties > Linker > Input > -Additional Dependencies, enter the name of the binary library -to link with, e.g. boost_regex-msvc-7.1-mt-d-1_34.lib.
      • -
    -

    See Library Naming for details about how to select the right -library name.

    +

    next...

    -

    5.2   *nix (e.g. Unix, Linux, MacOS, Cygwin)

    +

    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-msvc-7.1-mt-d-1_34.a
+   ~/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,4 dropping the filename's leading lib and trailing +

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

         $ c++ -I /path/to/boost_1_34_0 example.cpp -o example \
-   -L~/boost/lib/ -lboost_regex-msvc-7.1-mt-d-1_34
+   -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.

        +

        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.

    -

    5.3   Library Naming

    -

    In order to choose the right library binary to link with, you'll -need to know something about how Boost libraries are named. Each -library binary filename is composed of a common sequence of -elements that describe how it was built. For example, -libboost_regex-msvc-7.1-mt-d-1_34.lib can be broken down into the +

    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.5
    +not.7
    boost_regex
    Library name: all boost library filenames begin with boost_.
    -
    -msvc-7.1
    -
    Toolset tag: one of the Boost.Build toolset names, -possibly followed by a dash and a version number.
    +
    -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 @@ -733,14 +730,14 @@ libraries.
    - + - +
    darwinApple ComputerApple'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
    sun Sun Only very recent versions are +known to work well with +Boost.
    vacpp IBM using a special debug build of Python.
    dbuilding a debug version of your code.6building a debug version of your code.8
    p using the STLPort standard library rather than the default one supplied with your compiler.
    nusing STLPort's deprecated “native iostreams” feature.7using STLPort's deprecated “native iostreams” feature.9
    @@ -751,10 +748,9 @@ the tag would be: -sgdpn
    -1_34
    -
    Version tag: the full Boost release number, -with periods replaced by underscores. The major and minor version -numbers are taken together separated by an underscore. For -example, version 1.31.1 would be tagged as "-1_31_1".
    +
    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 Windows, .dll @@ -766,11 +762,118 @@ full version extension is added (e.g. ".so.1.34"); a symbolic link to the library file, named without the trailing version number, will also be created.
    +
    +
    +

    7.4   Test Your Program

    +

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

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

    Test Your Program on Microsoft Windows

    +

    In a command prompt window, type:

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

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

    +
    +
    +

    Test Your Program on *nix

    +

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

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

    On csh and tcsh, it's

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

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

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

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

    +
    +
    +
    +
    +

    8   Further Resources

    +

    This concludes your introduction to Boost and using it with your +programs. Remember that this page is only supposed to get you +started and not describe every detail you might want to know about. +There are lots of resources you can pursue from this point onward. +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.

    + +
    +

    Note

    +

    We're also very interested in what sort of material might +be appropriate for a “Book 2” in a Getting Started series.

    +
    +
    +
    +

    9   Appendix: Using command-line tools in Windows

    +

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

    +

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

    +

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

    +
    +cd path\to\some\directory
+
    +

    followed by Return. For example,

    +
    +cd C:\Program Files\boost\boost_1_34_0
+
    +

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

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

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

    +

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

    + + + + + +
    [1]If you prefer not to download executable programs, download +boost_1_34_0.zip and use an external tool to decompress +it. We don't recommend using Windows' built-in decompression as +it can be painfully slow for large archives.
    - @@ -779,17 +882,28 @@ to the Boost developers' list
    [1]If developers of Boost packages would like to work +
    [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.
    -
    [2]If you used the Windows installer from Boost +
    [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.
    - @@ -798,14 +912,14 @@ used in the examples.
    [3]There's no problem using Boost with precompiled headers; +
    [5]There's no problem using Boost with precompiled headers; these instructions merely avoid precompiled headers because it would require Visual Studio-specific changes to the source code used in the examples.
    -
    [4]That option is a dash followed by a lowercase “L” +
    [6]That option is a dash followed by a lowercase “L” character, which looks very much like a numeral 1 in some fonts.
    - @@ -814,7 +928,7 @@ same name.
    [5]This convention distinguishes the static version of +
    [7]This convention distinguishes the static version of a Boost library from the import library for an identically-configured Boost DLL, which would otherwise have the same name.
    -
    [6]These libraries were compiled without optimization +
    [8]These libraries were compiled without optimization or inlining, with full debug symbols enabled, and without NDEBUG #defined. All though it's true that sometimes these choices don't affect binary compatibility with other @@ -824,18 +938,17 @@ compiled code, you can't count on that with Boost libraries.
    -
    [7]This feature of STLPort is deprecated because it's +
    [9]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-11-20 13:06 UTC. +Generated on: 2006-12-11 20:27 UTC. Generated by Docutils from reStructuredText source.
    diff --git a/getting_started.rst b/getting_started.rst index 6f31455..6cb0fe2 100644 --- a/getting_started.rst +++ b/getting_started.rst @@ -1,19 +1,20 @@ -======================================== - Getting Started With Boost |(logo)|__ -======================================== +============================ + |(logo)|__ Getting Started +============================ .. |(logo)| image:: ../boost.png :alt: Boost + :class: boost-logo __ ../index.htm -This guide will help you get started using the Boost libraries. -Have fun! .. section-numbering:: + :depth: 2 -.. contents:: Index - +.. contents:: Contents + :depth: 2 + :class: sidebar small .. ## Update this substitution for each release @@ -21,34 +22,84 @@ Have fun! .. |boost_ver-bold| replace:: **boost_1_34_0** .. |root| replace:: ``/``\ *path*\ ``/``\ *to*\ ``/``\ |boost_ver| -.. |winroot| replace:: *C:*\ ``\``\ *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| -Getting Boost -============= +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 +========= There are basically three ways to get Boost on your system: -1. Download and run the `Windows installer`_ supplied by Boost - Consulting (not available for Boost alpha/beta releases). +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. -.. ## remove the parenthesized note for full releases -.. _Windows installer: http://www.boost-consulting.com/download.html + .. _Windows installer: http://www.boost-consulting.com/download.html + .. |Windows installer| replace:: **Windows installer** + .. _Boost Consulting: http://boost-consulting.com + .. _installer: `Windows installer`_ -2. or, `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 +2. **Download**: users of other platforms—and Windows + users who prefer to build everything from scratch—can `download + a complete Boost distribution`__ from SourceForge. - :Windows users: |boost_ver|\ ``.exe`` is a program you can - run to unpack the distribution; if you prefer not to download - executable programs, get |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. + .. ## Update this link for each release + __ http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=376197 - :\*nix users: Download |boost_ver|\ ``.tar.bz2``, then, in the + - **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 @@ -56,11 +107,11 @@ __ http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&re tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2 -3. or use a Boost package from RedHat, Debian, or some other - distribution packager. These instructions may not work for you - if you use this method, because other packagers sometimes choose - to break Boost up into several packages or to reorganize the - directory structure of the Boost distribution. [#packagers]_ +3. **Boost packages** from RedHat, Debian, or some other + distribution packager: these instructions may not work for you + if you use 3rd party packages, because other packagers sometimes + choose to break Boost up into several packages or to reorganize + the directory structure of the Boost distribution. [#packagers]_ The Structure of a Boost Distribution ===================================== @@ -71,8 +122,8 @@ slashes with backslashes): .. parsed-literal:: - **boost_1_34_0/** .................\ *The “boost root directory”* - **index.html** ....................\ *A copy of www.boost.org* + |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* @@ -86,6 +137,7 @@ slashes with backslashes): **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: @@ -100,7 +152,7 @@ slashes with backslashes): * 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 + example, Boost.Python_'s aggregate header is ``boost/python.hpp``. * Most libraries place private headers in a subdirectory called @@ -148,46 +200,53 @@ A few things are worth noting right off the bat: contains a subset of the Boost documentation. Start with ``libs/index.html`` if you're looking for the whole enchilada. -Building a Simple Boost Program -=============================== +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:: Header-Only Libraries +.. admonition:: Nothing to Build - Nearly all Boost libraries are **header-only**. That is, most - consist entirely of header files containing templates and inline - functions, and require no separately-compiled library binaries - or special treatment when linking. + 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 are *not* header-only are: +.. _separate: - * Boost.Filesystem - * Boost.IOStreams - * Boost.ProgramOptions - * Boost.Python - * Boost.Regex - * Boost.Serialization - * Boost.Signals - * Boost.Test - * Boost.Thread - * Boost.Wave +The only Boost libraries that can't be used without separate +compilation are: - The DateTime library has a separately-compiled - binary which is only needed if you're using a “legacy - compiler”(such as?). The Graph library has a - separately-compiled binary, but you won't need it unless you - intend to `parse GraphViz files`__. +* Boost.Filesystem +* Boost.IOStreams +* Boost.ProgramOptions +* Boost.Python_ +* Boost.Regex +* Boost.Serialization +* Boost.Signals +* Boost.Test +* Boost.Thread +* Boost.Wave + +The DateTime library has a separately-compiled component that +is only needed if you're using its to/from_string and/or +serialization features or if you're targeting Visual C++ 6.x or +Borland. The Graph library also has a separately-compiled part, +but you won't need it unless you intend to `parse GraphViz +files`__. __ ../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 (a header-only library) to multiply each -one by three, and writes them to standard output:: +input, uses Boost.Lambda to multiply each number by three, and +writes them to standard output:: #include #include @@ -203,60 +262,68 @@ one by three, and writes them to standard output:: in(std::cin), in(), std::cout << (_1 * 3) << " " ); } -Start by copying the text of this program into a file called -``example.cpp``. +Copy the text of this program into a file called ``example.cpp``. .. _unix-header-only: -\*nix (e.g. Unix, Linux, MacOS, Cygwin) ---------------------------------------- +Build on \*nix +-------------- -Simply issue the following command (``$`` represents the -prompt issued by the shell, so don't type that): +In the directory where you saved ``example.cpp``, issue the +following command: .. parsed-literal:: - **$** c++ -I |root| example.cpp -o example + c++ -I |root| example.cpp -o example To test the result, type: .. parsed-literal:: - **$** echo 1 2 3 | ./example + echo 1 2 3 | ./example -Microsoft Windows Command-Line using Visual C++ ------------------------------------------------ +.. |next| replace:: *next...* -From your computer's *Start* menu, select if you are a Visual +|next|__ + +__ `Errors and Warnings`_ + +Build from the Visual Studio Command Prompt +------------------------------------------- + +From your computer's *Start* menu, if you are a Visual Studio 2005 user, select *All Programs* > *Microsoft Visual Studio 2005* > *Visual Studio Tools* > *Visual Studio 2005 Command Prompt* -or if you're a Visual Studio .NET 2003 user, select +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 +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 (``C:\PROMPT>`` represents the prompt issued by -the shell, so don't type that): +hit the return key: .. parsed-literal:: - **C:\PROMPT>** cl /EHsc /I |winroot| example.cpp + cl /EHsc /I\ |winroot| *path*\ \\\ *to*\ \\example.cpp To test the result, type: .. parsed-literal:: - **C:\PROMPT>** echo 1 2 3 | example + echo 1 2 3 | example + +|next|__ + +__ `Errors and Warnings`_ .. _vs-header-only: -Visual Studio .NET 2003 or Visual Studio 2005 ---------------------------------------------- +Build in the Visual Studio IDE +------------------------------ * From Visual Studio's *File* menu, select *New* > *Project…* * In the left-hand pane of the resulting *New Project* dialog, @@ -284,33 +351,40 @@ into the resulting window, followed by the return key:: Then hold down the control key and press "Z", followed by the return key. -Other Compilers/Environments ----------------------------- +Errors and Warnings +------------------- -Consult your vendor's documentation; if you have trouble adapting -these instructions to your build environment, request assistance on -the `Boost Users' mailing list`_. +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]_ -.. _Boost Users' mailing list: mailing_lists.htm#users +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. -Getting Boost Library Binaries -============================== +Get Boost Library Binaries +========================== If you want to use any of the separately-compiled Boost libraries, -you'll need to get ahold of library binaries. +you'll need library binaries. -Microsoft Visual C++ 8.0 or 7.1 (Visual Studio 2005/.NET 2003) 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\``. -\*nix (e.g. Unix, Linux, MacOS, Cygwin) Binaries ------------------------------------------------- +|next|__ -Issue the following commands in the shell (again, ``$`` represents -the shell's prompt): +__ `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:: @@ -337,8 +411,12 @@ 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. -Other Compilers/Environments ----------------------------- +|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 want to build with a toolset other than your system's @@ -346,87 +424,32 @@ 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. -Building Boost Binaries with Boost.Build_ ------------------------------------------ - -Like an IDE, Boost.Build_ is a system for developing, testing, and -installing software. Instead of using a GUI, though, Boost.Build_ -is text-based, like ``make``. Boost.Build_ is written in the -interpreted Boost.Jam_ language. +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 -To use Boost.Build_, you'll need an executable called ``bjam``, the -Boost.Jam_ interpreter. .. _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 - - -.. nosidebar .. sidebar:: Using Boost.Build for your own project - - When you use Boost.Build to build your *own* project, you don't - need a separate step to create Boost binaries: you simply refer - to the boost library targets from your Jamfile and the are built - automatically (refer to the `Boost.Build documentation`_ for - detailed instructions). Here, we're assuming you're using a - different build system for your own code, so you need to - explicitly generate Boost binaries. We're also assuming that - you have a complete Boost distribution somewhere. - .. _Boost.Build documentation: Boost.Build_ +Get ``bjam`` +............ -Getting ``bjam`` -................ - -.. sidebar:: Using command-line tools in Windows - - In Windows, a command-line tool is invoked by typing its name, - optionally followed by arguments, into a *Command Prompt* window - and pressing the Return (or Enter) key. - - To open *Command Prompt*, click the *Start* menu button, click - *Run*, type “cmd”, and then click OK. - - All commands are executed within the context of a **current - directory** in the filesystem. To set the current directory, - type: - - .. parsed-literal:: - - cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory* - - followed by Return. For example, - - .. parsed-literal:: - - cd |winroot-default| - - One way to name a directory you know about is to write - - .. parsed-literal:: - - %HOMEDRIVE%%HOMEPATH%\\\ *directory-name* - - which indicates a sibling folder of your “My Documents” folder. - - Long commands can be continued across several lines by typing - backslashes at the ends of all but the last line. Many of the - examples on this page use that technique to save horizontal - space. +``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 the -instructions__ given in the `Boost.Jam documentation`_. +Alternatively, you can build ``bjam`` yourself using `these +instructions`__. __ http://www.boost.org/doc/html/jam/building.html -``bjam`` is a command-line tool. To build Boost binaries, you'll -invoke ``bjam`` with the current directory set to the Boost root, -and with options described in the following sections. .. _toolset: .. _toolset-name: @@ -459,7 +482,13 @@ following table. | | |version of dmc is known to | | | |handle Boost well. | +-----------+--------------------+-----------------------------+ -|``gcc`` |The Gnu Project | | +|``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. | @@ -472,7 +501,9 @@ following table. +-----------+--------------------+-----------------------------+ |``qcc`` |QNX Software Systems| | +-----------+--------------------+-----------------------------+ -|``sun`` |Sun | | +|``sun`` |Sun |Only very recent versions are| +| | |known to work well with | +| | |Boost. | +-----------+--------------------+-----------------------------+ |``vacpp`` |IBM |The VisualAge C++ compiler. | +-----------+--------------------+-----------------------------+ @@ -511,87 +542,80 @@ invoke ``bjam`` as follows: .. parsed-literal:: - bjam --build-dir=\ |build-directory|_ **\\** - --toolset=\ |toolset-name|_ stage + bjam **--build-dir=**\ |build-directory|_ **\\** + **--toolset=**\ |toolset-name|_ stage For example, on Windows, your session might look like: .. parsed-literal:: C:\WINDOWS> cd |winroot-default| - |winroot-default|> bjam **\\** - **--build-dir=**\ %HOMEDRIVE%%HOMEPATH%\\build-boost **\\** + |winroot-default|> bjam **\\** + **--build-dir=**\ %TEMP%\\build-boost **\\** **--toolset=msvc stage** +And on Unix: + +.. parsed-literal:: + + $ cd ~/|boost_ver| + $ bjam **--build-dir=**\ ~/build-boost **--prefix=**\ ~/boost + +In either case, Boost.Build will place the Boost binaries in the +``stage/`` subdirectory of your `build directory`_. + .. Note:: ``bjam`` is case-sensitive; it is important that all the parts shown in **bold** type above be entirely lower-case. -And on Unix: +For a description of other options you can pass when invoking +``bjam``, type:: -.. parsed-literal:: + bjam --help - ~$ cd ~/|boost_ver| - ~/|boost_ver|\ $ bjam --build-dir=~/build-boost --prefix=~/boost +Expected Build Output +--------------------- -In either case, Boost.Build will place the Boost binaries in the -``stage/`` subdirectory of your *build directory*. +During the process of building Boost libraries, you can expect to +see some messages printed on the console. These may include -``stage`` -......... +* 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. -You already have the Boost headers on your system (in the -``boost/`` subdirectory of your Boost distribution), so if you -prefer not to create an additional copy, instead of installing -Boost you can simply “stage” the Boost binaries, which leaves them -in the ``stage/`` subdirectory of your chosen `build directory`_: +* 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. -.. parsed-literal:: +* Build action messages describing what the tool is doing, which + look something like: - bjam --build-dir=\ |build-directory|_ **\\** - --toolset=\ |toolset-name|_ stage + .. parsed-literal:: -.. _prefix directory: -.. _prefix-directory: + *toolset-name*.c++ *long*\ /\ *path*\ /\ *to*\ /\ *file*\ /\ *being*\ /\ *built* -Select a Prefix Directory -......................... +* Compiler warnings. -Choose a **prefix directory**. The installation process will -leave you with the following subdirectories of the prefix directory: +In Case of Build Errors +----------------------- -* ``lib``, containing the Boost binaries -* ``include/``\ |boost_ver|, containing the Boost headers. +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. -.. |prefix-directory| replace:: *prefix-directory* +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`_. -Change your current directory to the Boost root directory and -invoke ``bjam`` as follows: +__ file:///home/dave/src/boost/libs/iostreams/doc/installation.html -.. parsed-literal:: - - bjam --build-dir=\ |build-directory|_ **\\** - --toolset=\ |toolset-name|_ **\\** - --prefix=\ |prefix-directory|_ install - -For example, on Windows your session might look like: - -.. parsed-literal:: - - C:\WINDOWS> cd |winroot-default| - |winroot-default|> bjam **\\** - --build-dir=C:\\TEMP\\build-boost **\\** - --prefix=C:\\boost - -And on Unix: - -.. parsed-literal:: - - ~$ cd ~/|boost_ver| - ~/|boost_ver|\ $ bjam --build-dir=/tmp/build-boost **\\** - --prefix=~/boost - -Linking A Program with a Boost Library -====================================== +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 @@ -612,7 +636,7 @@ separately-compiled binary component. :: std::getline(std::cin, line); boost::smatch matches; if (boost::regex_match(line, matches, pat)) - std::cout << matches[2]; + std::cout << matches[2] << std::endl; } } @@ -627,8 +651,17 @@ There are two main challenges associated with linking: whose compile configuration is compatible with the rest of your project. -Microsoft Windows ------------------ +.. Note:: Boost.Python_ users should read that library's own `build + documentation`__ as there are several library-specific issues to + consider. + +.. _Boost.Python: ../libs/python/index.html +__ ../libs/python/doc/building.html + +Link to a Boost Library on Windows +---------------------------------- + +.. _auto-linking: Most Windows compilers and linkers have so called “auto-linking support,” which is used by many Boost libraries to eliminate the @@ -638,14 +671,8 @@ the correct library into your object files; the linker selects the library with that name from the directories you've told it to search. -.. Note:: As of this writing, a few Boost libraries don't support - auto-linking: - - * Boost.Python - * …others?… - -Visual C++ Command Line -....................... +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 @@ -654,23 +681,15 @@ in |winroot-default|\ ``\lib``: .. parsed-literal:: - C:\PROMPT> cl /EHsc /I |winroot| example.cpp **\\** + cl /EHsc /I |winroot| example.cpp **\\** **/link /LIBPATH:** |bold-winroot-default|\ **\\lib** -To link with a library that doesn't use auto-linking support, you -need to specify the library name. For example, +|next|__ -.. parsed-literal:: +__ `Test Your Program`_ - C:\PROMPT> cl /EHsc /I |winroot| example.cpp **\\** - /link /LIBPATH: |winroot-default| **\\** - **boost_regex-msvc-7.1-mt-d-1_34.lib** - -See `Library Naming`_ for details about how to select the right -library name. - -Visual Studio IDE -................. +Link to a Boost Library in the Visual Studio IDE +................................................ Starting with the `header-only example project`__ we created earlier: @@ -684,30 +703,23 @@ __ vs-header-only_ e.g. |winroot-default|\ ``\lib\``. 3. From the *Build* menu, select *Build Solution*. -To link with a library that doesn't use auto-linking support, -before building (step 3 above), you also need to specify the library -name: +|next|__ -* In *Configuration Properties* > *Linker* > *Input* > - *Additional Dependencies*, enter the name of the binary library - to link with, e.g. **boost_regex-msvc-7.1-mt-d-1_34.lib**. +__ `Test Your Program`_ -See `Library Naming`_ for details about how to select the right -library name. - -\*nix (e.g. Unix, Linux, MacOS, Cygwin) ---------------------------------------- +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: +A. You can specify the full path to each library: .. parsed-literal:: $ c++ -I |root| example.cpp -o example **\\** - **~/boost/lib/libboost_regex-msvc-7.1-mt-d-1_34.a** + **~/boost/lib/libboost_regex-gcc-3.4-mt-d-1_34.a** -b. You can separately specify a directory to search (with ``-L``\ +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): @@ -715,11 +727,15 @@ b. You can separately specify a directory to search (with ``-L``\ .. parsed-literal:: $ c++ -I |root| example.cpp -o example **\\** - **-L~/boost/lib/ -lboost_regex-msvc-7.1-mt-d-1_34** + **-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. + 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`__. @@ -729,11 +745,11 @@ __ unix-header-only_ Library Naming -------------- -In order to choose the right library binary to link with, you'll -need to know something about how Boost libraries are named. Each -library binary filename is composed of a common sequence of -elements that describe how it was built. For example, -``libboost_regex-msvc-7.1-mt-d-1_34.lib`` can be broken down into the +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`` @@ -745,9 +761,9 @@ following elements: ``boost_regex`` *Library name*: all boost library filenames begin with ``boost_``. -``-msvc-7.1`` - *Toolset tag*: one of the `Boost.Build toolset names`_, - possibly followed by a dash and a version number. +``-vc71`` + *Toolset tag*: identifies the toolset and version used to build + the binary. ``-mt`` *Threading tag*: indicates that the library was @@ -785,10 +801,9 @@ following elements: ABI tag is ommitted. ``-1_34`` - *Version tag*: the full Boost release number, - with periods replaced by underscores. The major and minor version - numbers are taken together separated by an underscore. For - example, version 1.31.1 would be tagged as "-1_31_1". + *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 @@ -805,21 +820,164 @@ following elements: __ ../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`_ + +.. Admonition:: Onward + + .. epigraph:: + + Good luck, and have fun! + + -- the Boost Developers + +.. _Boost.Build reference manual: http://boost.org/tools/build/v2 +.. _Boost.Jam reference manual: http://boost.org/tools/jam +.. _Boost Users' mailing list: http://boost.org/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: http://boost.org/more/mailing_lists.htm#jamboost + + +.. _`Using command-line tools in Windows`: +.. _`command prompt`: +.. _`command-line tool`: + +Appendix: Using command-line tools in Windows +============================================= + +In Windows, a command-line tool is invoked by typing its name, +optionally followed by arguments, into a *Command Prompt* window +and pressing the Return (or Enter) key. + +To open *Command Prompt*, click the *Start* menu button, click +*Run*, type “cmd”, and then click OK. + +All commands are executed within the context of a **current +directory** in the filesystem. To set the current directory, +type: + +.. parsed-literal:: + + cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory* + +followed by Return. For example, + +.. parsed-literal:: + + cd |winroot-default| + +One way to name a directory you know about is to write + +.. parsed-literal:: + + %HOMEDRIVE%%HOMEPATH%\\\ *directory-name* + +which indicates a sibling folder of your “My Documents” folder. + +Long commands can be continued across several lines by typing +backslashes at the ends of all but the last line. Many of the +examples on this page use that technique to save horizontal +space. ------------------------------ +.. [#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. -.. _Boost developers' list: mailing_lists.htm#main +.. [#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. .. [#pch] There's no problem using Boost with precompiled headers; these instructions merely avoid precompiled headers because it From fe54e4d5d006e592060ca2d12c3d786c558d7c82 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Tue, 12 Dec 2006 00:39:45 +0000 Subject: [PATCH 03/15] Improve (but don't fix) collision avoidance between |winroot-default| and sidebar on FireFox. Correct notes about library extensions for GCC on Windows. Correct broken links to reference material. [SVN r36336] --- getting_started.html | 88 +++++++++++++++++++++----------------------- getting_started.rst | 42 ++++++++++----------- 2 files changed, 63 insertions(+), 67 deletions(-) diff --git a/getting_started.html b/getting_started.html index 01f0d0c..6a69396 100644 --- a/getting_started.html +++ b/getting_started.html @@ -44,7 +44,7 @@
  • 7.4   Test Your Program
    • -
  • 8   Further Resources
    • +
  • 8   Conclusion and Further Resources
  • 9   Appendix: Using command-line tools in Windows
    • @@ -86,13 +86,6 @@ users.

    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.

    -
    -

    Onward

    -
    -

    Good luck, and have fun!

    -

    —the Boost Developers

    -
    -
    @@ -174,7 +167,7 @@ expect to find anything you can use.

    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.

      +used the Windows installer, that will usually be C: \Program`` \ ``Files\boost\boost_1_34_0.

    2. To compile anything in Boost, you need a directory containing the boost/ subdirectory in your #include path. For most @@ -313,7 +306,7 @@ select Visual C++ > Win32.

      3. select Properties from the resulting pop-up menu
    3. In Configuration Properties > C/C++ > General > Additional Include Directories, enter the path to the Boost root directory, e.g. -C:\Program Files\boost\boost_1_34_0.
      4. +C: \Program`` \ ``Files\boost\boost_1_34_0.
    4. In Configuration Properties > C/C++ > Precompiled Headers, change Use Precompiled Header (/Yu) to Not Using Precompiled Headers.5
      5. @@ -347,7 +340,7 @@ 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\.

      +the boost root, typically C: \Program`` \ ``Files\boost\boost_1_34_0\lib\.

      next...

    @@ -514,8 +507,8 @@ bjam --build-dir=build-di

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

    -C:WINDOWS> cd C:\Program Files\boost\boost_1_34_0
-C:\Program Files\boost\boost_1_34_0> bjam \
+C:WINDOWS> cd C: \Program`` \ ``Files\boost\boost_1_34_0
+C: \Program`` \ ``Files\boost\boost_1_34_0> bjam \
   --build-dir=%TEMP%\build-boost          \
   --toolset=msvc stage
    @@ -574,7 +567,7 @@ linker, consider setting up a use 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.

    +Boost.Build mailing list.

    @@ -618,19 +611,18 @@ consider.

    7.1   Link to a Boost Library on Windows

    -

    Most Windows compilers and linkers have so called “auto-linking -support,” which is used by many Boost libraries to eliminate 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.

    +

    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:

    +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
@@ -646,7 +638,7 @@ earlier:
    
 select Properties from the resulting pop-up menu
 
  • 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\.
    • 
+e.g. C: \Program`` \ ``Files\boost\boost_1_34_0\lib\.
 
  • From the Build menu, select Build Solution.
    • 
 
 
    next...
    
@@ -753,14 +745,15 @@ 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 Windows, .dll
-indicates a shared library and .lib indicates a static or
-import library.  On most *nix platforms the extensions are
+operating system's usual convention.  On most *nix platforms the extensions are
 .a and .so for static libraries (archives) and shared
-libraries, respectively.  Where supported by *nix toolsets, a
-full version extension is added (e.g. ".so.1.34"); a symbolic
-link to the library file, named without the trailing version
-number, will also be created.
    
+libraries, respectively.  On Windows—except for libraries built
+by gcc toolset, which always uses the *nix
+convention—``.dll`` indicates a shared library and .lib
+indicates a static or import library.  Where supported by *nix
+toolsets, a full version extension is added (e.g. ".so.1.34"); a
+symbolic link to the library file, named without the trailing
+version number, will also be created.
    @@ -813,25 +806,28 @@ Spoil Rock Hunter?”

    -

    8   Further Resources

    -

    This concludes your introduction to Boost and using it with your -programs. Remember that this page is only supposed to get you -started and not describe every detail you might want to know about. -There are lots of resources you can pursue from this point onward. +

    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' +make this document clearer, please post it to the Boost Users' mailing list.

    -
    -

    Note

    -

    We're also very interested in what sort of material might -be appropriate for a “Book 2” in a Getting Started series.

    +
    +

    Onward

    +
    +

    Good luck, and have fun!

    +

    —the Boost Developers

    +
    @@ -849,7 +845,7 @@ cd path\to\some\directory

    followed by Return. For example,

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

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

    @@ -948,7 +944,7 @@ recommend it.
 
    
 
    
 View document source.
-Generated on: 2006-12-11 20:27 UTC.
+Generated on: 2006-12-12 00:28 UTC.
 Generated by Docutils from reStructuredText source.
 
 
    
diff --git a/getting_started.rst b/getting_started.rst
index 6cb0fe2..131d7ee 100644
--- a/getting_started.rst
+++ b/getting_started.rst
@@ -23,7 +23,7 @@ __ ../index.htm
 
 .. |root| replace:: ``/``\ *path*\ ``/``\ *to*\ ``/``\ |boost_ver|
 .. |winroot| replace:: *path*\ ``\``\ *to*\ ``\``\ |boost_ver|
-.. |winroot-default| replace:: ``C:\Program Files\boost\``\ |boost_ver|
+.. |winroot-default| replace:: ``C:\Program``\ `` ``\ ``Files\boost\``\ |boost_ver|
 .. |bold-winroot-default| replace:: **C:\\Program Files\\boost\\**\ |boost_ver-bold|
 
 Introduction
@@ -663,13 +663,12 @@ Link to a Boost Library on Windows
 
 .. _auto-linking:
 
-Most Windows compilers and linkers have so called “auto-linking
-support,” which is used by many Boost libraries to eliminate 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.
+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
 .............................................................
@@ -806,15 +805,16 @@ following elements:
   tagged as "-1_31_1".
 
 ``.lib``
-  *Extension*: determined according to the
-  operating system's usual convention.  On Windows, ``.dll``
-  indicates a shared library and ``.lib`` indicates a static or
-  import library.  On most \*nix platforms the extensions are
-  ``.a`` and ``.so`` for static libraries (archives) and shared
-  libraries, respectively.  Where supported by \*nix toolsets, a
-  full version extension is added (e.g. ".so.1.34"); a symbolic
-  link to the library file, named without the trailing version
-  number, will also be created.
+  *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_
 
@@ -904,11 +904,11 @@ mailing list`_.
 
      -- the Boost Developers
 
-.. _Boost.Build reference manual: http://boost.org/tools/build/v2
-.. _Boost.Jam reference manual: http://boost.org/tools/jam
-.. _Boost Users' mailing list: http://boost.org/more/mailing_lists.htm#users
+.. _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: http://boost.org/more/mailing_lists.htm#jamboost
+.. _Boost.Build mailing list: mailing_lists.htm#jamboost
 
 
 .. _`Using command-line tools in Windows`:

From d72028818ebd349e92d914cf6dc1bedeb0042090 Mon Sep 17 00:00:00 2001
From: John Maddock 
Date: Tue, 12 Dec 2006 13:37:03 +0000
Subject: [PATCH 04/15] Added more explanation about static vs dynamic
 libraries.

[SVN r36345]
---
 separate_compilation.html | 117 +++++++++++++++++++++++++-------------
 1 file changed, 77 insertions(+), 40 deletions(-)

diff --git a/separate_compilation.html b/separate_compilation.html
index 7a81fd4..3425be5 100644
--- a/separate_compilation.html
+++ b/separate_compilation.html
@@ -5,18 +5,17 @@
       
       
    
-
-         
-            
-               
-               
-            
-         
    
-                  
    C++ Boost
    
-                   		
-                  
    Guidelines for Authors of Boost Libraries Containing Separate 
-                     Source
    
-               
    
+      
+         
+            
+            
+         
+      
    
+               
    C++ Boost
    
+                		
+               
    Guidelines for Authors of Boost Libraries Containing Separate 
+                  Source
    
+            
    
       
    
       
    
       
    These guidelines are designed for the authors of Boost libraries which have 
@@ -25,24 +24,23 @@
          occurrences of "whatever" or "WHATEVER" with your own library's name when 
          copying the examples.
    
       
    Contents
    
-
-         
    
-            
    Changes Affecting Source Code
-               
    
-                  
    
-                     
    Preventing Compiler ABI Clashes 
    Supporting 
-                              Windows Dll's 
    Automatic Library Selection and Linking 
-                                 with auto_link.hpp 
    
-                  
    
-                  
    Changes Affecting the Build System
-                     
    
-                        
    
-                           
    Creating the Library Jamfile 
    Testing 
-                                    Auto-linking 
    
-                        
    
-                        
    Copyright
    
-         
    
-
+      
    
+         
    Changes Affecting Source Code
+            
    
+               
    
+                  
    Preventing Compiler ABI Clashes 
    Static 
+                           or Dymanic Libraries  
    Supporting Windows Dll's 
    
+                              Automatic Library Selection and Linking with auto_link.hpp
+                           
    
+               
    
+               
    Changes Affecting the Build System
+                  
    
+                     
    
+                        
    Creating the Library Jamfile 
    Testing 
+                                 Auto-linking 
    
+                     
    
+                     
    Copyright
    
+      
    
       
    Changes Affecting Source Code
    
       
    Preventing Compiler ABI Clashes
    
       
    There are some compilers (mostly Microsoft Windows compilers again!), which 
@@ -103,10 +101,19 @@ whatever get_whatever();
 
 #endif
    -

    You can include this code in your source files as well if you want - although - you probably shouldn't need to - these headers fix the ABI to the default used - by the compiler, and if the user attempts to compile the source with any other - setting then they will get compiler errors if there are any conflicts.

    +

    You can include this code in your library source files as well if you want, + although you probably shouldn't need to:  

    +
      +
    • + If you don't use these in the library source files (but do in your + library's headers) and the user attempts to compile the library source with a + non-default ABI setting, then they will get compiler errors if there are any + conflicts.
      • +
    • + If you do include them in both the library's headers and the library + source files, then the code should always compile no matter what the compiler + settings used, although the result might not match what the user was expecting: + since we've forced the ABI back into default mode.

    Rationale:

    Without some means of managing this issue, users often report bugs along the line of "Your silly library always crashes when I try and call it" and so on. @@ -124,7 +131,38 @@ whatever get_whatever(); shared_ptr.hpp also uses them. Authors of header-only boost libraries may not be so keen on this solution - with some justification - since they don't face the same problem.

    -

    Supporting Windows Dll's

    +

    Static or Dynamic Libraries

    +

    When the users runtime is dynamically linked the Boost libraries can be built + either as dynamic libraries (.so's on Unix platforms, .dll's on Windows) or as + static libraries (.a's on Unix, .lib's on Windows).  So we have a choice + as to which is supported by default:

    +
      +
    • + On Unix platforms it typically makes no difference to the code: the user just + selects in their makesfile which library they prefer to link to.
      • +
    • + On Windows platforms, the code has to be specially annotated to support DLL's, + so we need to pick one option as the default and one as an alternative.
      • +
    • + On Windows platforms, we can inject special code to automatically select which + library variant to link against: so again we need to decide which is to be the + default (see the section on auto-linking below).
    +

    The recomendation is to pick static linking by default.

    +

    Rationale:

    +

    There is no one policy that fits all here. +

    +

    The rationale for the current behaviour was inherited from Boost.Regex (and + it's ancestor regex++): this library originally used dynamic linking by + default whenever the runtime was dynamic. It's actually safer that way should + you be using regex from a dll for example. However, this + behavior brought a persistent stream of user complaints: mainly about + deployment, all asking if static linking could be the default. After regex + changed behavior the complaints stopped, and the author hasn't had one + complaint about static linking by default being the wrong choice.

    +

    Note that other libraries might need to make other choices: for example + libraries that are intended to be used to implement dll pluggin's would like + need to use dynamic linking in almost all cases.

    +

    Supporting Windows Dll's

    On most Unix-like platforms no special annotations of source code are required in order for that source to be compiled as a shared library because all external symbols are exposed. However the majority of Windows compilers require @@ -311,7 +349,6 @@ libboost_regex-vc71-sgd-1_31.lib #include <boost/config/auto_link.hpp> #endif // auto-linking disabled -

    The library's user documentation should note that the feature can be disabled by defining either BOOST_ALL_NO_LIB or BOOST_WHATEVER_NO_LIB:

    If for any reason you need to debug this feature, the header @@ -442,12 +479,12 @@ run 26 November, 2003

    Copyright John Maddock 1998- 2003

    -

    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)

    +

    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 use of code snippets from this article does not require the reproduction of this copyright notice and license declaration; if you wish to provide attribution then please provide a link to this article.

    + From 824447769b8302a5a63921613a8910c49566600c Mon Sep 17 00:00:00 2001 From: Ronald Garcia Date: Wed, 13 Dec 2006 22:40:14 +0000 Subject: [PATCH 05/15] *** empty log message *** [SVN r36360] --- formal_review_schedule.html | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/formal_review_schedule.html b/formal_review_schedule.html index f099859..fdb5549 100644 --- a/formal_review_schedule.html +++ b/formal_review_schedule.html @@ -73,6 +73,24 @@ authors address issues raised in the formal review.

    - + + Guid + Andy Tompkins + + Boost Sandbox Vault + Needed + - + + + + Intrusive Containers + Ion Gaztaaga + + Boost Sandbox Vault + Needed + - + +

    Past Review Results and Milestones

    @@ -112,7 +130,7 @@ authors address issues raised in the formal review.

    Jeremy Siek 2006 September 6 - 2006 September 15 - Accepted + Accepted -- Added to CVS From 7522f8e8e72b9974f388f011ea4c4d15a7a0eed8 Mon Sep 17 00:00:00 2001 From: Ronald Garcia Date: Wed, 13 Dec 2006 22:41:15 +0000 Subject: [PATCH 06/15] *** empty log message *** [SVN r36361] --- formal_review_schedule.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/formal_review_schedule.html b/formal_review_schedule.html index fdb5549..8aa5776 100644 --- a/formal_review_schedule.html +++ b/formal_review_schedule.html @@ -74,7 +74,7 @@ authors address issues raised in the formal review.

    - Guid + Globally Unique Identifier Andy Tompkins Boost Sandbox Vault From 5f59ede5a1871acace15df8752c3516b20c5049e Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Wed, 13 Dec 2006 23:49:10 +0000 Subject: [PATCH 07/15] Applied 2nd round of reader feedback to Getting Started guide. Updated BoostCon pages long since live on the website. [SVN r36362] --- BoostCon07.rst | 52 ++--- BoostCon07_session_call.html | 8 +- Jamfile.v2 | 4 +- getting_started.html | 363 ++++++++++++++++++++--------------- getting_started.rst | 301 ++++++++++++++++------------- 5 files changed, 405 insertions(+), 323 deletions(-) diff --git a/BoostCon07.rst b/BoostCon07.rst index fd43938..f6bde3a 100644 --- a/BoostCon07.rst +++ b/BoostCon07.rst @@ -24,12 +24,14 @@ __ ../index.htm ---------- -This inaugural Boost conference promises to be the main -face-to-face venue for all things Boost, from using libraries to -writing them, from evangelizing Boost to deployment within your -organization, from infrastructure and process to vision and -mission, and from TR1 to TR2. Given the range and interests of the -participants, the event is going to be intense and in-depth. +.. Admonition:: What is BoostCon? + + This inaugural Boost conference promises to be the main + face-to-face venue for all things Boost, from using libraries to + writing them, from evangelizing Boost to deployment within your + organization, from infrastructure and process to vision and + mission, and from TR1 to TR2. Given the range and interests of the + participants, the event is going to be intense and in-depth. .. contents:: Index @@ -44,21 +46,18 @@ overlap day at midweek. Thus, the conference fosters interaction both within *and* across these tracks, with an emphasis on service to our user base. -Sessions will run in the morning and evening, leaving a midday -break of several hours so that attendees can get out and enjoy the -town and its surroundings, or just to have time to work together in -small, informal groups. - -Sessions -======== - In the spirit of Boost, many sessions will be participatory and/or -collaborative in nature. The program committee has issued a `call -for sessions`_. Please raise any questions about—or ideas for—the -conference on the `Boost mailing lists`__. +collaborative in nature. Sessions will run in the morning and +evening, leaving a midday break of several hours so that attendees +can get out and enjoy the town and its surroundings, or just to +have time to work together in small, informal groups. -.. _call for sessions: http://www.boost.org/more/BoostCon07_session_call.html -__ http://www.boost.org/more/mailing_lists.htm +Propose a Session +================= + +See the BoostCon `Call for Sessions`_ for details about how to submit a sesion proposal. + +.. _call for Sessions: http://www.boost.org/more/BoostCon07_session_call.html Venue ===== @@ -94,13 +93,6 @@ us to expand registration should demand prove overwhelming, but when registration opens we recommend securing your place early, in case that isn't possible. -Sessions -======== - -The program committee is currently forming and drafting a call for -sessions; watch this space in upcoming weeks for an outline of -workshop, session, and talk ideas, and a request for submissions. - Registration ============ @@ -119,6 +111,14 @@ __ interest_ __ interest_ +Questions +========= + +Please raise any other questions about—or ideas for—the conference +on the `Boost mailing lists`__. + +__ http://www.boost.org/more/mailing_lists.htm + .. _interest: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?BoostCon Organizing Committee diff --git a/BoostCon07_session_call.html b/BoostCon07_session_call.html index 2929872..8249e72 100644 --- a/BoostCon07_session_call.html +++ b/BoostCon07_session_call.html @@ -15,7 +15,7 @@

    Boost Conference 2007: - Call for Proposals

    + Call for Sessions

    The first annual Boost conference will take place in Aspen, Colorado, May 14-18, 2007.

    This inaugural Boost conference promises to be the main face-to-face @@ -99,12 +99,12 @@

  • A biography, suitable for the conference web site
  • Your contact information (will not be made public)
    • -

    Please submit via email to conference@boost-consulting.com, with a +

    Please submit via email to boostcon-program@lists.boost-consulting.com, with a subject that begins "BoostCon proposal"

    Revised: - 11 November 2006

    + 4 December 2006

    Copyright David Abrahams and Beman Dawes 2006

    Distributed under the Boost Software License, Version 1.0. (See accompanying file @@ -113,4 +113,4 @@

    - \ No newline at end of file + diff --git a/Jamfile.v2 b/Jamfile.v2 index de53650..a61b176 100644 --- a/Jamfile.v2 +++ b/Jamfile.v2 @@ -4,7 +4,7 @@ import docutils ; import path ; -sources = getting_started.rst ; +sources = getting_started.rst BoostCon07.rst ; bases = $(sources:S=) ; # This is a path relative to the html/ subdirectory where the @@ -15,6 +15,8 @@ for local b in $(bases) { html $(b) : $(b).rst : + # "PYTHONPATH=~/src/boost/tools && python ~/src/boost/tools/litre/active-rst.py" + # "-gdt --writer=html --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet) "-gdt --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet) ; } diff --git a/getting_started.html b/getting_started.html index 6a69396..665efff 100644 --- a/getting_started.html +++ b/getting_started.html @@ -14,22 +14,21 @@

    Contents

    -

    1   Introduction

    +

    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

    +

    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 @@ -64,7 +62,7 @@ the end of this document, we'll refer you on to resources that can help you pursue these topics further.

    -

    1.2   Preliminaries

    +

    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 @@ -89,8 +87,8 @@ them for your own compiler or IDE.

    -

    2   Get Boost

    -

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

    +

    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 @@ -98,7 +96,7 @@ distribution, plus optional precompiled library binaries for Visual Studio, and (optionally) a prebuilt version of the bjam build tool.

      2. -

    2. Download: users of other platforms—and Windows +

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

      @@ -115,16 +113,18 @@ tar --bzip2 -xf /path/to/
      4. -

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

      +

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

    -

    3   The Structure of a Boost Distribution

    +

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

    @@ -159,15 +159,15 @@ the Type Traits Library's is_void example, Boost.Python's aggregate header is boost/python.hpp.
  • Most libraries place private headers in a subdirectory called -detail/ or aux_/. Don't look in these directories and -expect to find anything you can use.
    • +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.

      +used the Windows installer, that will usually be C:\Program Files\boost\boost_1_34_0.

    2. To compile anything in Boost, you need a directory containing the boost/ subdirectory in your #include path. For most @@ -203,40 +203,41 @@ contains a subset of the Boost documentation. Start with

    -

    4   Header-Only Libraries

    +

    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

    +

    Nothing to Build?

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

    -

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

    +

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

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

    -

    5   Build a Simple Program Using Boost

    +

    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 @@ -258,7 +259,7 @@ int main()

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

    -

    5.1   Build on *nix

    +

    5.1   Build on *nix

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

    @@ -271,7 +272,74 @@ echo 1 2 3 | ./example
 
    next...
    -

    5.2   Build from the Visual Studio Command Prompt

    +

    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

    @@ -285,45 +353,16 @@ Studio 2005 user, select

    Studio compiler. In that window, type the following command and hit the return key:

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

    To test the result, type:

     echo 1 2 3 | example
    -

    next...

    +
    -

    5.3   Build in the Visual Studio IDE

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

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

    -
    -1 2 3
-
    -

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

    -
    -
    -

    5.4   Errors and Warnings

    +

    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 @@ -333,14 +372,14 @@ Boost root directory.

    -

    6   Get Boost Library Binaries

    +

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

    +the boost root, typically C:\Program Files\boost\boost_1_34_0\lib\.

    next...

    @@ -357,12 +396,14 @@ directory, you'll probably want to at least use

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

    to install somewhere else. Finally,

    +

    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
    -

    which will leave Boost binaries in the lib/ subdirectory of -your installation prefix. You will also find a copy of the Boost +

    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.

    @@ -371,7 +412,7 @@ path in place of the Boost root directory.

    6.3   Build and Install Other Binaries

    If you're not using Visual C++ 7.1 or 8.0, or you're a *nix user -who wants want to build with a toolset other than your system's +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.

    @@ -502,20 +543,19 @@ purpose in your current working directory.

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

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

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

    +

    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 \
-  --build-dir=%TEMP%\build-boost          \
-  --toolset=msvc stage
+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=~/build-boost --prefix=~/boost
+$ 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.

    @@ -529,6 +569,14 @@ parts shown in bold type above be entirely lower-case.

     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.
      • +
    @@ -574,7 +622,7 @@ questions about configuring Boost for your compiler to the

    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 +emails. It uses the Boost.Regex library, which has a separately-compiled binary component.

     #include <boost/regex.hpp>
@@ -603,12 +651,6 @@ build settings.
 whose compile configuration is compatible with the rest of your
 project.
 
-
    
-
    Note
    
-
    Boost.Python users should read that library's own build
-documentation as there are several library-specific issues to
-consider.
    
-
    
 
    
 
    7.1   Link to a Boost Library on Windows
    
 
    Most Windows compilers and linkers have so-called “auto-linking
@@ -622,7 +664,7 @@ the directories you've told it to search.
    
 
    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:
    
+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
@@ -638,14 +680,14 @@ earlier:
    
 select Properties from the resulting pop-up menu
 
  • 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\.
    • 
+e.g. C:\Program Files\boost\boost_1_34_0\lib\.
 
  • From the Build menu, select Build Solution.
    • 
 
 
    next...
    -

    7.2   Link to a Boost Library On *nix

    +

    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:

      @@ -654,7 +696,7 @@ $ c++ -I /path~/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,6 dropping the filename's leading lib and trailing +

    3. 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 \
@@ -685,7 +727,7 @@ following elements:
      
 
      Prefix: except on Microsoft Windows, every Boost library
 name begins with this string.  On Windows, only ordinary static
 libraries use the lib prefix; import libraries and DLLs do
-not.7
      
+not.8
 
      boost_regex
      
 
      Library name: all boost library filenames begin with boost_.
      
 
      -vc71
      
@@ -722,14 +764,14 @@ libraries.
 using a special debug build of Python.
 
 d
-building a debug version of your code.8
+building a debug version of your code.9
 
 p
 using the STLPort standard library rather than the default one supplied with
 your compiler.
 
 n
-using STLPort's deprecated “native iostreams” feature.9
+using STLPort's deprecated “native iostreams” feature.10
 
 
 
@@ -744,16 +786,16 @@ ABI tag is ommitted.
      
 replaced by underscores. For example, version 1.31.1 would be
 tagged as "-1_31_1".
 
      .lib
      
-
      Extension: determined according to the
-operating system's usual convention.  On most *nix platforms the extensions are
-.a and .so for static libraries (archives) and shared
-libraries, respectively.  On Windows—except for libraries built
-by gcc toolset, which always uses the *nix
-convention—``.dll`` indicates a shared library and .lib
-indicates a static or import library.  Where supported by *nix
-toolsets, a full version extension is added (e.g. ".so.1.34"); a
-symbolic link to the library file, named without the trailing
-version number, will also be created.
      
+
      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.
    @@ -815,12 +857,30 @@ 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.

    -
    -
    -

    9   Appendix: Using command-line tools in Windows

    -

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

    -

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

    -

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

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

    followed by Return. For example,

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

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

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

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

    -

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

    @@ -896,10 +929,20 @@ 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.
    - @@ -908,14 +951,14 @@ used in the examples.
    [5]There's no problem using Boost with precompiled headers; +
    [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.
    -
    [6]That option is a dash followed by a lowercase “L” +
    [7]That option is a dash followed by a lowercase “L” character, which looks very much like a numeral 1 in some fonts.
    - @@ -924,7 +967,7 @@ same name.
    [7]This convention distinguishes the static version of +
    [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.
    -
    [8]These libraries were compiled without optimization +
    [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 @@ -934,7 +977,7 @@ compiled code, you can't count on that with Boost libraries.
    - @@ -944,7 +987,7 @@ recommend it.
    View document source. -Generated on: 2006-12-12 00:28 UTC. +Generated on: 2006-12-13 23:45 UTC. Generated by Docutils from reStructuredText source.
    diff --git a/getting_started.rst b/getting_started.rst index 131d7ee..4d44753 100644 --- a/getting_started.rst +++ b/getting_started.rst @@ -23,7 +23,7 @@ __ ../index.htm .. |root| replace:: ``/``\ *path*\ ``/``\ *to*\ ``/``\ |boost_ver| .. |winroot| replace:: *path*\ ``\``\ *to*\ ``\``\ |boost_ver| -.. |winroot-default| replace:: ``C:\Program``\ `` ``\ ``Files\boost\``\ |boost_ver| +.. |winroot-default| replace:: ``C:\``\ ``Program`` ``Files\boost\``\ |boost_ver| .. |bold-winroot-default| replace:: **C:\\Program Files\\boost\\**\ |boost_ver-bold| Introduction @@ -31,7 +31,7 @@ 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. +of a Boost distribution and how to go about using it. What's Here ----------- @@ -75,7 +75,7 @@ them for your own compiler or IDE. Get Boost ========= -There are basically three ways to get Boost on your system: +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 @@ -89,7 +89,7 @@ There are basically three ways to get Boost on your system: .. _installer: `Windows installer`_ -2. **Download**: users of other platforms—and Windows +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. @@ -107,11 +107,13 @@ There are basically three ways to get Boost on your system: tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2 -3. **Boost packages** from RedHat, Debian, or some other - distribution packager: these instructions may not work for you - if you use 3rd party packages, because other packagers sometimes - choose to break Boost up into several packages or to reorganize - the directory structure of the Boost distribution. [#packagers]_ +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 ===================================== @@ -156,8 +158,8 @@ slashes with backslashes): ``boost/python.hpp``. * Most libraries place private headers in a subdirectory called - ``detail/`` or ``aux_/``. Don't look in these directories and - expect to find anything you can use. + ``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: @@ -206,7 +208,7 @@ 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 +.. admonition:: Nothing to Build? Most Boost libraries are **header-only**: they consist *entirely of header files* containing templates and inline functions, and @@ -215,26 +217,28 @@ Boost?” The good news is that often, there's nothing to build. .. _separate: -The only Boost libraries that can't be used without separate -compilation are: +The only Boost libraries that *must* be built separately are: -* Boost.Filesystem -* Boost.IOStreams -* Boost.ProgramOptions +* Boost.Filesystem_ +* Boost.IOStreams_ +* Boost.ProgramOptions_ * Boost.Python_ -* Boost.Regex -* Boost.Serialization -* Boost.Signals -* Boost.Test -* Boost.Thread -* Boost.Wave +* Boost.Regex_ +* Boost.Serialization_ +* Boost.Signals_ +* Boost.Thread_ +* Boost.Wave_ -The DateTime library has a separately-compiled component that -is only needed if you're using its to/from_string and/or -serialization features or if you're targeting Visual C++ 6.x or -Borland. The Graph library also has a separately-compiled part, -but you won't need it unless you intend to `parse GraphViz -files`__. +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.** __ ../libs/graph/doc/read_graphviz.html @@ -288,8 +292,84 @@ To test the result, type: __ `Errors and Warnings`_ -Build from the Visual Studio Command Prompt -------------------------------------------- +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 @@ -308,7 +388,7 @@ hit the return key: .. parsed-literal:: - cl /EHsc /I\ |winroot| *path*\ \\\ *to*\ \\example.cpp + cl /EHsc /I |winroot| *path*\ \\\ *to*\ \\example.cpp To test the result, type: @@ -316,41 +396,6 @@ To test the result, type: echo 1 2 3 | example -|next|__ - -__ `Errors and Warnings`_ - -.. _vs-header-only: - -Build in the Visual Studio IDE ------------------------------- - -* From Visual Studio's *File* menu, select *New* > *Project…* -* In the left-hand pane of the resulting *New Project* dialog, - select *Visual C++* > *Win32*. -* In the right-hand pane, select *Win32 Console Application* - (VS8.0) or *Win32 Console Project* (VS7.1). -* In the *name* field, enter “example” -* Right-click **example** in the *Solution Explorer* pane and - select *Properties* from the resulting pop-up menu -* In *Configuration Properties* > *C/C++* > *General* > *Additional Include - Directories*, enter the path to the Boost root directory, e.g. - |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. - Errors and Warnings ------------------- @@ -363,8 +408,8 @@ 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. -Get Boost Library Binaries -========================== +Prepare to Use a Boost Library Binary +===================================== If you want to use any of the separately-compiled Boost libraries, you'll need library binaries. @@ -399,14 +444,16 @@ directory, you'll probably want to at least use **$** ./configure **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix* -to install somewhere else. Finally, +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 -which will leave Boost binaries in the ``lib/`` subdirectory of -your installation prefix. You will also find a copy of the Boost +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. @@ -419,7 +466,7 @@ Build and Install Other Binaries -------------------------------- If you're not using Visual C++ 7.1 or 8.0, or you're a \*nix user -who wants want to build with a toolset other than your system's +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. @@ -542,24 +589,23 @@ invoke ``bjam`` as follows: .. parsed-literal:: - bjam **--build-dir=**\ |build-directory|_ **\\** - **--toolset=**\ |toolset-name|_ stage + bjam **--build-dir=**\ |build-directory|_ **--toolset=**\ |toolset-name|_ stage -For example, on Windows, your session might look like: +For example, on Windows, your session might look like this: [#continuation]_ .. parsed-literal:: C:\WINDOWS> cd |winroot-default| - |winroot-default|> bjam **\\** - **--build-dir=**\ %TEMP%\\build-boost **\\** - **--toolset=msvc stage** + |winroot-default|> bjam **^** + More? **--build-dir=**\ %TEMP%\\build-boost **^** + More? **--toolset=**\ msvc stage And on Unix: .. parsed-literal:: $ cd ~/|boost_ver| - $ bjam **--build-dir=**\ ~/build-boost **--prefix=**\ ~/boost + $ 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`_. @@ -572,6 +618,17 @@ For a description of other options you can pass when invoking 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 --------------------- @@ -640,8 +697,6 @@ separately-compiled binary component. :: } } -.. _Boost.Regex: ../libs/regex - There are two main challenges associated with linking: 1. Tool configuration, e.g. choosing command-line options or IDE @@ -651,13 +706,6 @@ There are two main challenges associated with linking: whose compile configuration is compatible with the rest of your project. -.. Note:: Boost.Python_ users should read that library's own `build - documentation`__ as there are several library-specific issues to - consider. - -.. _Boost.Python: ../libs/python/index.html -__ ../libs/python/doc/building.html - Link to a Boost Library on Windows ---------------------------------- @@ -706,7 +754,7 @@ __ vs-header-only_ __ `Test Your Program`_ -Link to a Boost Library On \*nix +Link to a Boost Library on \*nix -------------------------------- There are two main ways to link to libraries: @@ -895,6 +943,19 @@ mailing list`_. * `Boost Users' mailing list`_ * `Boost.Build mailing list`_ * `Boost.Build Wiki`_ +* Index of `All 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** + + + +.. _All Library Documentation: ../libs/index.html .. Admonition:: Onward @@ -910,48 +971,6 @@ mailing list`_. .. _Boost.Build Wiki: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2 .. _Boost.Build mailing list: mailing_lists.htm#jamboost - -.. _`Using command-line tools in Windows`: -.. _`command prompt`: -.. _`command-line tool`: - -Appendix: Using command-line tools in Windows -============================================= - -In Windows, a command-line tool is invoked by typing its name, -optionally followed by arguments, into a *Command Prompt* window -and pressing the Return (or Enter) key. - -To open *Command Prompt*, click the *Start* menu button, click -*Run*, type “cmd”, and then click OK. - -All commands are executed within the context of a **current -directory** in the filesystem. To set the current directory, -type: - -.. parsed-literal:: - - cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory* - -followed by Return. For example, - -.. parsed-literal:: - - cd |winroot-default| - -One way to name a directory you know about is to write - -.. parsed-literal:: - - %HOMEDRIVE%%HOMEPATH%\\\ *directory-name* - -which indicates a sibling folder of your “My Documents” folder. - -Long commands can be continued across several lines by typing -backslashes at the ends of all but the last line. Many of the -examples on this page use that technique to save horizontal -space. - ------------------------------ .. [#zip] If you prefer not to download executable programs, download @@ -979,6 +998,12 @@ space. 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 @@ -1002,3 +1027,15 @@ space. 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 From 30237aa61876a0ec149c29716e2c0b84f721bdb0 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sun, 17 Dec 2006 11:49:07 +0000 Subject: [PATCH 08/15] * Say something accurate about Boost.Test * Fix a windows shell line terminator * Improve Boost lib documentation link [SVN r36442] --- getting_started.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/getting_started.rst b/getting_started.rst index 4d44753..4a9fcba 100644 --- a/getting_started.rst +++ b/getting_started.rst @@ -238,7 +238,8 @@ A few libraries have optional separately-compiled binaries: * 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.** +* 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 @@ -728,7 +729,7 @@ in |winroot-default|\ ``\lib``: .. parsed-literal:: - cl /EHsc /I |winroot| example.cpp **\\** + cl /EHsc /I |winroot| example.cpp **^** **/link /LIBPATH:** |bold-winroot-default|\ **\\lib** |next|__ @@ -943,7 +944,7 @@ mailing list`_. * `Boost Users' mailing list`_ * `Boost.Build mailing list`_ * `Boost.Build Wiki`_ -* Index of `All Library Documentation`_ +* `Index of all Boost library documentation`_ * Library-specific Configuration and Build Details - Boost.Python__ @@ -955,7 +956,7 @@ mailing list`_. -.. _All Library Documentation: ../libs/index.html +.. _Index of all Boost library documentation: ../libs/index.html .. Admonition:: Onward From 3c82e581403d010802658d76c44702f376b5bce5 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Fri, 22 Dec 2006 14:52:22 +0000 Subject: [PATCH 09/15] Factored getting started guide into separate windows and *nix documents [SVN r36493] --- getting_started.html | 997 +--------------- getting_started.rst | 1042 ----------------- getting_started/Jamfile.v2 | 23 + getting_started/detail/binary-head.rst | 10 + .../detail/build-from-source-head.rst | 123 ++ .../detail/build-from-source-tail.rst | 66 ++ getting_started/detail/build-simple-head.rst | 28 + getting_started/detail/common-footnotes.rst | 26 + getting_started/detail/common-unix.rst | 21 + getting_started/detail/common-windows.rst | 29 + getting_started/detail/common.rst | 5 + getting_started/detail/conclusion.rst | 39 + getting_started/detail/distro.rst | 88 ++ .../detail/errors-and-warnings.rst | 16 + getting_started/detail/header-only.rst | 45 + getting_started/detail/library-naming.rst | 80 ++ getting_started/detail/link-head.rst | 39 + getting_started/detail/links.rst | 16 + getting_started/detail/release-variables.rst | 12 + getting_started/detail/test-head.rst | 16 + getting_started/index.html | 58 + getting_started/index.rst | 60 + getting_started/unix-variants.html | 786 +++++++++++++ getting_started/unix-variants.rst | 236 ++++ getting_started/windows.html | 876 ++++++++++++++ getting_started/windows.rst | 315 +++++ 26 files changed, 3020 insertions(+), 2032 deletions(-) delete mode 100644 getting_started.rst create mode 100644 getting_started/Jamfile.v2 create mode 100644 getting_started/detail/binary-head.rst create mode 100644 getting_started/detail/build-from-source-head.rst create mode 100644 getting_started/detail/build-from-source-tail.rst create mode 100644 getting_started/detail/build-simple-head.rst create mode 100644 getting_started/detail/common-footnotes.rst create mode 100644 getting_started/detail/common-unix.rst create mode 100644 getting_started/detail/common-windows.rst create mode 100644 getting_started/detail/common.rst create mode 100644 getting_started/detail/conclusion.rst create mode 100644 getting_started/detail/distro.rst create mode 100644 getting_started/detail/errors-and-warnings.rst create mode 100644 getting_started/detail/header-only.rst create mode 100644 getting_started/detail/library-naming.rst create mode 100644 getting_started/detail/link-head.rst create mode 100644 getting_started/detail/links.rst create mode 100644 getting_started/detail/release-variables.rst create mode 100644 getting_started/detail/test-head.rst create mode 100644 getting_started/index.html create mode 100644 getting_started/index.rst create mode 100644 getting_started/unix-variants.html create mode 100644 getting_started/unix-variants.rst create mode 100644 getting_started/windows.html create mode 100644 getting_started/windows.rst diff --git a/getting_started.html b/getting_started.html index 665efff..62d669e 100644 --- a/getting_started.html +++ b/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.

    -
    [9]This feature of STLPort is deprecated because it's +
    [10]This feature of STLPort is deprecated because it's impossible to make it work transparently to the user; we don't recommend it.
    ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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/getting_started.rst b/getting_started.rst deleted file mode 100644 index 4a9fcba..0000000 --- a/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/getting_started/Jamfile.v2 b/getting_started/Jamfile.v2 new file mode 100644 index 0000000..770aae9 --- /dev/null +++ b/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/getting_started/detail/binary-head.rst b/getting_started/detail/binary-head.rst new file mode 100644 index 0000000..21f32ab --- /dev/null +++ b/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/getting_started/detail/build-from-source-head.rst b/getting_started/detail/build-from-source-head.rst new file mode 100644 index 0000000..7e55da8 --- /dev/null +++ b/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/getting_started/detail/build-from-source-tail.rst b/getting_started/detail/build-from-source-tail.rst new file mode 100644 index 0000000..1fd8855 --- /dev/null +++ b/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/getting_started/detail/build-simple-head.rst b/getting_started/detail/build-simple-head.rst new file mode 100644 index 0000000..487610e --- /dev/null +++ b/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/getting_started/detail/common-footnotes.rst b/getting_started/detail/common-footnotes.rst new file mode 100644 index 0000000..e7b1fa2 --- /dev/null +++ b/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/getting_started/detail/common-unix.rst b/getting_started/detail/common-unix.rst new file mode 100644 index 0000000..77fa042 --- /dev/null +++ b/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/getting_started/detail/common-windows.rst b/getting_started/detail/common-windows.rst new file mode 100644 index 0000000..f7dc50e --- /dev/null +++ b/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/getting_started/detail/common.rst b/getting_started/detail/common.rst new file mode 100644 index 0000000..591c05b --- /dev/null +++ b/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/getting_started/detail/conclusion.rst b/getting_started/detail/conclusion.rst new file mode 100644 index 0000000..b9ee341 --- /dev/null +++ b/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/getting_started/detail/distro.rst b/getting_started/detail/distro.rst new file mode 100644 index 0000000..bf429a1 --- /dev/null +++ b/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/getting_started/detail/errors-and-warnings.rst b/getting_started/detail/errors-and-warnings.rst new file mode 100644 index 0000000..770d46e --- /dev/null +++ b/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/getting_started/detail/header-only.rst b/getting_started/detail/header-only.rst new file mode 100644 index 0000000..13d7e3f --- /dev/null +++ b/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/getting_started/detail/library-naming.rst b/getting_started/detail/library-naming.rst new file mode 100644 index 0000000..bf777a0 --- /dev/null +++ b/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/getting_started/detail/link-head.rst b/getting_started/detail/link-head.rst new file mode 100644 index 0000000..c4a5995 --- /dev/null +++ b/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/getting_started/detail/links.rst b/getting_started/detail/links.rst new file mode 100644 index 0000000..21d1110 --- /dev/null +++ b/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/getting_started/detail/release-variables.rst b/getting_started/detail/release-variables.rst new file mode 100644 index 0000000..c8dc919 --- /dev/null +++ b/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/getting_started/detail/test-head.rst b/getting_started/detail/test-head.rst new file mode 100644 index 0000000..90e1ce7 --- /dev/null +++ b/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/getting_started/index.html b/getting_started/index.html new file mode 100644 index 0000000..c72e124 --- /dev/null +++ b/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/getting_started/index.rst b/getting_started/index.rst new file mode 100644 index 0000000..23bfa7b --- /dev/null +++ b/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/getting_started/unix-variants.html b/getting_started/unix-variants.html new file mode 100644 index 0000000..2a2a876 --- /dev/null +++ b/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/getting_started/unix-variants.rst b/getting_started/unix-variants.rst new file mode 100644 index 0000000..6924468 --- /dev/null +++ b/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/getting_started/windows.html b/getting_started/windows.html new file mode 100644 index 0000000..8d7b795 --- /dev/null +++ b/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/getting_started/windows.rst b/getting_started/windows.rst new file mode 100644 index 0000000..0c820fd --- /dev/null +++ b/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 From 5933328ba00834ae2470668528d951d9cb0c212c Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Fri, 22 Dec 2006 15:00:01 +0000 Subject: [PATCH 10/15] Factored getting started guide into separate windows and *nix documents [SVN r36494] --- getting_started/windows.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/getting_started/windows.rst b/getting_started/windows.rst index 0c820fd..ac27721 100644 --- a/getting_started/windows.rst +++ b/getting_started/windows.rst @@ -249,14 +249,6 @@ in |default-root|\ ``\lib``: 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 -------------- From c5a8b3eab6d75da8faa368bb6605b4b360e97d87 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Fri, 22 Dec 2006 16:26:47 +0000 Subject: [PATCH 11/15] clean up some ReST errors, remove `*nix\' [SVN r36495] --- getting_started/detail/library-naming.rst | 18 ++-- getting_started/unix-variants.html | 18 ++-- getting_started/windows.html | 124 ++++++++++------------ 3 files changed, 77 insertions(+), 83 deletions(-) diff --git a/getting_started/detail/library-naming.rst b/getting_started/detail/library-naming.rst index bf777a0..ad1d512 100644 --- a/getting_started/detail/library-naming.rst +++ b/getting_started/detail/library-naming.rst @@ -64,15 +64,15 @@ following elements: ``.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. + convention. On most unix-style 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 the ``gcc`` + toolset, whose names always end in ``.a``) ``.lib`` indicates a + static or import library. Where supported by toolsets on unix + variants, 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_ diff --git a/getting_started/unix-variants.html b/getting_started/unix-variants.html index 2a2a876..873ae6e 100644 --- a/getting_started/unix-variants.html +++ b/getting_started/unix-variants.html @@ -628,15 +628,15 @@ 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.
    +convention. On most unix-style 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 the gcc +toolset, whose names always end in .a) .lib indicates a +static or import library. Where supported by toolsets on unix +variants, 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. diff --git a/getting_started/windows.html b/getting_started/windows.html index 8d7b795..f15a1f9 100644 --- a/getting_started/windows.html +++ b/getting_started/windows.html @@ -26,40 +26,40 @@ not supported—they may or may not work.

    Index

    -

    1   Get Boost

    +

    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 @@ -76,7 +76,7 @@ distribution.

    -

    2   The Boost Distribution

    +

    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”
@@ -159,7 +159,7 @@ contains a subset of the Boost documentation.  Start with
    -

    3   Header-Only Libraries

    +

    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.

    @@ -197,7 +197,7 @@ use.
    -

    4   Build a Simple Program Using Boost

    +

    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 @@ -253,7 +253,7 @@ caret (^) at the end on this page use that technique to save horizontal space.

    -

    4.1   Build From the Visual Studio IDE

    +

    4.1   Build From the Visual Studio IDE

    • From Visual Studio's File menu, select New > Project…

      • @@ -294,7 +294,7 @@ Return key.

      skip to the next step

    -

    4.2   Or, Build From the Command Prompt

    +

    4.2   Or, Build From the Command Prompt

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

    @@ -320,7 +320,7 @@ echo 1 2 3 | example
    -

    4.3   Errors and Warnings

    +

    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 @@ -333,11 +333,11 @@ correctly identified the Boost

    -

    5   Prepare to Use a Boost Library Binary

    +

    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

    +

    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 @@ -347,7 +347,7 @@ now.

    skip to the next step

    -

    5.2   Or, Build and Install Binaries From Source

    +

    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.

    @@ -358,7 +358,7 @@ own binaries.

    installing software. To use it, you'll need an executable called bjam.

    -

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

    @@ -367,7 +367,7 @@ Alternatively, you can build bjam instructions.

    -

    5.2.2   Identify Your Toolset

    +

    5.2.2   Identify Your Toolset

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

    @@ -469,7 +469,7 @@ toolset from the table.

    -

    5.2.3   Select a Build Directory

    +

    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 @@ -477,7 +477,7 @@ default Boost.Build will create a

    -

    5.2.4   Invoke bjam

    +

    5.2.4   Invoke bjam

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

    @@ -516,7 +516,7 @@ be interested in:
    -

    5.3   Expected Build Output

    +

    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

      @@ -540,7 +540,7 @@ look something like:

    -

    5.4   In Case of Build Errors

    +

    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 @@ -558,7 +558,7 @@ questions about configuring Boost for your compiler to the

    -

    6   Link Your Program to a Boost Library

    +

    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 @@ -600,7 +600,7 @@ 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

    +

    6.1   Link From Within the Visual Studio IDE

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

      @@ -614,7 +614,7 @@ e.g. C:\Program skip to the next step

    -

    6.2   Or, Link From the Command Prompt

    +

    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 @@ -623,15 +623,9 @@ in C:\Program 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

    +

    6.3   Library Naming

    Note

    If, like Visual C++, your compiler supports auto-linking, @@ -653,7 +647,7 @@ following elements:

    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
    +not.6
    boost_regex
    Library name: all boost library filenames begin with boost_.
    -vc71
    @@ -691,14 +685,14 @@ libraries.
    - + - +
    using a special debug build of Python.
    dbuilding a debug version of your code.7building a debug version of your code.7
    p using the STLPort standard library rather than the default one supplied with your compiler.
    nusing STLPort's deprecated “native iostreams” feature.8using STLPort's deprecated “native iostreams” feature.8
    @@ -715,22 +709,22 @@ 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.
    +convention. On most unix-style 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 the gcc +toolset, whose names always end in .a) .lib indicates a +static or import library. Where supported by toolsets on unix +variants, 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

    +

    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:

    @@ -752,7 +746,7 @@ Spoil Rock Hunter?”
    -

    7   Conclusion and Further Resources

    +

    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 @@ -832,7 +826,7 @@ have any source code mechanism for suppressing warnings. - @@ -841,7 +835,7 @@ same name.
    [6]This convention distinguishes the static version of +
    [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 +
    [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 @@ -851,7 +845,7 @@ compiled code, you can't count on that with Boost libraries.
    - From 0478a6ae7901025652a1b9d8489b6b4f9bc0d4de Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Fri, 22 Dec 2006 21:03:05 +0000 Subject: [PATCH 12/15] fix a broken link and "All though" => "Although" [SVN r36496] --- getting_started/detail/common-footnotes.rst | 2 +- getting_started/detail/conclusion.rst | 2 +- getting_started/unix-variants.html | 4 ++-- getting_started/windows.html | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/getting_started/detail/common-footnotes.rst b/getting_started/detail/common-footnotes.rst index e7b1fa2..980600b 100644 --- a/getting_started/detail/common-footnotes.rst +++ b/getting_started/detail/common-footnotes.rst @@ -16,7 +16,7 @@ .. [#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 + ``NDEBUG`` ``#define``\ d. Although 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. diff --git a/getting_started/detail/conclusion.rst b/getting_started/detail/conclusion.rst index b9ee341..10d61f5 100644 --- a/getting_started/detail/conclusion.rst +++ b/getting_started/detail/conclusion.rst @@ -31,7 +31,7 @@ mailing list`_. -- the Boost Developers -.. _Boost.Build reference manual: ../tools/build/v2 +.. _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 diff --git a/getting_started/unix-variants.html b/getting_started/unix-variants.html index 873ae6e..f247ed7 100644 --- a/getting_started/unix-variants.html +++ b/getting_started/unix-variants.html @@ -693,7 +693,7 @@ 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.

     diff --git a/getting_started/windows.html b/getting_started/windows.html index f15a1f9..4330058 100644 --- a/getting_started/windows.html +++ b/getting_started/windows.html @@ -756,7 +756,7 @@ 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.

    From c7330c0392e7195385f7f2990ebbfc68fcc383db Mon Sep 17 00:00:00 2001 From: Andreas Huber Date: Sun, 24 Dec 2006 07:35:50 +0000 Subject: [PATCH 13/15] From Darin Adler Fri Dec 15 13:10:41 2006 X-Apparently-To: ahd6974-boostorg -at- yahoo.com via 68.142.206.155; Fri, 15 Dec 2006 13:10:51 -0800 X-Originating-IP: [17.254.13.23] Return-Path: Authentication-Results: mta278.mail.re4.yahoo.com from=bentspoon.com; domainkeys=neutral (no sig) Received: from 17.254.13.23 (EHLO mail-out4.apple.com) (17.254.13.23) by mta278.mail.re4.yahoo.com with SMTP; Fri, 15 Dec 2006 13:10:51 -0800 Received: from relay5.apple.com (a17-128-113-35.apple.com [17.128.113.35]) by mail-out4.apple.com (8.13.6/8.13.6) with ESMTP id kBFLAoGP019669 for ; Fri, 15 Dec 2006 13:10:50 -0800 (PST) Received: from [17.219.209.233] (unknown [17.219.209.233]) (using TLSv1 with cipher AES128-SHA (128/128 bits)) (No client certificate requested) by relay5.apple.com (Apple SCV relay) with ESMTP id B9D3D324014 for ; Fri, 15 Dec 2006 13:10:50 -0800 (PST) Mime-Version: 1.0 (Apple Message framework v752.3) In-Reply-To: <20061120100114.38287.qmail@web33506.mail.mud.yahoo.com> References: <20061120100114.38287.qmail@web33506.mail.mud.yahoo.com> Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed Message-Id: <15EB64CF-7150-4FAD-BAF0-C5759D2B6772@bentspoon.com> Content-Transfer-Encoding: 7bit From: "Darin Adler" Add to Address Book Add Mobile Alert Subject: Re: [boost] Need your permission to correct license & copyright issues Date: Fri, 15 Dec 2006 13:10:41 -0800 To: ahd6974-boostorg -at- yahoo.com [Edit - Delete] X-Mailer: Apple Mail (2.752.3) X-Brightmail-Tracker: AAAAAA== Content-Length: 468 On Nov 20, 2006, at 2:01 AM, Andreas Huber wrote: > 2. Reply to this email and expressly state that you grant permission > to convert all your contributions to the boost library to the new > license (). This will > ultimately have the same effect as 1. above, as I will then add your > name to blanket-permission.txt. I grant permission to convert all my contributions to the boost library to the new license. -- Darin [SVN r36498] --- blanket-permission.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/blanket-permission.txt b/blanket-permission.txt index 046e61d..7245e2b 100644 --- a/blanket-permission.txt +++ b/blanket-permission.txt @@ -17,6 +17,7 @@ Dan Gohman (djg -at- cray.com) (See Boost list messsage of Sat, 21 Aug 2004 10:5 Dan Nuffer (dan -at- nuffer.name) Daniel Frey (d.frey -at- gmx.de, daniel.frey -at- aixigo.de) Daniel Nuffer (dan -at- nuffer.name) +Darin Adler (darin -at- bentspoon.com) (Email to Andreas Huber, see change log) Daryle Walker (darylew - at - hotmail.com) Dave Abrahams (dave@boost-consulting.com) Dave Moore (dmoore -at- viefinancial.com) (See Boost list message of 18 Dec 2003 15:35:50 -0500) From bd275ceb9d31ac40184b86e0598c289fbaf0144a Mon Sep 17 00:00:00 2001 From: Ronald Garcia Date: Sun, 24 Dec 2006 14:25:03 +0000 Subject: [PATCH 14/15] *** empty log message *** [SVN r36510] --- formal_review_schedule.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/formal_review_schedule.html b/formal_review_schedule.html index 8aa5776..d3a278d 100644 --- a/formal_review_schedule.html +++ b/formal_review_schedule.html @@ -60,8 +60,8 @@ authors address issues raised in the formal review.

     - - + + @@ -110,8 +110,8 @@ authors address issues raised in the formal review.

    - + From f93be8223e2df20d0a5f0f2f3b7e9fe72bf79326 Mon Sep 17 00:00:00 2001 From: Rene Rivera Date: Sun, 24 Dec 2006 15:30:39 +0000 Subject: [PATCH 15/15] Sync with RC, again. [SVN r36511] --- blanket-permission.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/blanket-permission.txt b/blanket-permission.txt index 7245e2b..018d5ea 100644 --- a/blanket-permission.txt +++ b/blanket-permission.txt @@ -57,6 +57,7 @@ Joel de Guzman (joel -at- boost-consulting.com) (See Boost list message of July John Bandela (jbandela-at-ufl.edu) John Maddock (john - at - johnmaddock.co.uk) John R Bandela (jbandela-at-ufl.edu) +Jonathan Turkanis (turkanis -at- coderage dot com) Juergen Hunold (hunold -at- ive.uni-hannover.de) (See Boost List Message of Fri, 13 Aug 2004 19:39:55 +0200) Kevlin Henney (kevlin -at- curbralan.com) (See Boost list message of Wed, 15 Sep 2004 18:15:17 +0200) Kresimir Fresl (fresl -at- master.grad.hr) (See Boost List message of August 16, 2004 8:23:35 AM EST)
    [8]This feature of STLPort is deprecated because it's +
    [8]This feature of STLPort is deprecated because it's impossible to make it work transparently to the user; we don't recommend it.
    [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 +NDEBUG #defined. Although 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.
    [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 +NDEBUG #defined. Although 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.
    Eric Niebler Boost Sandbox VaultNeeded-John R. PhillipsJanuary 29, 2007 - February 7, 2007
    Tobias Schwinger Tom Brinkman 2006 November 6 - 2006 November 17 - Ongoing + Accepted -