[Boost-commit] svn:boost r77757 - trunk/tools/build/v2/doc/src

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>