tools/build/v2/doc/src/project-target.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4
   5 <section id="bbv2.reference.class.project-target">
   6
   7   <title>Class project-target</title>
   8   <indexterm>
   9     <primary>project-target</primary>
  10   </indexterm>
  11
  12 <programlisting language="jam">
  13 class project-target : <link linkend="bbv2.reference.class.abstract-target">abstract-target</link> {
  14     rule <link linkend="bbv2.reference.class.project-target.generate">generate</link> ( property-set )
  15     rule <link linkend="bbv2.reference.class.project-target.build-dir">build-dir</link> ( )
  16     rule <link linkend="bbv2.reference.class.project-target.main-target">main-target</link> ( name )
  17     rule <link linkend="bbv2.reference.class.project-target.has-main-target">has-main-target</link> ( name )
  18     rule <link linkend="bbv2.reference.class.project-target.find">find</link> ( id : no-error ? )
  19
  20     # Methods inherited from <link linkend="bbv2.reference.class.abstract-target">abstract-target</link>
  21     rule <link linkend="bbv2.reference.class.abstract-target.name">name</link> ( )
  22     rule <link linkend="bbv2.reference.class.abstract-target.project">project</link> ( )
  23     rule <link linkend="bbv2.reference.class.abstract-target.location">location</link> ( )
  24     rule <link linkend="bbv2.reference.class.abstract-target.full-name">full-name</link> ( )
  25 }
  26 </programlisting>
  27
  28   <para>
  29     This class has the following responsibilities:
  30     <itemizedlist>
  31       <listitem>
  32         <para>
  33           Maintaining a list of main targets in this project and building them.
  34         </para>
  35       </listitem>
  36     </itemizedlist>
  37   </para>
  38
  39   <orderedlist>
  40
  41     <listitem id="bbv2.reference.class.project-target.generate">
  42       <indexterm zone="bbv2.reference.class.project-target.generate">
  43         <primary>generate</primary>
  44         <secondary>Project Target</secondary>
  45       </indexterm>
  46       <code language="jam">rule generate ( property-set )</code>
  47       <para>
  48         Overrides
  49         <link linkend="bbv2.reference.class.abstract-target.generate">abstract-target.generate</link>.
  50
  51         Generates virtual targets for all the targets contained in this project.
  52       </para>
  53
  54       <para>
  55         On success, returns:
  56         <itemizedlist>
  57           <listitem>a property-set with the usage requirements to be applied to dependents</listitem>
  58           <listitem>a list of produced virtual targets, which may be empty.</listitem>
  59         </itemizedlist>
  60       </para>
  61     </listitem>
  62
  63     <listitem id="bbv2.reference.class.project-target.build-dir">
  64       <indexterm zone="bbv2.reference.class.project-target.build-dir">
  65         <primary>build-dir</primary>
  66         <secondary>Project Target Method</secondary>
  67       </indexterm>
  68       <code language="jam">rule build-dir ( )</code>
  69       <para>
  70         Returns the root build directory of the project.
  71       </para>
  72     </listitem>
  73
  74     <listitem id="bbv2.reference.class.project-target.main-target">
  75       <indexterm zone="bbv2.reference.class.project-target.main-target">
  76         <primary>main-target</primary>
  77         <secondary>Project Target Method</secondary>
  78       </indexterm>
  79       <code language="jam">rule main-target ( name )</code>
  80       <para>
  81         Returns a <link linkend="bbv2.reference.class.main-target">main-target</link>
  82         class instance corresponding to <literal>name</literal>.
  83         Can only be called after the project has been fully loaded.
  84       </para>
  85     </listitem>
  86
  87     <listitem id="bbv2.reference.class.project-target.has-main-target">
  88       <indexterm zone="bbv2.reference.class.project-target.has-main-target">
  89         <primary>has-main-target</primary>
  90         <secondary>Project Target Method</secondary>
  91       </indexterm>
  92       <code language="jam">rule has-main-target ( name )</code>
  93       <para>
  94         Returns whether a <link linkend="bbv2.reference.class.main-target">main-target</link>
  95         with the specified name exists.
  96         Can only be called after the project has been fully loaded.
  97       </para>
  98     </listitem>
  99
 100     <listitem id="bbv2.reference.class.project-target.find">
 101       <indexterm zone="bbv2.reference.class.project-target.find">
 102         <primary>find</primary>
 103         <secondary>Project Target Method</secondary>
 104       </indexterm>
 105       <code language="jam">rule find ( id : no-error ? )</code>
 106       <para>
 107         Find and return the target with the specified id, treated relative to
 108         self. Id may specify either a target or a file name with the target taking
 109         priority. May report an error or return nothing if the target is not found
 110         depending on the <literal>no-error</literal> parameter.
 111       </para>
 112     </listitem>
 113
 114     <!--
 115
 116     I'm not sure whether these should be considered public interfaces.
 117     Leave them out for now (SW):
 118
 119     rule project-module ( )
 120     rule get ( attribute )
 121
 122     -->
 123
 124     <!--
 125
 126     The following are not documented because I consider them implementation details (SW):
 127
 128     rule __init__ ( name : project-module parent-project ?
 129         : requirements * : default-build * ) - invoked by the build system.
 130
 131     rule targets-to-build ( ) - internal to project-target
 132     rule mark-target-as-explicit ( target-name * ) - Implementation of explicit
 133     rule mark-target-as-always ( target-name * ) - Implementation of always
 134     rule add-alternative ( target-instance ) - Implementation of targets.main-target-alternative
 135     rule find-really ( id ) - internal to project-target
 136     rule build-main-targets ( ) - internal to project-target
 137     rule inherit ( parent ) - internal to project-target
 138     rule add-constant ( name : value + : type ? ) - Implementation of constant/path-constant
 139
 140     -->
 141
 142   </orderedlist>
 143
 144 </section>