template main-target documentation

From: Thomas Witt (witt_at_[hidden])
Date: 2002-03-07 18:00:59

Hi,

I finally managed to write the documentation for the proposed new main-target 
"template". Please note that the documentation describes template as I 
initially wanted it to be. Note that the supplied patch does not fully 
implement template as it is documented it only cares about the requirement
section.

There were already a few comments on the name and further design issues. I 
left these out so that you can see what I want to achieve. This does not mean 
I think they are all wrong.

As for the name I think requirement-set is not a suitable name for templateas 
it is documented. Its scope goes well beyond requirements. If we decide only 
the requirement portion is needed requirement-set would certainly be a good 
name for such a thing.

Dave, I still think the analogy between templates and targets is ok. These
things _are_ pretty much like targets. Basically they are incomplete targets. 
I hope the documentation makes this clear.

Thomas

 --------------Boundary-00=_N9LM5M0LUA3888OI2W74 Content-Type: text/plain;
charset="us-ascii";
name="template.txt"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="template.txt"

Describing Template Targets

Template targets do not build files, they just act as templates when defining other
main-targets. Like normal build targets templates can have sources, requirements and
default builds. The syntax is the same as with normal main-targets.

In order to use a template it must be listed as a dependency in the
sources of a main-target. The main-target that uses a template inherits the sources,
requirements and default build settings from the template. A template dependency in principal
has the same effect as copying the sources, requirements and default build definitions
from the template definition to the respective sections of the target definition. The
only difference is that every path from the template definition must be adjusted according
to the relative position of template and main-target.

Template ease project maintenance in that they provide a convenient way to handle common properties
for the projects main-targets. They are designed to solve the problem of duplicated definition
of common properties that can make large projects unmanageable. In order to allow for a single
point of definition for each property templates offer great flexibility. A common template can be
used by an arbitrary number of main-targets, template usage is not tied to the directory structure
of the project. As templates can themself depend on templates template granularity can be tailored to
the specific projects needs. Template names are non global, in order to reduce name clashes. The same
name restrictions as for other main-targets exists.

The following example shows template usage for a small project. A base template is used to handle
defines and include pathes and an exe template holds additional information about external libraries
to link.

-------------------------------------------------
project-root;

template base
:
:
<define>MY_APP
<debug><define>MY_DEBUG
<include>include/my_includes
<gcc><debug><cxxflags>-gstabs+
:
debug
<runtime-link>dynamic
;

template library
:
<template>base
:
:
# Only dependend lib's will be built
<suppress>true
;

template exe
:
# Exe's do need base as well
<template>base
# All exe's should link libBaseServices
<lib>baseservices/BaseServices
:
<library-path>$(A_PATH)
<library-file>AnotherLib
:
;

subinclude baseservices ;

-----------------------------------------------------

-----------------------------------------------------
subproject baseservices ;

lib BaseServices
:
<template>../library
baseservice.cpp
:
:
;

# Foo will link BaseServices through exe template
exe Foo
:
<template>../exe
foo.cpp
:
# Target specific requirements can go here
:
# Target specific default builds can go here
;

----------------------------------------------------------

 --------------Boundary-00=_N9LM5M0LUA3888OI2W74--