boost/build
2
0
Fork 0
mirror of https://github.com/boostorg/build.git synced 2026-02-20 02:32:13 +00:00
Code Issues Projects Releases Wiki Activity

Cleanups

Browse Source 
[SVN r23366]
This commit is contained in:
Dave Abrahams
2004-07-06 10:05:32 +00:00
parent 8859a3a9b3
commit 6e1e12c7b7
3 changed files with 193 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
v2/doc/src/howto.xml
View File

@@ -26,8 +26,11 @@
</para>
<para>
Finally, if nothing applies to you, write to our mailing list,
telling what information you'd like to know.
If you have questions, please post them to our <ulink
url="../../../../more/mailing_lists.htm#jamboost">mailing
list</ulink>, and be sure to indicate in the subject line that
you're asking about Boost.Build <emphasis
role="bold">V2</emphasis>.
</para>
</chapter>

113
v2/doc/src/install.xml
View File

@@ -6,54 +6,81 @@
<title>Installation</title>
<para>
Assuming you're installing Boost.Build from released source
distribution, the following steps are needed. All paths are
given relatively to Boost.Build root directory, which is the
directory with the document you are reading.
This section describes how to install Boost.Build from a
released source distribution. All paths are given relative to
the <firstterm>Boost.Build v2 root directory</firstterm>, which is
<!-- the normal location of the document you are reading.
Boost.Build is -->
<!-- That is a lie AFAICT, at least in a Boost distro. You need
to say something that will be true if you want to cover BBv2 as
distributed separately -->
located in the <filename>tools/build/v2</filename> subdirectory
of a full <ulink url="http://www.boost.org">Boost</ulink>
distribution.
</para>
<orderedlist>
<listitem>
<simpara>
Go to "jam_src" directory and build Boost.Jam. Two convenient
scripts are provided, "build.sh" (for Unix systems) and
"build.bat" (for Windows). Run the appropriate one and
Boost.Jam will be built to directory
<filename>bin.{platform_name}.</filename>. The <ulink url=
"../jam_src/index.html">Boost.Jam documentation</ulink> has
more details in case you need them.
Boost.Build uses <ulink
url= "../jam_src/index.html">Boost.Jam</ulink>, an
extension of the <ulink
url="http://www.perforce.com/jam/jam.html">Perforce
Jam</ulink> portable <command>make</command> replacement. The
recommended way to get Boost.Jam is to <emphasis
role="bold"><ulink
url= "http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=72941">download
a prebuilt executable</ulink></emphasis> from SourceForge.
If a prebuilt executable is not provided for your platform
or you are using Boost's sources in an unreleased state, it
may be neccessary to <ulink
url= "../../jam_src/index.html#building_bjam">build <command>bjam</command>
from sources</ulink> included in the Boost source tree.
</simpara>
</listitem>
<listitem>
<para>
Place the Boost.Jam binary, called "bjam" or "bjam.exe",
somewhere in your <envar>PATH</envar>. Go to the root
directory of Boost.Build and run "bjam --version". You should
get
<screen>Boost.Build V2 (Milestone N)</screen>
To install Boost.Jam, copy the executable,
called <command>bjam</command>
or <command>bjam.exe</command> to a location accessible in
your <envar>PATH</envar>. Go to the Boost.Build root
directory and
run <command>bjam <option>--version</option></command>. You
should see:
(where N is the version you've downloaded).
<screen>
Boost.Build V2 (Milestone N)
Boost.Jam xx.xx.xx
</screen>
where N is the version of Boost.Build you're using.
</para>
</listitem>
<listitem>
<simpara>
Configure toolsets to use. Open the
<filename>user-config.jam</filename> file and follow
instructions there to specify what compiles/libraries you
have and where they are located.
Configure Boost.Build to recognize the build resources (such
as compilers and libraries) you have installed on your
system. Open the
<filename>user-config.jam</filename> file in the Boost.Build
root directory and follow the instructions there to describe
your toolsets and libraries, and, if neccessary, where they
are located.
</simpara>
</listitem>
<listitem>
<simpara>
You should now be able to go to
<filename>example/hello</filename>, and run
You should now be able to go to the
<filename>example/hello/</filename> directory and run
<command>bjam</command> there. A simple application will be
built. You can also play with other projects in
<filename>example</filename>.
built. You can also play with other projects in the
<filename>example/</filename> directory.
<!-- This part should not go into intoduction docs, but we need to
place it somewhere.
@@ -69,43 +96,47 @@
</orderedlist>
<para>
If you use Boost distribution, or Boost CVS, the Boost.Build
root is located at <filename>$boost_root/tools/build/v2</filename>
and the installation steps are the same. However, don't skip
the bjam rebuilding step, even if you have a previous version.
CVS version of Boost.Build requires CVS version of Boost.Jam.
If you are using Boost's CVS state, be sure to
rebuild <command>bjam</command> even if you have a previous
version. The CVS version of Boost.Build requires the CVS
version of Boost.Jam.
</para>
<para>
When starting a new project which uses Boost.Build, you need
to make sure that build system can be found. There are two
ways.
When <command>bjam</command> is invoked, it always needs to be
able to find the Boost.Build root directory, where the
interpreted source code of Boost.Build is located. There are
two ways to tell <command>bjam</command> about the root directory:
</para>
<itemizedlist>
<listitem>
<simpara>
Set enviromnetal variable <envar>BOOST_BUILD_PATH</envar>
to the absolute path to Boost.Build installation directory.
Set the environment variable <envar>BOOST_BUILD_PATH</envar>
to the absolute path of the Boost.Build root directory.
</simpara>
</listitem>
<listitem>
<para>
Create, at the top of your project, a file called
At the root directory of your project or in any of its
parent directories, create a file called
<filename>boost-build.jam</filename>, with a single line:
<programlisting>
boost-build /path/to/boost.build ;
boost-build <replaceable>/path/to/boost.build</replaceable> ;
</programlisting>
</para>
</listitem>
</itemizedlist>
<para>If you're trying to use Boost.Build V2 on Boost itself, please
note that when building Boost, V1 is used by default. You'd have
to add <option>--v2</option> command line option to all "bjam"
invocations.</para>
<para><emphasis role="bold">N.B.</emphasis>
When <command>bjam</command> is invokedfrom anywhere in the Boost
directory tree <emphasis>other than</emphasis> the Boost.Build root
and its subdirectories, <ulink url="../../tools/build">Boost.Build
v1</ulink> is used by default. To overide the default and use
Boost.Build v2, you have to add the <option>--v2</option> command
line option to all <command>bjam</command> invocations.</para>
</chapter>

179
v2/doc/src/tutorial.xml
View File

@@ -9,49 +9,56 @@
<title>Hello, world</title>
<para>The simplest project that Boost.Build can construct is
stored in example/hello directory. The targets are declared in
a file called <filename>Jamfile</filename>, which contains the
following:
stored in <filename>example/hello/</filename> directory. The
project is described by a file
called <filename>Jamfile</filename> that contains:
<programlisting>
exe hello : hello.cpp ;
</programlisting>
Even with this simple setup, you can do some interesting
things. First of all, running "bjam" would build binary "hello"
from hello.cpp, in debug version. After that, you can run
things. First of all, just invoking <command>bjam</command> will
build the debug variant of the <command>hello</command>
executable by compiling and
linking <filename>hello.cpp</filename>. Now, to build the
release variant of <command>hello</command>, invoke
<screen>
bjam release
</screen>
which would create release version of the 'hello' binary.
Note that debug and release version would be created in different
directories, so if you want to switch from debug to release
version and back, no recompilation is needed. Let's extend the
example by adding another line to Jamfile:
Note that debug and release variants are created in different
directories, so you can switch between variants or even build
multiple variants at once, without any unneccessary
recompilation. Let's extend the example by adding another line
to our project's <filename>Jamfile</filename>:
<programlisting>
exe hello2 : hello.cpp ;
</programlisting>
You can now rebuild both debug and release versions:
Now we can build both the debug and release variants of our
project:
<screen>
bjam debug release
</screen>
You'll see that two versions of "hello2" binary are linked.
Of course, hello.cpp won't be recompiled. Now you decide to remove
all build products. You do that with the following command
Note that two variants of <command>hello2</command> are linked.
Since we have already built both variants
of <command>hello</command>, hello.cpp won't be recompiled;
instead the existing object files will just be linked into the
corresponding variants of <command>hello2</command>. Now
let's remove all the built products:
<screen>
bjam --clean debug release
</screen>
It's also possible to create or clean only specific targets.
Both following commands are legal and create or clean only files
that belonging the the named binary:
It's also possible to build or clean specific targets. The
following two commands, respectively, build or clean only the
debug version of <command>hello2</command>.
<screen>
bjam hello2
@@ -63,67 +70,112 @@ bjam --clean hello2
<section id="bbv2.tutorial.properties">
<title>Properties</title>
<para>Boost.Build attempts to allow building different variants of
projects, e.g. for debugging and release, or in single and
multithreaded mode. In order to stay portable, it uses the
concept of <emphasis>features</emphasis>, which is abstract aspect of
build configuration. <emphasis>Property</emphasis> is just a (feature,
value) pair. For example, there's a feature "debug-symbols", which can
have a value of "on" or "off". When users asks to build project is a
particual value, Boost.Build will automatically find the
appropriate flags to the used compiler.</para>
<para>
To portably represent aspects of target configuration such as
debug and release variants, or single- and multi-threaded
builds, Boost.Build uses <firstterm>features</firstterm> with
associated <firstterm>values</firstterm>. For
example, the "debug-symbols" feature can have a value of "on" or
"off". A <firstterm>property</firstterm> is just a (feature,
value) pair. When a user initiates a build, Boost.Build
automatically translates the requested properties into appropriate
command-line flags for invoking toolset components like compilers
and linkers.</para>
<para>The "release" and "debug" in bjam invocation that we've seen
are just are short form of specifying values of feature
"variant". There is a lot of builtin features, and it's possible
to write something like:</para>
<para>There are many built-in features that can be combined to
produce arbitrary build configurations. The following command
builds the project's &quot;release&quot; variant with inlining
disabled and debug symbols enabled:
<screen>
bjam release inlining=off debug-symbols=on
</screen>
</para>
<para>
The first command line element specified the value of feature
"variant". The feature is very common and is therefore special
&#x2014; it's possible to specify only value. Another feature,
"inlining" is not special, and you should use
<para>Properties on the command-line are specified with the syntax:
<screen>
feature-name=feature-value
<replaceable>feature-name</replaceable>=<replaceable>feature-value</replaceable>
</screen>
</para>
syntax for it. Complete description of features can be found
<link linkend="bbv2.reference.features">here</link>. The set of
properties specified in the command line constitute
<emphasis>build request</emphasis> &#x2014; the desired properties
for requested targets, or for the project in the current
directory. The actual set of properties used for building is
often different. For example, when compiling a program you need
some include paths. It's not reasonable to ask the user to specify
those paths with each bjam invocation, so must be specified in
Jamfile and added to the build request. For another example,
certain application can only be linked in multithreaded mode. To
support such situations, every target is allowed to specify
<emphasis>requirements</emphasis> -- properties that are required
to its building. Consider this example:
<para>The "release" and "debug" that we've seen
in <command>bjam</command> invocations are just a shorthand way to
specify values of the "variant" feature. For example, the command
above could also have been written this way:
<screen>
bjam variant=release inlining=off debug-symbols=on
</screen>
</para>
<para> &quot;variant&quot; is so commonly-used that it has been given
special status as an <firstterm>implicit</firstterm> feature
&#x2014; Boost.Build will deduce the its identity just from the name
of one of its values.
</para>
<para>
A complete description of features can be found
<link linkend="bbv2.reference.features">here</link>.
</para>
<section id="bbv2.tutorial.properties.requirements">
<title>Build Requests and Target Requirements</title>
<para>
The set of properties specified in the command line constitute a
<firstterm>build request</firstterm> &#x2014; a description of
the desired properties for building the requested targets (or,
if no targets were explicitly requested, the project in the
current directory). The <emphasis>actual</emphasis> properties
used for building targets is typically a combination of the
build request and properties derived from the
project's <filename>Jamfile</filename>s. For example, the
locations of <code>#include</code>d header files are normally
not specified on the command-line, but described
in <filename>Jamfile</filename>s as <firstterm>target
requirements</firstterm> and automatically combined with the
build request for those targets. Multithread-enabled
compilation is another example of a typical target requirement.
The <filename>Jamfile</filename> fragment below illustrates how
these requirements might be specified.
</para>
<programlisting>
exe hello
: hello.cpp
: &lt;include&gt;/home/ghost/Work/boost &lt;threading&gt;multi
;
</programlisting>
In this case, when hello is build, the two specified properties will
always be present. This leads to a question: what if user explictly
requested single-threading. The answer is that requirement can
affect build properties only to a certain degree: the requested and
actual properties must be link-compatible. See <xref linkend=
"bbv2.reference.variants.compat"/> below. If they are not link
compatible, the bulding of the target is skipped. Previously, we've
added "hello2" target. Seems like we have to specify the same
requirements for it, which results in duplication. But there's a
better way. Each project (i.e. each Jamfile), can specify a set of
attributes, including requirements:
<para> When <filename>hello</filename> is built, the two requirements
specified above will normally always be present. If the build
request given on the <command>bjam</command> command-line
explictly contradicts a target's requirements, the command-line
usually overrides (or, in the case of &quot;free&quot; feautures
like <code>&lt;include&gt;</code>, augments) the target
requirements. However, when a contradiction of a target's
requrements involves certain
<firstterm>link-incompatible</firstterm> features, the target will
be skipped. See <xref linkend=
"bbv2.reference.variants.compat"/> for more information.
</para>
</section>
<section id="bbv2.tutorial.properties.project_attributes">
<title>Project Attributes</title>
<para>
If we want the same requirements for our other
target, <filename>hello2</filename>, we could simply duplicate
them. However, as projects grow, that approach leads to a great
deal of repeated boilerplate in Jamfiles.
Fortunately, there's a better way. Each project (i.e. each
<filename>Jamfile</filename>), can specify a set of attributes,
including requirements:
<programlisting>
project
@@ -134,10 +186,11 @@ exe hello : hello.cpp ;
exe hello2 : hello.cpp ;
</programlisting>
The effect would be as if we specified this requirement for
both "hello" and "hello2".
The effect would be as if we specified the same requirement for
both <command>hello</command> and <command>hello2</command>.
</para>
</section>
</section>
<section id="bbv2.tutorial.hierarchy">
<title>Project hierarchy</title>