townforge/build
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Commit my restructuring of user manual.

Browse Source 
[SVN r23390]
This commit is contained in:
Vladimir Prus 2004-07-07 07:30:48 +00:00
parent 04cf0e5cc5
commit dacedf84d3
4 changed files with 1104 additions and 626 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1396
v2/doc/src/advanced.xml
View File

File diff suppressed because it is too large Load Diff

134
v2/doc/src/architecture.xml
View File

@ -7,13 +7,135 @@
<sidebar>
<para>This document is work-in progress. Don't expect much from it
yet.</para>
yet.</para>
</sidebar>
<section id="bbv2.arch.overview">
<title>Overview</title>
<para>The Boost.Build code is structured in four different components:
"kernel", "util", "build" and "tools". The first two are relatively
uninteresting, so we'll focus on the remaining pair. The "build" component
provides classes necessary to declare targets, determine which properties
should be used for their building, and for creating the dependency
graph. The "tools" component provides user-visible functionality. It
mostly allows to declare specific kind of main targets, and declare
avaiable tools, which are then used when creating the dependency graph.
</para>
</section>
<section id="bbv2.arch.build">
<title>The build layer</title>
<para>The build layer has just four main parts -- abstract targets,
virtual targets, generators and properties. The abstract targets,
represented by the "abstract-target" class, correspond to main targets
-- which, as you recall, can produce different files depending on
properties. Virtual targets, represented by the 'virtual-target' class
correspond to real files. The abstract-target class has a method
'generate', which is given a set of properties and produces virtual
targets for those properties.
</para>
<para>There are several classes derived from "abstract-target". The
"main-target" class represents top-level main target, the "project-target"
acts like container for all main targets, and "basic-target" class is a
base class for all further target types.
</para>
<para>Since each main target can have several alternatives, all top-level
target objects are just containers, referring to "real" main target
classes. The type is that container is "main-target". For example, given:
<programlisting>
alias a ;
lib a : a.cpp : &lt;toolset&gt;gcc ;
</programlisting>
we would have one-top level instance of "main-target-class", which will
contain one instance of "alias-target-class" and one instance of
"lib-target-class". The "generate" method of "main-target" decides
which of the alternative should be used, and call "generate" on the
corresponding instance.
</para>
<para>Each alternative is a instance of a class derived from
"basic-target". The "basic-target.generate" does several things that are
always should be done:
<itemizedlist>
<listitem>
<para>Determines what properties should be used for building the
target. This includes looking at requested properties, requirements,
and usage requirements of all sources.</para>
</listitem>
<listitem>
<para>Builds all sources</para>
</listitem>
<listitem>
<para>Computes the usage requirements which should be passes back.</para>
</listitem>
</itemizedlist>
For the real work of constructing virtual target, a new method
"construct" is called.
</para>
<para>The "construct" method can be implemented in any way by classes
derived from "basic-target", but one specific derived class plays the
central role -- "typed-target". That class holds the desired type of file
to be produces, and calls the generators modules to do the job.
</para>
<para>Generators are Boost.Build abstractions for a tool. For example, one
can register a generator which converts target of type CPP into target of
type OBJ. When run with on a virtual target with CPP type, the generator
will construct the virtual target of type OBJ. The "generators" module
implements an algorithm, which given a list of sources, the desired type
and a list of properties, find all the generators which can perform the conversion.
</para>
<para>The virtual targets which are produces by the main targets form a
graph. Targets which are produces from other ones refer to an instance of
"action" class, which in turn refers to action's sources, which can
further refer to actions. The sources, which are not produces from
anything, don't refer to any actions.
</para>
<para>When all virtual targets are produced, they are "actualized". This
means that the real file names are computed, and the commands that should
be run are generated. This is done by "virtual-target.actualize" and
"action.actualize" methods. The first is conceptually simple, while the
second need additional explanation. The commands in bjam are generated in
two-stage process. First, a rule with the appropriate name (for example
"gcc.compile") is called and is given the names of targets. The rule sets
some variables, like "OPTIONS". After that, the command string is taken,
and variable are substitutes, so use of OPTIONS inside the command string
become the real compile options.
</para>
<para>Boost.Build added a third stage to simplify things. It's now
possible to automatically convert properties to appropriate assignments to
variables. For example, &lt;debug-symbols&gt;on would add "-g" to the
OPTIONS variable, without requiring to manually add this logic to
gcc.compile. This functionality is part of the "toolset" module.
</para>
<para>When target paths are computed and the commands are set, Boost.Build
just gives control to bjam, which controls the execution of
commands.</para>
</section>
<section id="bbv2.arch.tools">
<title>The tools layer</title>
<para>Write me!</para>
</section>
<section id="bbv2.arch.targets">
<title>Targets</title>
<para>There are two user-visible kinds of targets in Boost.Build.
<para>NOTE: THIS SECTION IS NOT EXPECTED TO BE READ!
There are two user-visible kinds of targets in Boost.Build.
First are "abstract" &#x2014; they correspond to things declared
by user, for example, projects and executable files. The primary
thing about abstract target is that it's possible to request them
@ -432,3 +554,11 @@ debug/main-target-a
</section>
</appendix>
<!--
Local Variables:
mode: xml
sgml-indent-data: t
sgml-parent-document: ("userman.xml" "chapter")
sgml-set-face: t
End:
-->

86
v2/doc/src/extending.xml
View File

@ -105,24 +105,86 @@ and linked it.
"../../example/customization">example/customization</ulink>
directory.</para>
</section>
<section id="bbv2.extending.targets">
<title>Target types</title>
</section>
<section id="bbv2.extending.targets">
<title>Target types</title>
<para/>
</section>
<section id="bbv2.extending.tools">
<title>Tools</title>
<para/>
</section>
</section>
<section id="bbv2.extending.rules">
<title>Main target rules</title>
<para>
The main target rule is what creates a top-level target, for example "exe" or
"lib". It's quite likely that's you'll want to declare your own and
there are as much as three way to do that.
</para>
<para>The first is the simplest, but is sufficient in a number of
case. Just write a wrapper rule, which will redirect to any of existing
rules. For example, you have only one library per directory and want all
cpp files in the directory to be compiled. You can achieve this effect
with:
<programlisting>
lib codegen : [ glob *.cpp ] ;
</programlisting>
but what if you want to make it even simple. Then, you add the following
definition to the project-root.jam file:
<programlisting>
rule glib ( name : extra-sources * : requirements * )
{
lib $(name) : [ glob *.cpp ] $(extra-sources) : $(requirements) ;
}
</programlisting>
which would allow to reduce Jamfile to
<programlisting>
glib codegen ;
</programlisting>
</para>
<section id="bbv2.extending.tools">
<title>Tools</title>
<para/>
</section>
<para>The second approach is suitable when your target rule should just
produce a target of specific type. Then, when declaring a type you
should tell Boost.Build that a main target rule should be created.
For example, if you create a module "obfuscate.jam" containing:
<section id="bbv2.extending.rules">
<title>Main target rules</title>
<para/>
</section>
<programlisting>
import type ;
type.register OBFUSCATED_CPP : ocpp : : main ;
import generators ;
generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ;
</programlisting>
and import that module, you'll be able to use the rule "obfuscated-cpp"
in Jamfiles, which will convert source to the OBFUSCATED_CPP type.
</para>
<para>
The remaining method is to declared your own main target class. The
simplest example of this can be found in "build/alias.jam" file. The
current V2 uses this method when transformations are relatively
complex. However, we might deprecate this approach. If you find that you
need to use it (that is, the first two approaches are not sufficient),
please let us know by posting to the mailing list.
</para>
</section>
<section id="bbv2.extending.scanners">
<title>Scanners</title>
<para/>
</section>
</appendix>
<!--
Local Variables:
mode: xml
sgml-indent-data: t
sgml-parent-document: ("userman.xml" "chapter")
sgml-set-face: t
End:
-->

114
v2/doc/src/reference.xml
View File

@ -484,7 +484,7 @@ Boost.Build comes with default versions of those files,
symbol is either a value of an implicit feature, or target to
be built. It is taken to be value of a feature if appropriate
feature exists. Otherwise, it is considered a <link linkend=
"bbv2.advanced.ids">target id</link>. Special target name "clean"
"bbv2.reference.ids">target id</link>. Special target name "clean"
has the same effect as "--clean" option.
</simpara>
</listitem>
@ -631,6 +631,118 @@ linked binaries would be created.
<section id="bbv2.reference.buildreq">
<title>Build request</title>
<section id="bbv2.reference.ids">
<title>Target identifiers and references</title>
<para><emphasis>Target identifier</emphasis> is used to denote a
target. The syntax is:</para>
<programlisting>
target-id -&gt; (project-id | target-name | file-name )
| (project-id | directory-name) "//" target-name
project-id -&gt; path
target-name -&gt; path
file-name -&gt; path
directory-name -&gt; path
</programlisting>
<para>
This grammar allows some elements to be recognized as either
<itemizedlist>
<listitem>
<simpara>
project id (at this point, all project ids start with slash).
</simpara>
</listitem>
<listitem>
<simpara>
name of target declared in current Jamfile (note that target
names may include slash).
</simpara>
</listitem>
<listitem>
<simpara>
a regular file, denoted by absolute name or name relative to
project's sources location.
</simpara>
</listitem>
</itemizedlist>
To determine the real meaning a check is made if project-id
by the specified name exists, and then if main target of that
name exists. For example, valid target ids might be:
<screen>
a -- target in current project
lib/b.cpp -- regular file
/boost/thread -- project "/boost/thread"
/home/ghost/build/lr_library//parser -- target in specific project
</screen>
</para>
<para><emphasis role="bold">Rationale:</emphasis>Target is separated from project by special
separator (not just slash), because:</para>
<itemizedlist>
<listitem>
<simpara>
It emphasises that projects and targets are different things.
</simpara>
</listitem>
<listitem>
<simpara>
It allows to have main target names with slashes.
<!-- The motivation for which is:
So, to summarize:
1. The project which extract tarfile may extract all possible kinds
of targets, and it's reasonable to use them directly from other
project.
2. The rule for unpacking tar is inplemented in terms of
"patch-file", for maintainability, and therefore, must use main
target name which contains slashes?
3. Using sub-Jamfile in "foo" to declare extracted file "foo/b" is
not an option, because you should not change existing tree
That makes good rationale for why main target must contain names.
-->
</simpara>
</listitem>
</itemizedlist>
<para id="bbv2.reference.targets.references">
<emphasis>Target reference</emphasis> is used to
specify a source target, and may additionally specify desired
properties for that target. It has this syntax:</para>
<programlisting>
target-reference -&gt; target-id [ "/" requested-properties ]
requested-properties -&gt; property-path
</programlisting>
<para>
For example,
<programlisting>
exe compiler : compiler.cpp libs/cmdline/&lt;optimization&gt;space ;
</programlisting>
would cause the version of <literal>cmdline</literal> library,
optimized for space, to be linked in even if the
<literal>compiler</literal> executable is build with optimization for
speed.
</para>
</section>
<para/>
</section>