mirror of
https://github.com/boostorg/build.git
synced 2026-02-13 12:22:17 +00:00
Document abstract-target and its subclasses.
[SVN r77757]
This commit is contained in:
Steven Watanabe
115
doc/src/abstract-target.xml
Normal file
115
doc/src/abstract-target.xml
Normal file
@@ -0,0 +1,115 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
|
||||
<section id="bbv2.reference.class.abstract-target">
|
||||
|
||||
<title>Class abstract-target</title>
|
||||
<indexterm>
|
||||
<primary>abstract-target</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
Base class for all abstract targets.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Classes derived from <link linkend="bbv2.reference.class.abstract-target">abstract-target</link>:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<link linkend="bbv2.reference.class.project-target">project-target</link>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<link linkend="bbv2.reference.class.main-target">main-target</link>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<link linkend="bbv2.reference.class.project-target">basic-target</link>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem id="bbv2.reference.class.abstract-target.__init__">
|
||||
<code language="jam">rule __init__ ( name : project-target )</code>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<literal>name</literal>
|
||||
<listitem>
|
||||
<para>Name of the target in Jamfile.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<literal>project-target</literal>
|
||||
<listitem>
|
||||
<para>The project target to which this one belongs.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.abstract-target.name">
|
||||
<indexterm zone="bbv2.reference.class.abstract-target.name">
|
||||
<primary>name</primary>
|
||||
<secondary>Abstract Target</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule name ( )</code>
|
||||
<para>Returns the name of this target.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.abstract-target.project">
|
||||
<indexterm zone="bbv2.reference.class.abstract-target.project">
|
||||
<primary>project</primary>
|
||||
<secondary>Abstract Target</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule project ( )</code>
|
||||
<para>Returns the project for this target.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.abstract-target.location">
|
||||
<indexterm zone="bbv2.reference.class.abstract-target.location">
|
||||
<primary>location</primary>
|
||||
<secondary>Abstract Target</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule location ( )</code>
|
||||
<para>Return the location where the target was declared.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.abstract-target.full-name">
|
||||
<indexterm zone="bbv2.reference.class.abstract-target.full-name">
|
||||
<primary>full-name</primary>
|
||||
<secondary>Abstract Target</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule full-name ( )</code>
|
||||
<para>Returns a user-readable name for this target.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.abstract-target.generate">
|
||||
<indexterm zone="bbv2.reference.class.abstract-target.generate">
|
||||
<primary>generate</primary>
|
||||
<secondary>Abstract Target</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule generate ( property-set )</code>
|
||||
<para>
|
||||
Generates virtual targets for this abstract target using the specified
|
||||
properties, unless a different value of some feature is required by the
|
||||
target. This is an abstract method which must be overriden by derived
|
||||
classes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
On success, returns:
|
||||
<itemizedlist>
|
||||
<listitem>a property-set with the usage requirements to be applied to dependents</listitem>
|
||||
<listitem>a list of produced virtual targets, which may be empty.</listitem>
|
||||
</itemizedlist>
|
||||
If <code language="jam">property-set</code> is empty, performs the
|
||||
default build of this target, in a way specific to the derived class.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
</section>
|
||||
101
doc/src/basic-target.xml
Normal file
101
doc/src/basic-target.xml
Normal file
@@ -0,0 +1,101 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
|
||||
<section id="bbv2.reference.class.basic-target">
|
||||
|
||||
<title>Class basic-target</title>
|
||||
<indexterm>
|
||||
<primary>basic-target</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
Derived from <link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Implements the most standard way of constructing main target alternative from
|
||||
sources. Allows sources to be either files or other main targets and handles
|
||||
generation of those dependency targets.
|
||||
<!-- FIXME: Better description of sources. The sources can be either target
|
||||
references or instances of abstract-target. -->
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem>
|
||||
<code language="jam">rule __init__ ( name : project : sources * : requirements * : default-build * : usage-requirements * )</code>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.basic-target.name">
|
||||
<code language="jam">rule name ( )</code>
|
||||
<para>
|
||||
Returns the name of this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.basic-target.project">
|
||||
<code language="jam">rule project ( )</code>
|
||||
<para>
|
||||
Returns the project for this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.basic-target.location">
|
||||
<code language="jam">rule location ( )</code>
|
||||
<para>
|
||||
Return the location where the target was declared. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.basic-target.full-name">
|
||||
<code language="jam">rule full-name ( )</code>
|
||||
<para>
|
||||
Returns a user-readable name for this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.basic-target.generate">
|
||||
<indexterm zone="bbv2.reference.class.basic-target.generate">
|
||||
<primary>generate</primary>
|
||||
<secondary>Basic Target Method</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule generate ( property-set )</code>
|
||||
<para>
|
||||
Overrides
|
||||
<link linkend="bbv2.reference.class.abstract-target.generate">abstract-target.generate</link>.
|
||||
|
||||
Determines final build properties, generates sources, and calls
|
||||
<link linkend="bbv2.reference.class.basic-target.construct">construct</link>.
|
||||
This method should not be overridden.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
On success, returns:
|
||||
<itemizedlist>
|
||||
<listitem>a property-set with the usage requirements to be applied to dependents</listitem>
|
||||
<listitem>a list of produced virtual targets, which may be empty.</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.basic-target.construct">
|
||||
<indexterm zone="bbv2.reference.class.basic-target.construct">
|
||||
<primary>construct</primary>
|
||||
<secondary>Basic Target Method</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule construct ( name : source-targets * : properties * )</code>
|
||||
<para>
|
||||
Constructs virtual targets for this abstract target and the dependency
|
||||
graph. Returns a usage-requirements property-set and a list of virtual
|
||||
targets. Should be overriden in derived classes.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
</section>
|
||||
83
doc/src/main-target.xml
Normal file
83
doc/src/main-target.xml
Normal file
@@ -0,0 +1,83 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
|
||||
<section id="bbv2.reference.class.main-target">
|
||||
|
||||
<title>Class main-target</title>
|
||||
<indexterm>
|
||||
<primary>main-target</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
Derived from <link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A <link linkend="bbv2.reference.class.main-target">main-target</link>
|
||||
represents a named top-level target in a Jamfile.
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem id="bbv2.reference.class.main-target.name">
|
||||
<code language="jam">rule name ( )</code>
|
||||
<para>
|
||||
Returns the name of this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.main-target.project">
|
||||
<code language="jam">rule project ( )</code>
|
||||
<para>
|
||||
Returns the project for this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.main-target.location">
|
||||
<code language="jam">rule location ( )</code>
|
||||
<para>
|
||||
Return the location where the target was declared. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.main-target.full-name">
|
||||
<code language="jam">rule full-name ( )</code>
|
||||
<para>
|
||||
Returns a user-readable name for this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.main-target.generate">
|
||||
<indexterm zone="bbv2.reference.class.main-target.generate">
|
||||
<primary>generate</primary>
|
||||
<secondary>Main Target Method</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule generate ( property-set )</code>
|
||||
<para>
|
||||
Overrides
|
||||
<link linkend="bbv2.reference.class.abstract-target.generate">abstract-target.generate</link>.
|
||||
|
||||
Select an alternative for this main target, by finding all alternatives
|
||||
whose requirements are satisfied by <literal>property-set</literal> and
|
||||
picking the one with the longest requirements set. Returns the result
|
||||
of calling <link linkend="bbv2.reference.class.basic-target.generate">generate</link>
|
||||
on that alternative.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
On success, returns:
|
||||
<itemizedlist>
|
||||
<listitem>a property-set with the usage requirements to be applied to dependents</listitem>
|
||||
<listitem>a list of produced virtual targets, which may be empty.</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
</section>
|
||||
179
doc/src/project-target.xml
Normal file
179
doc/src/project-target.xml
Normal file
@@ -0,0 +1,179 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
||||
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
||||
|
||||
<section id="bbv2.reference.class.project-target">
|
||||
|
||||
<title>Class project-target</title>
|
||||
<indexterm>
|
||||
<primary>project-target</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
Derived from <link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This class has the following responsibilities:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Maintaining a list of main targets in this project and building them.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Main targets are constructed in two stages:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
When Jamfile is read, a number of calls to 'add-alternative' are made. At
|
||||
that time, alternatives can also be renamed to account for inline targets.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The first time 'main-target' or 'has-main-target' rule is called, all
|
||||
alternatives are enumerated and main targets are created.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.name">
|
||||
<code language="jam">rule name ( )</code>
|
||||
<para>
|
||||
Returns the name of this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.project">
|
||||
<code language="jam">rule project ( )</code>
|
||||
<para>
|
||||
Returns the project for this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.location">
|
||||
<code language="jam">rule location ( )</code>
|
||||
<para>
|
||||
Return the location of the project. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.full-name">
|
||||
<code language="jam">rule full-name ( )</code>
|
||||
<para>
|
||||
Returns a user-readable name for this target. Inherited from
|
||||
<link linkend="bbv2.reference.class.abstract-target">abstract-target</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.generate">
|
||||
<indexterm zone="bbv2.reference.class.project-target.generate">
|
||||
<primary>generate</primary>
|
||||
<secondary>Project Target</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule generate ( property-set )</code>
|
||||
<para>
|
||||
Overrides
|
||||
<link linkend="bbv2.reference.class.abstract-target.generate">abstract-target.generate</link>.
|
||||
|
||||
Generates virtual targets for all the targets contained in this project.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
On success, returns:
|
||||
<itemizedlist>
|
||||
<listitem>a property-set with the usage requirements to be applied to dependents</listitem>
|
||||
<listitem>a list of produced virtual targets, which may be empty.</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.build-dir">
|
||||
<indexterm zone="bbv2.reference.class.project-target.build-dir">
|
||||
<primary>build-dir</primary>
|
||||
<secondary>Project Target Method</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule build-dir ( )</code>
|
||||
<para>
|
||||
Returns the root build directory of the project.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.main-target">
|
||||
<indexterm zone="bbv2.reference.class.project-target.main-target">
|
||||
<primary>main-target</primary>
|
||||
<secondary>Project Target Method</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule main-target ( name )</code>
|
||||
<para>
|
||||
Returns a <link linkend="bbv2.reference.class.main-target">main-target</link>
|
||||
class instance corresponding to <literal>name</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.has-main-target">
|
||||
<indexterm zone="bbv2.reference.class.project-target.has-main-target">
|
||||
<primary>has-main-target</primary>
|
||||
<secondary>Project Target Method</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule has-main-target ( name )</code>
|
||||
<para>
|
||||
Returns whether a <link linkend="bbv2.reference.class.main-target">main-target</link>
|
||||
with the specified name exists.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem id="bbv2.reference.class.project-target.find">
|
||||
<indexterm zone="bbv2.reference.class.project-target.find">
|
||||
<primary>find</primary>
|
||||
<secondary>Project Target Method</secondary>
|
||||
</indexterm>
|
||||
<code language="jam">rule find ( id : no-error ? )</code>
|
||||
<para>
|
||||
Find and return the target with the specified id, treated relative to
|
||||
self. Id may specify either a target or a file name with the target taking
|
||||
priority. May report an error or return nothing if the target is not found
|
||||
depending on the <literal>no-error</literal> parameter.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<!--
|
||||
|
||||
I'm not sure whether these should be considered public interfaces.
|
||||
Leave them out for now (SW):
|
||||
|
||||
rule project-module ( )
|
||||
rule get ( attribute )
|
||||
|
||||
-->
|
||||
|
||||
<!--
|
||||
|
||||
The following are not documented because I consider them implementation details (SW):
|
||||
|
||||
rule __init__ ( name : project-module parent-project ?
|
||||
: requirements * : default-build * ) - invoked by the build system.
|
||||
|
||||
rule targets-to-build ( ) - internal to project-target
|
||||
rule mark-target-as-explicit ( target-name * ) - Implementation of explicit
|
||||
rule mark-target-as-always ( target-name * ) - Implementation of always
|
||||
rule add-alternative ( target-instance ) - Implementation of targets.main-target-alternative
|
||||
rule find-really ( id ) - internal to project-target
|
||||
rule build-main-targets ( ) - internal to project-target
|
||||
rule inherit ( parent ) - internal to project-target
|
||||
rule add-constant ( name : value + : type ? ) - Implementation of constant/path-constant
|
||||
|
||||
-->
|
||||
|
||||
</orderedlist>
|
||||
|
||||
</section>
|
||||
@@ -1953,6 +1953,14 @@ import path : native make : native-path make-path ;
|
||||
|
||||
</section>
|
||||
|
||||
<section id="bbv2.reference.class">
|
||||
<title>Builtin classes</title>
|
||||
<xi:include href="abstract-target.xml"/>
|
||||
<xi:include href="project-target.xml"/>
|
||||
<xi:include href="main-target.xml"/>
|
||||
<xi:include href="basic-target.xml"/>
|
||||
</section>
|
||||
|
||||
<section id="bbv2.reference.buildprocess">
|
||||
<title>Build process</title>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user