From 3e90d9d38802ad57c5eac88a89978307aa2d6679 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sun, 19 Nov 2006 22:59:27 +0000 Subject: [PATCH] Initial checkin. [SVN r36097] --- getting_started.rst | 846 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 846 insertions(+) create mode 100644 getting_started.rst diff --git a/getting_started.rst b/getting_started.rst new file mode 100644 index 0000000..340689b --- /dev/null +++ b/getting_started.rst @@ -0,0 +1,846 @@ +======================================== + Getting Started With Boost |(logo)|__ +======================================== + +.. |(logo)| image:: ../boost.png + :alt: Boost + +__ ../index.htm + +This guide will help you get started using the Boost libraries. +Have fun! + +.. section-numbering:: + +.. contents:: Index + + +.. ## 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:: *C:*\ ``\``\ *path*\ ``\``\ *to*\ ``\``\ |boost_ver| +.. |winroot-default| replace:: ``C:\Program Files\boost\``\ |boost_ver| +.. |bold-winroot-default| replace:: **C:\\Program Files\\boost\\**\ |boost_ver| + +Getting 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). + +.. ## remove the parenthesized note for full releases +.. _Windows installer: http://www.boost-consulting.com/download.html + +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 + + :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. + + :\*nix users: 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. 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]_ + +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_1_34_0/** .................\ *The “boost root directory”* + **index.html** ....................\ *A copy of www.boost.org* + **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 + + 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. + +Building a Simple Boost Program +=============================== + +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 + + 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: + + * 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 + 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`__. + +__ ../libs/graph/doc/read_graphviz.html + +.. ## Keep the list of non-header-only libraries up-to-date + + +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:: + + #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) << " " ); + } + +Start by copying the text of this program into a file called +``example.cpp``. + +.. _*nix-header-only: + +\*nix (e.g. Unix, Linux, MacOS, Cygwin) +--------------------------------------- + +Simply issue the following command (``$`` represents the +prompt issued by the shell, so don't type that): + +.. parsed-literal:: + + **$** c++ -I |root| example.cpp -o example + +To test the result, type: + +.. parsed-literal:: + + **$** echo 1 2 3 | ./example + +Microsoft Windows Command-Line using Visual C++ +----------------------------------------------- + +From your computer's *Start* menu, select 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 (``C:\PROMPT>`` represents the prompt issued by +the shell, so don't type that): + +.. parsed-literal:: + + **C:\PROMPT>** cl /EHsc /I |winroot| example.cpp + +To test the result, type: + +.. parsed-literal:: + + **C:\PROMPT>** echo 1 2 3 | example + +.. _vs-header-only: + +Visual Studio .NET 2003 or Visual Studio 2005 +--------------------------------------------- + +* 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. + +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`_. + +.. _Boost Users' mailing list: mailing_lists.htm#users + +Getting Boost Library Binaries +============================== + +If you want to use any of the separately-compiled Boost libraries, +you'll need to get ahold of library binaries. + +Microsoft Visual C++ 8.0 or 7.1 (Visual Studio 2005/.NET 2003) 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 +------------------------------------------------ + +Issue the following commands in the shell (again, ``$`` 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. + +Other Compilers/Environments +---------------------------- + +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. + +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. + +.. |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_ + + +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. + +Boost provides |precompiled-bjam|_ for a variety of platforms. +Alternatively, you can build ``bjam`` yourself using the +instructions__ given in the `Boost.Jam documentation`_. + +__ 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: + +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. | ++--------+--------------------+-----------------------------+ +|gcc |The Gnu Project | | ++--------+--------------------+-----------------------------+ +|hp_cxx |Hewlett Packard |Targeted at the Tru64 | +| | |operating system. | ++--------+--------------------+-----------------------------+ +|intel |Intel | | ++--------+--------------------+-----------------------------+ +|kylix |Borland | | ++--------+--------------------+-----------------------------+ +|msvc |Microsoft | | ++--------+--------------------+-----------------------------+ +|qcc |QNX Software Systems| | ++--------+--------------------+-----------------------------+ +|sun |Sun | | ++--------+--------------------+-----------------------------+ +|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=**\ %HOMEDRIVE%%HOMEPATH%\\build-boost \\ + **--toolset=msvc stage** + +.. Note:: ``bjam`` is case-sensitive; it is important that all the + parts shown in **bold** type above be entirely lower-case. + +And on Unix: + +.. parsed-literal:: + + ~$ cd ~/|boost_ver| + ~/|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*. + +``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`_: + +.. parsed-literal:: + + bjam --build-dir=\ |build-directory|_ \\ + --toolset=\ |toolset-name|_ stage + +.. _prefix directory: +.. _prefix-directory: + +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_ver|, containing the Boost headers. + +.. |prefix-directory| replace:: *prefix-directory* + +Change your current directory to the Boost root directory and +invoke ``bjam`` as follows: + +.. 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 +====================================== + +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]; + } + } + +.. _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. + +Microsoft 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?… + +Visual C++ Command Line +....................... + +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|: + +.. parsed-literal:: + + C:\PROMPT> cl /EHsc /I |winroot| example.cpp **\\** + **/link /LIBPATH:** |bold-winroot-default| + +To link with a library that doesn't use auto-linking support, you +need to specify the library name. For example, + +.. parsed-literal:: + + 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 +................. + +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*. + +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. + +\*nix (e.g. Unix, Linux, MacOS, Cygwin) +--------------------------------------- + +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-msvc-7.1-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-msvc-7.1-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. + +In both cases above, the bold text is what you'd add to `the +command lines we explored earlier`__. + +__ *nix-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 +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_``. + +``-msvc-7.1`` + *Toolset tag*: one of the `Boost.Build toolset names`_, + possibly followed by a dash and a version number. + +``-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. 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". + +``.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 + + +------------------------------ + +.. [#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`_. + +.. [#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 + +.. [#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. +