build/doc/src/project-target.xml

<?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>