From 2253b8ad4dd3f133911837a155fbcb75ed2c4d02 Mon Sep 17 00:00:00 2001 From: Rene Rivera Date: Tue, 18 Nov 2003 05:42:53 +0000 Subject: [PATCH] Single document to explain the building and installation of Boost libraries with the new build+install system. [SVN r20844] --- more/getting_started.html | 1119 +++++++++++++++++++++++++++++++++++++ 1 file changed, 1119 insertions(+) create mode 100644 more/getting_started.html diff --git a/more/getting_started.html b/more/getting_started.html new file mode 100644 index 0000000000..4d07bde099 --- /dev/null +++ b/more/getting_started.html @@ -0,0 +1,1119 @@ + + + + + + + + + + Getting Started + + + + + + + + + +
+ + + + + +
+ + + + +
+

. Home
+ . Libraries
+ . People
+ . FAQ
+ . More

+
+
+
+ +

Getting Started

+ + + +

Introduction

+ +

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. Download Boost.
    2. + +
  2. Install Boost.Jam.
    3. + +
  3. Configure your compiler toolset.
    4. + +
  4. Go to Boost distribution directory.
    5. + +
  5. Build and install.
    6. +
+ +

Download

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

.zip file

The .zip format is widely supported by + both free decoders and commercial compress/archive utilities. If you don't + already have a .zip file decoder, download one from the Info-ZIP web site, which supplies versions + for many operating systems. + +

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.

+ +

.tar.gz and .tar.bz2 files

+ +

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.

+ +

Boost CVS Repository

+ +

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.

+ +

Boost CVS access via command line or graphical clients

For those + who have CVS clients installed, the libraries are also available from the + public Boost CVS + repository. Free command line clients (often already installed on + Linux/Unix systems) are available for many systems, and free GUI clients + are available for Windows, Mac, and other systems. + +

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:

+ +
+ 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 +
Read the manual for your CVS client for further information. + +

This access is read-only; if you are a library author and wish to have + CVS write access, please contact one of the moderators.

+ +

Boost CVS access via web Browser

For access + to the CVS archive from any modern web browser, you can also use the + web + browser  interface.  Try one of the color diffs to see how a + file has changed over time. + +

Preparation

+ +

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.

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

Configuring the tools

+ +

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:

+ +
    +
  1. The user sets up all of the environment for each toolset he wants to + use in the normal way. For example, for Microsoft VC++, ...vc98/bin is in + the path, vcvars32.bat or equivalent has been invoked, etc. For + Metrowerks CodeWarrior, cwenv.bat or equivalent has been called and + ...Other Metrowerks Tools/Command Line Tools is in the path. Many Unix + operating systems come preconfigured this way and require no user + intervention.
    +
    2. + +
  2. The user doesn't want his environment cluttered with settings or has + nonstandard installations for some of his tools. Instead, he or she sets + variables which point to the toolset installation directories, either in + the command shell environment or on the bjam command-line. + These variables are used by the build system to locate the tools and + invoke the necessary setup.
    3. +
+ +

Supported Toolsets

+ + + + + + + +
+ 3The following toolsets are supported by Boost.Build. For + information about configuring each toolset, + click its name in the leftmost column.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TOOLS NameDescription
borlandBorland C++
comoComeau C++ compiler + front-end for non-Windows platforms
como-win32Comeau C++ compiler + front-end for Windows, using Microsoft Visual C++as a back-end.
cwpro8Metrowerks CodeWarrior Pro + 8.x command-line tools
darwinApple Darwin OS hosted GNU GCC.
edgEdison Design Group compiler + front-end (evaluation version)
gccGNU GCC on Unix and Cygwin.
gcc-stlportGNU GCC on Unix and Cygwin, using the STLport standard library + implementation
gcc-nocygwinGNU GCC Cygwin command line compiler tools running in "no-cygwin" + mode (produces commercially redistributable objects)
intel-linuxIntel C++ for + Linux
intel-win32Intel C++ for + Windows using the Dinkumware standard library in the Intel-required + Microsoft Visual C++ 6 + or 7 installation
kccKAI + C++
kylixBorland C++ for Linux + (Kylix).
metrowerksMetrowerks CodeWarrior + command-line tools
mingwGNU GCC and associated tools in MinGW configuration (produces commercially + redistributable objects)
mipsproSGI MIPSpro + C and C++
msvcMicrosoft Visual + C++ command-line tools.
msvc-stlportMicrosoft Visual + C++ command-line tools, using the STLport standard library + implementation
sunproSunPRO C++ + compiler
tru64cxxCompaq C++ for + Tru64 UNIX (versions prior to 6.5)
tru64cxx65Compaq C++ + Version 6.5 for Tru64 UNIX
vacppIBM Visual Age + C++ command-line tools
vc7Microsoft Visual + C++ command-line tools from Visual Studio .NET.
vc7.1Microsoft Visual + C++ command-line tools from Visual Studio .NET 2003.
+ +

Build and Install

+ +

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:

+ +
+

chdir boost-1.31.0

+
+
+ +

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

bjam "-sTOOLS=gcc" install

+
+
+ +

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 
noneOnly 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.
installBuilds and installs Boost libraries and + headers.
stageBuilds the Boost libraries and "stages" + them into a "stage" directory.
Option 
--helpShows 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=PREFIXInstall architecture independent files + here.
+ Default; C:\\Boost on Win32.
+ Default; /usr/local on Unix. Linux, etc.
+ --exec-prefix=EPREFIXInstall architecture dependent files + here.
+ Default; PREFIX
--libdir=DIRInstall libraries here.
+ Default; EPREFIX/lib
--includedir=DIRInstall source headers here. The Boost + headers are installed in a version specific + "boost-<version>" subdirectory in this directory.
+ Default; PREFIX/include
--builddir=DIRBuild 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=DIRWhen 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-pydebugBuild 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.

+ +

Results

+ +

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:

+ +
    +
  1. libboost_date_time-gcc-d-1_31.so
    2. + +
  2. libboost_date_time-gcc-mt-d-1_31.so
    3. + +
  3. libboost_date_time-gcc-1_31.so
    4. + +
  4. libboost_date_time-gcc-mt-1_31.so
    5. + +
  5. libboost_date_time-gcc-d-1_31.a
    6. + +
  6. libboost_date_time-gcc-mt-d-1_31.a
    7. + +
  7. libboost_date_time-gcc-1_31.a
    8. + +
  8. libboost_date_time-gcc-mt-1_31.a
    9. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
· Library Prefix
+ 		 
lib + + + + +
· Library Name
+
boost_date_time + + + + +
· Toolset
+
-gcc + + + + +
· Threading
+
-mt + + + + +
· Runtime
+
-d + + + + +
· Boost Version
+
-1_31 + + + + +
· Library Type
+
.a 
+ +

Library Prefix

+ +

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:

+ + + +

Library Name

+ +

For Boost libraries the name has the "boost_" prefix to + separate them from other libraries in your system.

+ +

Toolset

+ +

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 NameAbbreviation
borlandbcb
comocomo
como-win32como
cwpro8cw8
darwinosx
edgedg
gccgcc
gcc-stlportgcc
gcc-nocygwingcc
intel-linuxil
intel-win32iw
kcckcc
kylixbck
metrowerkscw
mingwmgw
mipspromp
msvcvc
msvc-stlportvc
sunprosw
tru64cxxtru
tru64cxx65tru
vacppxlc
vc7vc
vc7.1vc
OthersThe first part of the toolset name.
+ +

Threading

+ +

This tag indicates if the library is compiled with threading support. If + threading is enabled "-mt" is added, otherwise nothing is + added.

+ +

Runtime

+ +

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyFeature
sStatic link to runtime.
gDebug runtime.
yDebug Python system.
dDebug enabled code.
pSTLport runtime, instead of the vendor toolset runtime.
nSTLport 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".

+ +

Boost Version

+ +

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.

+ +

Library Type

+ +

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.

+ +

Additional Steps

+ +

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)

+ +