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..980600b --- /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. 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. + +.. [#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..10d61f5 --- /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/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..ad1d512 --- /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 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_ + +__ ../../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!

+
+
+ + + 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.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.rst b/getting_started/windows.rst new file mode 100644 index 0000000..ac27721 --- /dev/null +++ b/getting_started/windows.rst @@ -0,0 +1,307 @@ +.. 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** + +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