Template documentation

From: Thomas Witt (witt_at_[hidden])
Date: 2002-03-28 18:22:18

The attached patch provides the missing documentation for the template target.

Thomas --------------Boundary-00=_69IPLQMVHYVZOVX21OXJ Content-Type: text/x-diff;
charset="us-ascii";
name="build_system.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="build_system.patch"

*** build_system.htm	Fri Mar 29 00:00:22 2002
--- _build_system.htm	Fri Mar 29 00:08:48 2002
***************
*** 100,105 ****
--- 100,106 ----
<ul>
<li>The subproject Rule 
<li>Describing Main Targets 
+ <li>Describing Template Targets
<li>Describing Stage Targets
<li>Example 
</ul>
***************
*** 749,756 ****

<ul>
<li><i>target-type</i> may be one of <tt>exe</tt>, <tt>lib</tt>, <tt>dll</tt>, 
! or <tt>stage</tt>. These are actually names of Jam rules. Additional main 
! target rules are possible; see <tt><a href"../../status/Jamfile">status/Jamfile</a></tt> or <tt><a href"../../libs/python/build/Jamfile">libs/python/build/Jamfile</a></tt> for 
examples.<br>
--- 750,757 ----

<ul>
<li><i>target-type</i> may be one of <tt>exe</tt>, <tt>lib</tt>, <tt>dll</tt>, 
! <tt>stage</tt> or <tt>template</tt>. These are actually names of Jam rules.
! Additional main target rules are possible; see <tt><a href"../../status/Jamfile">status/Jamfile</a></tt> or <tt><a href"../../libs/python/build/Jamfile">libs/python/build/Jamfile</a></tt> for 
examples.<br>
***************
*** 767,775 ****
file in the build system.<br>
<br>
<li><i>sources</i> is a list of paths to source files and dependency targets. 
! A dependency target path is preceded by <tt>&lt;lib&gt;, &lt;dll&gt;, 
! </tt>or <tt>&lt;exe&gt; </tt>, and the final path component specifies 
! the name of a main target in a Jamfile located in the directory given 
by the initial path components. Paths may be absolute or relative. The 
type of dependency is also used to decide how to link to it when needed. 
Specifying a <tt>&lt;lib&gt;</tt> indicates the use of static linking, 
--- 768,776 ----
file in the build system.<br>
<br>
<li><i>sources</i> is a list of paths to source files and dependency targets. 
! A dependency target path is preceded by <tt>&lt;template&gt;, &lt;lib&gt;,
! &lt;dll&gt;, </tt>or <tt>&lt;exe&gt; </tt>, and the final path component
! specifies the name of a main target in a Jamfile located in the directory given 
by the initial path components. Paths may be absolute or relative. The 
type of dependency is also used to decide how to link to it when needed. 
Specifying a <tt>&lt;lib&gt;</tt> indicates the use of static linking, 
***************
*** 838,843 ****
--- 839,854 ----
"#default_build">default-BUILD</a></i>, more-specific qualification
overrides less-specific.

+ <blockquote> </blockquote>
+ <h4><a name="template_targets">Describing Template Targets</a></h4>
+ <p>Template targets provide a way to handle commonalities between a projects targets. They have the same
+ form as main targets but do not initiate build requests.
+ A target that lists a template as a dependency inherits all the settings from the template, i.e.
+ the templates sources, requirements and default build settings will be added to the targets settings.
+ Paths mentioned in a template definition are always relative to the subdirectory of the Jamfile
+ containing the templates definition, regardless of the subdirectory of the dependent main target.
+ Typically a project will have at least one template target that handles defines, include paths
+ and additional compiler flags common to all targets in the project.

<blockquote> </blockquote>
<h4><a name="stage_targets">Describing Stage Targets</a></h4>
***************
*** 856,862 ****
created. <br>
<br>
<li><i>sources</i> is the same as main targets and one can list both generated 
! targets like <tt>&lt;exe&gt;test_exe</tt> and individual files.<br>
<br>
<li> <i>Requirements</i> the build properties specified are used as with main 
targets. But one additional type of requirement is possible: <tt>&lt;tag&gt;</tt>... 
--- 867,874 ----
created. <br>
<br>
<li><i>sources</i> is the same as main targets and one can list both generated 
! targets like <tt>&lt;exe&gt;test_exe</tt> and individual files, but no template
! targets<br>
<br>
<li> <i>Requirements</i> the build properties specified are used as with main 
targets. But one additional type of requirement is possible: <tt>&lt;tag&gt;</tt>... 
***************
*** 880,895 ****
</ul>
<h4><a name="jamfile_example">Example</a></h4>

! <p>This artificially complex example shows how an executable called "foo"
! might be described in a Jamfile. The executable is composed of the sources
! <tt>./foo.cpp</tt> and <tt>./src/bar.cpp</tt> (specified relative to the
! directory in which the Jamfile resides), and the built target which results
! from building the target <tt>baz</tt> as described in
! <tt>../bazlib/Jamfile</tt>.

<blockquote>
<pre>
! exe foo : foo.cpp src/bar.cpp &lt;lib&gt;../bazlib/baz
## Requirements ##
: &lt;include&gt;../bazlib/include 
&lt;define&gt;BUILDING_FOO

--- 892,908 ----
</ul>
<h4><a name="jamfile_example">Example</a></h4>

! <p>This artificially complex example shows how two executables called "foo"
! and "fop" might be described in a Jamfile. All common settings are factored out
! in the templates "base" and "executable". Foo is composed of the sources
! <tt>./foo.cpp</tt> and <tt>./src/bar.cpp</tt> (specified relative to the
! directory in which the Jamfile resides). Fop only has one sourcefile <tt>./fop.cpp</tt>.
! Both executables link against the built target which results from building the target 
! <tt>baz</tt> as described in <tt>../bazlib/Jamfile</tt>.

<blockquote>
<pre>
! template base : 
## Requirements ##
: &lt;include&gt;../bazlib/include 
&lt;define&gt;BUILDING_FOO

***************
*** 905,910 ****
--- 918,930 ----
: debug release
&lt;debug&gt;&lt;runtime-link&gt;static/dynamic
;
+ 
+ template executable : &lt;template&gt;base &lt;lib&gt;../bazlib/baz ;
+ 
+ exe foo : &lt;template&gt;executable foo.cpp src/bar.cpp ;
+ 
+ exe fop : &lt;template&gt;executable fop.cpp ;
+ 
</pre>
</blockquote>

 --------------Boundary-00=_69IPLQMVHYVZOVX21OXJ--