Subject: [Boost-commit] svn:boost r77757 - trunk/tools/build/v2/doc/src
From: steven_at_[hidden]
Date: 2012-04-04 12:46:40
Author: steven_watanabe
Date: 2012-04-04 12:46:39 EDT (Wed, 04 Apr 2012)
New Revision: 77757
URL: http://svn.boost.org/trac/boost/changeset/77757
Log:
Document abstract-target and its subclasses.
Added:
trunk/tools/build/v2/doc/src/abstract-target.xml (contents, props changed)
trunk/tools/build/v2/doc/src/basic-target.xml (contents, props changed)
trunk/tools/build/v2/doc/src/main-target.xml (contents, props changed)
trunk/tools/build/v2/doc/src/project-target.xml (contents, props changed)
Text files modified:
trunk/tools/build/v2/doc/src/reference.xml | 8 ++++++++
1 files changed, 8 insertions(+), 0 deletions(-)
Added: trunk/tools/build/v2/doc/src/abstract-target.xml
==============================================================================
--- (empty file)
+++ trunk/tools/build/v2/doc/src/abstract-target.xml 2012-04-04 12:46:39 EDT (Wed, 04 Apr 2012)
@@ -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>
Added: trunk/tools/build/v2/doc/src/basic-target.xml
==============================================================================
--- (empty file)
+++ trunk/tools/build/v2/doc/src/basic-target.xml 2012-04-04 12:46:39 EDT (Wed, 04 Apr 2012)
@@ -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>
Added: trunk/tools/build/v2/doc/src/main-target.xml
==============================================================================
--- (empty file)
+++ trunk/tools/build/v2/doc/src/main-target.xml 2012-04-04 12:46:39 EDT (Wed, 04 Apr 2012)
@@ -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>
Added: trunk/tools/build/v2/doc/src/project-target.xml
==============================================================================
--- (empty file)
+++ trunk/tools/build/v2/doc/src/project-target.xml 2012-04-04 12:46:39 EDT (Wed, 04 Apr 2012)
@@ -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>
Modified: trunk/tools/build/v2/doc/src/reference.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/reference.xml (original)
+++ trunk/tools/build/v2/doc/src/reference.xml 2012-04-04 12:46:39 EDT (Wed, 04 Apr 2012)
@@ -1953,6 +1953,14 @@
</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>