mirror of
https://github.com/boostorg/thread.git
synced 2026-01-26 07:02:12 +00:00
138 lines
8.5 KiB
XML
138 lines
8.5 KiB
XML
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd" [
|
|
<!ENTITY % thread.entities SYSTEM "entities.xml">
|
|
%thread.entities;
|
|
]>
|
|
<!-- Copyright (c) 2002-2003 William E. Kempf, Michael Glassford
|
|
Copyright (c) 2007 Roland Schwarz
|
|
Subject to the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE-1.0 or http://www.boost.org/LICENSE-1.0)
|
|
-->
|
|
<section id="thread.build" last-revision="$Date$">
|
|
<title>Build</title>
|
|
<para>
|
|
How you build the &Boost.Thread; libraries, and how you build your own applications
|
|
that use those libraries, are some of the most frequently asked questions. Build
|
|
processes are difficult to deal with in a portable manner. That's one reason
|
|
why &Boost.Thread; makes use of &Boost.Build;.
|
|
In general you should refer to the documentation for &Boost.Build;.
|
|
This document will only supply you with some simple usage examples for how to
|
|
use <emphasis>bjam</emphasis> to build and test &Boost.Thread;. In addition, this document
|
|
will try to explain the build requirements so that users may create their own
|
|
build processes (for instance, create an IDE specific project), both for building
|
|
and testing &Boost.Thread;, as well as for building their own projects using
|
|
&Boost.Thread;.
|
|
</para>
|
|
<section id="thread.build.building">
|
|
<title>Building the &Boost.Thread; Libraries</title>
|
|
<para>
|
|
Building the &Boost.Thread; Library depends on how you intend to use it. You have several options:
|
|
<itemizedlist>
|
|
<listitem>
|
|
Using as a <link linkend="thread.build.precompiled">precompiled</link> library, possibly
|
|
with auto-linking, or for use from within an IDE.
|
|
</listitem>
|
|
<listitem>
|
|
Use from a <link linkend="thread.build.bjam">&Boost.Build;</link> project.
|
|
</listitem>
|
|
<listitem>
|
|
Using in <link linkend="thread.build.source">source</link> form.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<section id="thread.build.precompiled">
|
|
<title>Precompiled</title>
|
|
<para>
|
|
Using the &Boost.Thread; library in precompiled form is the way to go if you want to
|
|
install the library to a standard place, from where your linker is able to resolve code
|
|
in binary form. You also will want this option if compile time is a concern. Multiple
|
|
variants are available, for different toolsets and build variants (debug/release).
|
|
The library files are named <emphasis>{lead}boost_thread{build-specific-tags}.{extension}</emphasis>,
|
|
where the build-specific-tags indicate the toolset used to build the library, whether it's
|
|
a debug or release build, what version of &Boost; was used, etc.; and the lead and extension
|
|
are the appropriate extensions for a dynamic link library or static library for the platform
|
|
for which &Boost.Thread; is being built.
|
|
For instance, a debug build of the dynamic library built for Win32 with VC++ 7.1 using Boost 1.34 would
|
|
be named <emphasis>boost_thread-vc71-mt-gd-1_34.dll</emphasis>.
|
|
More information on this should be available from the &Boost.Build; documentation.
|
|
</para>
|
|
<para>
|
|
Building should be possible with the default configuration. If you are running into problems,
|
|
it might be wise to adjust your local settings of &Boost.Build; though. Typically you will
|
|
need to get your user-config.jam file to reflect your environment, i.e. used toolsets. Please
|
|
refer to the &Boost.Build; documentation to learn how to do this.
|
|
</para>
|
|
<para>
|
|
To create the libraries you need to open a command shell and change to the
|
|
<emphasis>boost_root</emphasis> directory. From there you give the command
|
|
<programlisting>bjam --toolset=<emphasis>mytoolset</emphasis> stage --with-thread</programlisting>
|
|
Replace <emphasis>mytoolset</emphasis> with the name of your toolset, e.g. msvc-7.1 .
|
|
This will compile and put the libraries into the <emphasis>stage</emphasis> directory which is just below the
|
|
<emphasis>boost_root</emphasis> directory. &Boost.Build; by default will generate static and
|
|
dynamic variants for debug and release.
|
|
</para>
|
|
<note>
|
|
Invoking the above command without the --with-thread switch &Boost.Build; will build all of
|
|
the Boost distribution, including &Boost.Thread;.
|
|
</note>
|
|
<para>
|
|
The next step is to copy your libraries to a place where your linker is able to pick them up.
|
|
It is also quite possible to leave them in the stage directory and instruct your IDE to take them
|
|
from there.
|
|
</para>
|
|
<para>
|
|
In your IDE you then need to add <emphasis>boost_root</emphasis>/boost to the paths where the compiler
|
|
expects to find files to be included. For toolsets that support <emphasis>auto-linking</emphasis>
|
|
it is not necessary to explicitly specify the name of the library to link against, it is sufficient
|
|
to specify the path of the stage directory. Typically this is true on Windows. For gcc you need
|
|
to specify the exact library name (including all the tags). Please don't forget that threading
|
|
support must be turned on to be able to use the library. You should be able now to build your
|
|
project from the IDE.
|
|
</para>
|
|
</section>
|
|
<section id="thread.build.bjam">
|
|
<title>&Boost.Build; Project</title>
|
|
<para>
|
|
If you have decided to use &Boost.Build; as a build environment for your application, you simply
|
|
need to add a single line to your <emphasis>Jamroot</emphasis> file:
|
|
<programlisting>use-project /boost : {path-to-boost-root} ;</programlisting>
|
|
where <emphasis>{path-to-boost-root}</emphasis> needs to be replaced with the location of
|
|
your copy of the boost tree.
|
|
Later when you specify a component that needs to link against &Boost.Thread; you specify this
|
|
as e.g.:
|
|
<programlisting>exe myapp : {myappsources} /boost//thread ;</programlisting>
|
|
and you are done.
|
|
</para>
|
|
</section>
|
|
<section id="thread.build.source">
|
|
<title>Source Form</title>
|
|
<para>
|
|
Of course it is also possible to use the &Boost.Thread; library in source form.
|
|
First you need to specify the <emphasis>boost_root</emphasis>/boost directory as
|
|
a path where your compiler expects to find files to include. It is not easy
|
|
to isolate the &Boost.Thread; include files from the rest of the boost
|
|
library though. You would also need to isolate every include file that the thread
|
|
library depends on. Next you need to copy the files from
|
|
<emphasis>boost_root</emphasis>/libs/thread/src to your project and instruct your
|
|
build system to compile them together with your project. Please look into the
|
|
<emphasis>Jamfile</emphasis> in <emphasis>boost_root</emphasis>/libs/thread/build
|
|
to find out which compiler options and defines you will need to get a clean compile.
|
|
Using the boost library in this way is the least recommended, and should only be
|
|
considered if avoiding dependency on &Boost.Build; is a requirement. Even if so
|
|
it might be a better option to use the library in it's precompiled form.
|
|
Precompiled downloads are available from the boost consulting web site, or as
|
|
part of most linux distributions.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section id="thread.build.testing">
|
|
<title>Testing the &Boost.Thread; Libraries</title>
|
|
<para>
|
|
To test the &Boost.Thread; libraries using &Boost.Build;, simply change to the
|
|
directory <emphasis>boost_root</emphasis>/libs/thread/test and execute the command:
|
|
<programlisting>bjam --toolset=<emphasis>mytoolset</emphasis> test</programlisting>
|
|
</para>
|
|
</section>
|
|
</section>
|