+
|
+
|
+
+
+
|
+
These instructions are intended to help you get started using the Boost + Libraries. This walks you through getting, building, and installing the + libraries. To summarize these are the steps to get Boost built and + installed:
+ +| + 1 | + +The Boost Libraries are distributed through the SourceForge file + distribution system. Click here to + download releases from SourceForge. And unpack the + release to a convenient location. | +
The Boost release includes all of the libraries and other material from + the web site. It is available in ZIP, TAR.GZ, and TAR.BZ2 formats. Past + releases are also available.
It is also possible to download current + snapshots of work-in-progress from Boost's CVS + repository. + +Text file line endings in the .zip file are as supplied by each library + developer. This works fine for Windows, but not for Unix/Linux. + The .tar.gz and .tar.bz2 files supply Unix/Linux friendly line endings.
+ +The .tar.gz format is widely supported on Unix/Linux platforms. Some + Windows compress/archive utilities can read the format as well. + Because the gzip format compresses the archive as a single file rather than + compressing each file individually, the .tar.gz file is smaller that the + .zip file.
+ +The .tar.bz2 format is becoming widely available on Unix/Linux platforms + and is built into many tar utilities. This format differs for the .tar.gz + format in the compression used, which is considerably better and therefore + creates smaller files.
+ +Text file line endings in the .tar.gz and .tar.bz2 files have been + converted to newlines for ease of use on Unix/Linux platforms.
+ +All Boost files, including the entire distribution tree including web + site HTML is maintained in a CVS repository. Command line, GUI, or browser + access is available.
+ +See the much improved CVS documentation (Section + F) from SourceForge, which includes links to the home pages for various GUI + and command line clients.
+ +The general procedure for command-line clients is something like + this:
+ ++Read the manual for your CVS client for further information. + +cvs -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost + login
+ [Hit <return> when it asks for a password]
+cvs -z3 + -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost checkout + boost+
+ cvs -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost + logout
This access is read-only; if you are a library author and wish to have + CVS write access, please contact one of the moderators.
+ +The recommended way to build and install the Boost Libraries is to use + Boost.Build, the Boost Build system. The rest of these instructions explain + that use, but it is up to you to use this method, or not. Note that some of + the libraries also include non Boost.Build makefiles and/or project files. + But all include the needed files for building with Boost.Build.
+ +| + 2 | + +The build system uses Boost.Jam, an extension of the + Perforce Jam + portable make replacement. You can either build this yourself, + it's included with the distribution. Or obtain a + prebuilt from SourceForge. To install Boost.Jam, + copy the bjam executable to a location accessible in your + PATH. | +
Before using Boost.Build you will need to configure the compiler tools + you are using. The build system's toolsets are designed to work in either + of two ways:
+ +bjam command-line.
+ These variables are used by the build system to locate the tools and
+ invoke the necessary setup.| + 3 | + +The following toolsets are supported by Boost.Build. For + information about configuring each toolset, + click its name in the leftmost column. | +
| TOOLS Name | + +Description | +
borland |
+
+ Borland C++ | +
como |
+
+ Comeau C++ compiler + front-end for non-Windows platforms | +
como-win32 |
+
+ Comeau C++ compiler + front-end for Windows, using Microsoft Visual C++as a back-end. | +
cwpro8 |
+
+ Metrowerks CodeWarrior Pro + 8.x command-line tools | +
darwin |
+
+ Apple Darwin OS hosted GNU GCC. | +
edg |
+
+ Edison Design Group compiler + front-end (evaluation version) | +
gcc |
+
+ GNU GCC on Unix and Cygwin. | +
gcc-stlport |
+
+ GNU GCC on Unix and Cygwin, using the STLport standard library + implementation | +
gcc-nocygwin |
+
+ GNU GCC Cygwin command line compiler tools running in "no-cygwin" + mode (produces commercially redistributable objects) | +
intel-linux |
+
+ Intel C++ for + Linux | +
intel-win32 |
+
+ Intel C++ for + Windows using the Dinkumware standard library in the Intel-required + Microsoft Visual C++ 6 + or 7 installation | +
kcc |
+
+ KAI + C++ | +
kylix |
+
+ Borland C++ for Linux + (Kylix). | +
metrowerks |
+
+ Metrowerks CodeWarrior + command-line tools | +
mingw |
+
+ GNU GCC and associated tools in MinGW configuration (produces commercially + redistributable objects) | +
mipspro |
+
+ SGI MIPSpro + C and C++ | +
msvc |
+
+ Microsoft Visual + C++ command-line tools. | +
msvc-stlport |
+
+ Microsoft Visual + C++ command-line tools, using the STLport standard library + implementation | +
sunpro |
+
+ SunPRO C++ + compiler | +
tru64cxx |
+
+ Compaq C++ for + Tru64 UNIX (versions prior to 6.5) | +
tru64cxx65 |
+
+ Compaq C++ + Version 6.5 for Tru64 UNIX | +
vacpp |
+
+ IBM Visual Age + C++ command-line tools | +
vc7 |
+
+ Microsoft Visual + C++ command-line tools from Visual Studio .NET. | +
vc7.1 |
+
+ Microsoft Visual + C++ command-line tools from Visual Studio .NET 2003. | +
The common build and install process is driven by the top-level build + file (Jamfile).
+ +| + 4 | + +
+ First you need to change to the directory where you have the Boost + distribution you downloaded. For example: + +++ |
+
The default build and install attempts to build all available libraries + and install to default locations the libraries and Boost header files. On + Unix systems the default install location is "/usr/local", and on + Windows systems the default is "C:\\Boost". Within those libraries + are installed to the "lib" subdirectory, and headers to an + "include/boost-1_31" subdirectory, the version will reflect the + distribution you are installing.
+ +| + 5 | + +
+ Invoke the build system, specifying the toolset(s) you wish to use, to build and install. For
+ example for GNU/GCC.
+
+ ++ |
+
The build and install system can be controlled through a set of options + similar in style to GNU configure options. The options allow you to, among + other things, change the install location, disable building of libraries, + etc. You can see a summary of the available options by invoking "bjam + --help". The full invocation takes the form:
+ +++ ++
bjam [options...] [install|stage]
| Action | + ++ |
|---|---|
| none | + +Only builds the Boost libraries. This + lets you do the first part of what the install action normally + does without copying the built libraries to the install location. | +
| install | + +Builds and installs Boost libraries and + headers. | +
| stage | + +Builds the Boost libraries and "stages" + them into a "stage" directory. | +
| Option | + ++ |
| --help | + +Shows a short summary of the options and + syntax of the command. | +
| + -sTOOLS=<toolsets> | + +The list of tools to compile with. + Usually only one is needed. You can specify more than one by separating + them with spaces. | +
| --prefix=PREFIX | + +Install architecture independent files
+ here. + Default; C:\\Boost on Win32. + Default; /usr/local on Unix. Linux, etc. |
+
| + --exec-prefix=EPREFIX | + +Install architecture dependent files
+ here. + Default; PREFIX |
+
| --libdir=DIR | + +Install libraries here. + Default; EPREFIX/lib |
+
| --includedir=DIR | + +Install source headers here. The Boost
+ headers are installed in a version specific
+ "boost-<version>" subdirectory in this directory. + Default; PREFIX/include |
+
| --builddir=DIR | + +Build in this location instead of + building within the distribution tree. This moves where the sources for + the libraries are compiled to before they are installed. + Recommended! | +
| --stagedir=DIR | + +When staging only, with the
+ "stage" action, stage to the given location. + Default; ./stage |
+
| + --without-<library> | + +Do not build, stage, or install the + specified library. | +
| + --with-python-root[=PYTHON_ROOT] | + +Build Boost.Python libraries with the
+ Python devel packages located at PYTHON_ROOT. The Boost.Python
+ libraries are built only if the build can find the Python development
+ package at this location. + Default; C:\\tools\\python on Win32. + Default; /usr/local on Unix, Linux, etc. + Default; /usr on Cygwin. |
+
| --with-pydebug | + +Build Boost.Python libraries using the + Python debug runtime. This builds an additional set of libraries for + use with the debug version of Python. The regular versions of the + Boost.Python libraries are also built. | +
If you have some feedback about the build and install process please + drop us a line at the Boost.Build + mailing list. We are particularly interested if it works for your + platform and if it there is anything that you feel could be done + better.
+ +The results of building come in to forms: static libraries, and dynamic + libraries. Depending on the platform the libraries produced have different + names to accommodate the platform requirements. For a single Boost library + the build with the default will produce eight different libraries. For + example building the Boost.Datetime library on Unix type system it would + produce:
+ +
+
|
+
+ + | |||||||
| lib | + +
+
|
+ |||||||
| boost_date_time | + +
+
|
+ |||||||
| -gcc | + +
+
|
+ |||||||
| -mt | + +
+
|
+ |||||||
| -d | + +
+
|
+ |||||||
| -1_31 | + +
+
|
+ |||||||
| .a | + ++ | |||||||
The "lib" prefix on the libraries is a requirement on many platforms, + like Unix, and on others like GCC running on Windows. The prefix is + therefore added to all libraries on Unix type systems, and to static + libraries on Windows. That is on Unix shared libraries and static libraries + (object archives) are named respectively:
+ +On Windows shared libraries do not have the prefix to differentiate the + import libraries from static libraries. Consequently on Windows the + libraries are named:
+ +For Boost libraries the name has the "boost_" prefix to + separate them from other libraries in your system.
+ +The toolset name is an abbreviation based on the compiler you are + building with. The abbreviation is composed of a short, 2 to 4 characters, + tag for the compiler and a version number of the compiler's major and minor + revision (if available). For example if your toolset is + "gcc-3.2.3" the toolset tag would be "gcc32". The toolset + abbreviations used are as follows:
+ +| TOOLS Name | + +Abbreviation | +
borland |
+
+ bcb | +
como |
+
+ como | +
como-win32 |
+
+ como | +
cwpro8 |
+
+ cw8 | +
darwin |
+
+ osx | +
edg |
+
+ edg | +
gcc |
+
+ gcc | +
gcc-stlport |
+
+ gcc | +
gcc-nocygwin |
+
+ gcc | +
intel-linux |
+
+ il | +
intel-win32 |
+
+ iw | +
kcc |
+
+ kcc | +
kylix |
+
+ bck | +
metrowerks |
+
+ cw | +
mingw |
+
+ mgw | +
mipspro |
+
+ mp | +
msvc |
+
+ vc | +
msvc-stlport |
+
+ vc | +
sunpro |
+
+ sw | +
tru64cxx |
+
+ tru | +
tru64cxx65 |
+
+ tru | +
vacpp |
+
+ xlc | +
vc7 |
+
+ vc | +
vc7.1 |
+
+ vc | +
| Others | + +The first part of the toolset name. | +
This tag indicates if the library is compiled with threading support. If + threading is enabled "-mt" is added, otherwise nothing is + added.
+ +This specifies the type of runtime the library was compiled against, and + the type of code that is compiled. More commonly this encodes the ABI + variation used in the code. For each feature of the runtime system and code + compilation option a single letter is added to this tag.
+ +| Key | + +Feature | +
| s | + +Static link to runtime. | +
| g | + +Debug runtime. | +
| y | + +Debug Python system. | +
| d | + +Debug enabled code. | +
| p | + +STLport runtime, instead of the vendor toolset runtime. | +
| n | + +STLport runtime using the "native" IO streams instead of the + STLport IO streams. | +
For example if you compile debug code for STLport using native IO + streams, and statically link to the debug runtime the tag would be: + "-sgdpn".
+ +This is the short label for the version of the Boost Libraries. The + major and minor version numbers are taken together separated by an + underscore. For example version 1.31.0 would be tagged as "-1_31". + The patch version number is not included because it is assumed that patch + versions are upward compatible.
+ +The extension holds the type of library. This follows the platform + requirements. On Windows this is ".dll" for shared libraries, and + ".lib" for static libraries including import libraries. On Unix + this is ".a" for static libraries (archives), and ".so" for shared + libraries. For toolsets that support it in Unix they will also have a full + version extension (for example ".so.1.31.0") with a symbolic link + for the un-versioned library.
+ +Depending on your platform and configuration you may need to perform + some additional configuration to get Boost to build and install.
+ +Revised + 17 November, 2003 +
+ +Copyright © Rene Rivera 2003.
+ Copyright © Jens Maurer 2001.
Use, modification, and distribution are subject to the Boost + Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)
+ +