From 74ddd1e585647aecd380618ab7a4c993481011af Mon Sep 17 00:00:00 2001 From: nobody Date: Mon, 11 Dec 2006 20:38:42 +0000 Subject: [PATCH] This commit was manufactured by cvs2svn to create branch 'RC_1_34_0'. [SVN r36334] --- more/getting_started.rst | 1004 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 1004 insertions(+) create mode 100644 more/getting_started.rst diff --git a/more/getting_started.rst b/more/getting_started.rst new file mode 100644 index 0000000000..6cb0fe23f9 --- /dev/null +++ b/more/getting_started.rst @@ -0,0 +1,1004 @@ +============================ + |(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 +========= + +There are basically three ways to get Boost on your system: + +1. **Windows Installer**: Boost Consulting provides an installer_ + for Windows platforms that installs a complete Boost + distribution, plus optional precompiled library binaries for + Visual Studio, and (optionally) a prebuilt version of the + ``bjam`` build tool. + + .. _Windows installer: http://www.boost-consulting.com/download.html + .. |Windows installer| replace:: **Windows installer** + .. _Boost Consulting: http://boost-consulting.com + .. _installer: `Windows installer`_ + + +2. **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** 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 +===================================== + +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 look in these directories and + expect to find anything you can use. + +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 can't be used without separate +compilation are: + +* 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 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 from the Visual Studio Command Prompt +------------------------------------------- + +From your computer's *Start* menu, if you are a Visual +Studio 2005 user, select + + *All Programs* > *Microsoft Visual Studio 2005* + > *Visual Studio Tools* > *Visual Studio 2005 Command Prompt* + +or, if you're a Visual Studio .NET 2003 user, select + + *All Programs* > *Microsoft Visual Studio .NET 2003* + > *Visual Studio .NET Tools* > *Visual Studio .NET 2003 Command Prompt* + +to bring up a special `command prompt`_ window set up for the Visual +Studio compiler. In that window, type the following command and +hit the return key: + +.. parsed-literal:: + + cl /EHsc /I\ |winroot| *path*\ \\\ *to*\ \\example.cpp + +To test the result, type: + +.. parsed-literal:: + + 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 +------------------- + +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. + +Get Boost Library Binaries +========================== + +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. 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 +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 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``. + +.. |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: + +.. parsed-literal:: + + C:\WINDOWS> cd |winroot-default| + |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. + +For a description of other options you can pass when invoking +``bjam``, type:: + + bjam --help + +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; + } + } + +.. _Boost.Regex: ../libs/regex + +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. + +.. 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 +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 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. + +.. _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`_ + +.. 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. + +.. [#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 + 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. +