2
0
mirror of https://github.com/boostorg/build.git synced 2026-02-17 01:32:12 +00:00

Lots of documentation rearrangement and improvement.

[SVN r18927]
This commit is contained in:
Vladimir Prus
2003-07-03 09:13:05 +00:00
parent 01a997e299
commit d649f55b80
8 changed files with 1542 additions and 934 deletions

File diff suppressed because it is too large Load Diff

View File

@@ -21,12 +21,12 @@
br.clear { clear: left }
div.alert { color: red }
table { align: center; border: thin; }
</style>
</style>
</head>
<!-- Things yet to document:
- build request, build request expansion and directly requested targets
- conditional properties
-->
- build request, build request expansion and directly requested targets
- conditional properties
-->
<body>
<p><a href="../../index.htm"><img class="banner" height="86" width="277"
@@ -36,11 +36,39 @@
</h1>
<hr>
<div class="alert">
<p>This document is work-in progress. Don't expect much from it
yet.</p>
</div>
<dl class="page-index">
<dt><a href="#dependencies">Dependency scanning</a></dt>
</dl>
<hr>
<h2><a name="targets">Targets</a></h2>
<p>There are two user-visible kinds of targets in Boost.Build. First are
"abstract" &mdash; they correspond to things declared by user, for
example, projects and executable files. The primary thing about abstract
target is that it's possible to request them to be build with a
particular values of some properties. Each combination of properties may
possible yield different set of real file, so abstract target do not have
a direct correspondence with files.</p>
<p>File targets, on the contary, are associated with concrete files.
Dependency graphs for abstract targets with specific properties are
constructed from file targets. User has no was to create file targets,
however it can specify rules that detect file type for sources, and also
rules for transforming between file targets of different types. That
information is used in constructing dependency graph, as desribed in the
<a href="#generators">next section</a>. <b>Note:</b>File targets are not
the same as targets in Jam sense; the latter are created from file
targets at the latest possible moment. <b>Note:</b>"File target" is a
proposed name for what we call virtual targets. It it more understandable
by users, but has one problem: virtual targets can potentially be
"phony", and not correspond to any file.</p>
<h2 id="dependency_scanning">Dependency scanning</h2>
<p>Dependency scanning is the process of finding implicit dependencies
@@ -208,6 +236,58 @@
bound via LOCATE_TARGET to "build" and we'll call INCLUDE on that found
target, instread of creating a completely unrelated one.</li>
</ol>
<div class="alert">
The remainder of this document is not indended to be read at all. This
will be rearranged in future.
</div>
<h4>File targets</h4>
As described above, file targets corresponds to files that Boost.Build
manages. User's may be concerned about file targets in three ways: when
declaring file target types, when declaring transformations between
types, and when determining where file target will be placed. File
targets can also be connected with actions, that determine how the target
is created. Both file targets and actions are implemented in the
<tt>virtual-target</tt> module.
<h5>Types</h5>
A file target can be given a file, which determines what transformations
can be applied to the file. The <tt>type.register</tt> rule declares new
types. File type can also be assigned a scanner, which is used to find
implicit dependencies. See <a href="#dependency_scanning">dependency
scanning</a> below.
<h4>Target paths</h4>
<p>To distinguish targets build with different properties, they are put
in different directories. Rules for determining target paths are given
below:</p>
<ol>
<li>All targets are placed under directory corresponding to the project
where they are defined.</li>
<li>Each non free, non incidental property cause an additional element
to be added to the target path. That element has the form
<tt>&lt;feature-name&gt;-&lt;feature-value&gt;</tt> for ordinary
features and <tt>&lt;feature-value&gt;</tt> for implicit ones. [Note
about composite features].</li>
<li>If the set of free, non incidental properties is different from the
set of free, non incidental properties for the project in which the
main target that uses the target is defined, a part of the form
<tt>main_target-&lt;name&gt;</tt> is added to the target path.
<b>Note:</b>It would be nice to completely track free features also,
but this appears to be complex and not extremely needed.</li>
</ol>
<p>For example, we might have these paths:</p>
<pre>
debug/optimization-off
debug/main-target-a
</pre>
<hr>
<p class="revision">Last modified: June 30, 2003</p>

154
doc/extending.html Normal file
View File

@@ -0,0 +1,154 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1st April 2002), see www.w3.org">
<!--tidy options: -i -wrap 78 -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="../../boost.css">
<title>Boost.Build v2 extender manual</title>
<style type="text/css">
hr { color: black }
p.revision { text-align: right; font-style: italic }
pre.code { margin-left: 2em }
pre.output { margin-left: 2em }
img.banner { border: 0; float: left }
h1 { text-align: right }
br.clear { clear: left }
div.alert { color: red }
table { align: center; border: thin; }
</style>
</head>
<!-- Things yet to document:
- build request, build request expansion and directly requested targets
- conditional properties
-->
<body>
<p><a href="../../index.htm"><img class="banner" height="86" width="277"
alt="C++ Boost" src="c++boost.gif"></a></p>
<h1>Boost.Build v2 extender manual<br class="clear">
</h1>
<hr>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#target_types">Target types</a></dt>
<dt><a href="#tools">Tools</a></dt>
<dt><a href="#main_target_rules">Main target rules</a></dt>
<dt><a href="#scanners">Scanners</a></dt>
</dl>
<hr>
<h2 id="introduction">Introduction</h2>
<p>This document explains how to extend Boost.Build to accomodate your
local requirements. Let's start with quite simple, but realistic
example.</p>
<p>Say you're writing an application which generates C++ code. If you
ever did this, you know that it's not nice. Embedding large portions of
C++ code in string literals is very awkward. A much better solution
is:</p>
<ol>
<li>Write the template of the code to be generated, leaving
placeholders at the points which will change</li>
<li>Access the template in your application and replace placeholders
with appropriate text.</li>
<li>Write the result.</li>
</ol>
<p>It's quite easy to archive. You write special verbatim files, which
are just C++, except that the very first line of the file gives a name of
variable that should be generated. A simple tool is created which takes
verbatim file and creates a cpp file with a single char* variable, which
name is taken from the first line of verbatim file, and which value is
properly quoted content of the verbatim file.</p>
<p>Let's see what Boost.Build can do.</p>
<p>First off, Boost.Build has no idea about "verbatim files". So, you
must register a new type. The following code does it:</p>
<pre>
import type ;
type.register VERBATIM : verbatim ;
</pre>
<p>The first parameter to 'type.register' gives the name of declared
type. By convention, it's uppercase. The second parameter is suffix for
this type. So, if Boost.Build sees "code.verbatim" in the list of
sources, it knows that it's of type <tt>VERBATIM</tt>.</p>
<p>Lastly, you need to tool to convert verbatim files to C++. Say you've
stetched such a tool in Python. Then, you have to inform Boost.Build
about the tool. The Boost.Build concept which represent tool is
<em>generator</em>.</p>
<p>First, you say that generator 'inline-file' is able to convert
VERBATIM type into C++:</p>
<pre>
import generators ;
generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
</pre>
<p>Second, you must specify the commands to be run to actually perform
convertion:</p>
<pre>
actions inline-file
{
./inline-file.py $(&lt;) $(&gt;)
}
</pre>
<!-- We use verbatim.inline-file in one place and just inline-file in
another. Is this confusing for user?
-->
<p>Now, we're ready to tie it all together. Put all the code above in
file "verbatim.jam", add "import verbatim ;" to "project-root.jam", and
it's possible to write the following in Jamfile:</p>
<pre>
exe codegen : codegen.cpp class_template.verbatim usage.verbatim ;
</pre>
The verbatim files will be automatically converted into C++ and linked
it.
<p>The complete code is available in <a href=
"../examples-v2/customization">examples-v2/customization</a>
directory.</p>
<h2 id="target_types">Target types</h2>
<h2 id="tools">Tools</h2>
<h2 id="main_target_rules">Main target rules</h2>
<h2 id="scanners">Scanners</h2>
<hr>
<p class="revision">Last modified: Jule 3, 2003</p>
<p>&copy; Copyright Vladimir Prus 2002-2003. Permission to copy, use,
modify, sell and distribute this document is granted provided this
copyright notice appears in all copies. This document is provided ``as
is'' without express or implied warranty, and with no claim as to its
suitability for any purpose.</p>
<!-- sf logo -->
</body>
</html>

View File

@@ -3,7 +3,7 @@
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1st March 2002), see www.w3.org">
"HTML Tidy for Linux/x86 (vers 1st April 2002), see www.w3.org">
<meta name="generator" content="Microsoft FrontPage 5.0">
<meta http-equiv="Content-Type" content=
"text/html; charset=windows-1252">
@@ -14,52 +14,66 @@
<body bgcolor="#FFFFFF" text="#000000">
<img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center"
width="277" height="86">
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=7586&amp;type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" align="right"/></a>
width="277" height="86"> <a href="http://sourceforge.net"><img src=
"http://sourceforge.net/sflogo.php?group_id=7586&amp;type=1" width="88"
height="31" border="0" alt="SourceForge.net Logo" align="right"></a>
<h1>Boost Build System V2 &mdash; supported tools</h1>
<h2>Compilers</h2>
<p>The following compilers pass Boost.Build tests:
<ul>
<li>gcc (various versions), on Linux, NT, and Cygwin.
<li>msvc (various version), on NT and Cygwin.
<li>borland, on NT and Cygwin.
<p>The following compilers pass Boost.Build tests:</p>
<ul>
<li>gcc (various versions), on Linux, NT, and Cygwin.</li>
<li>msvc (various version), on NT and Cygwin.</li>
<li>borland, on NT and Cygwin.</li>
</ul>
<h2>Libraries</h2>
<p>Some important libraries have special support in Boost.Build:
<p>Some important libraries have special support in Boost.Build:</p>
<ul>
<li>STLPort &mdash; on gcc.
<li>QT, including the <tt>moc</tt> and <tt>uic</tt> tools &mdash; on gcc.
<ul>
<li><a href="http://stlport.org">STLport</a> &mdash; on gcc and
msvc.</li>
<li><a href="http://www.trolltech.com/products/qt/index.html">QT</a>,
including the <tt>moc</tt> and <tt>uic</tt> tools &mdash; on gcc.</li>
</ul>
<h2>Other tools</h2>
<ul>
<li>Parser/lexer generators <tt>bison</tt> and <tt>lex</tt>.
<li>XSLT processor <tt>xsltproc</tt>.
<li>The Apache FOP tool.
<li>BoostBook documentation format.
<li>Parser/lexer generators <tt>bison</tt> and <tt>lex</tt>.</li>
<li>XSLT processor <a href=
"http://xmlsoft.org/XSLT/">xsltproc</a>.</li>
<li>The Apache <a href="http://xml.apache.org/fop/index.html">FOP</a>
tool.</li>
<li>BoostBook documentation format.</li>
<li>GNU <a href=
"http://www.gnu.org/software/gettext/gettext.html">gettext</a>
internationalization tools.</li>
</ul>
<hr>
<p>&copy; Copyright Vladimir Prus 2003. Permission to
copy, use, modify, sell and distribute this document is granted provided
this copyright notice appears in all copies. This document is provided
"as is" without express or implied warranty, and with no claim as to its
suitability for any purpose.</p>
<p>&copy; Copyright Vladimir Prus 2003. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability for
any purpose.</p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan
-->26 Apr, 2003
-->Jule 3, 2003
<!--webbot bot="Timestamp" endspan i-checksum="13972"
-->
-->
</p>
</body>
</html>

File diff suppressed because it is too large Load Diff

View File

@@ -21,12 +21,12 @@
br.clear { clear: left }
div.alert { color: red }
table { align: center; border: thin; }
</style>
</style>
</head>
<!-- Things yet to document:
- build request, build request expansion and directly requested targets
- conditional properties
-->
- build request, build request expansion and directly requested targets
- conditional properties
-->
<body>
<p><a href="../../index.htm"><img class="banner" height="86" width="277"
@@ -36,11 +36,39 @@
</h1>
<hr>
<div class="alert">
<p>This document is work-in progress. Don't expect much from it
yet.</p>
</div>
<dl class="page-index">
<dt><a href="#dependencies">Dependency scanning</a></dt>
</dl>
<hr>
<h2><a name="targets">Targets</a></h2>
<p>There are two user-visible kinds of targets in Boost.Build. First are
"abstract" &mdash; they correspond to things declared by user, for
example, projects and executable files. The primary thing about abstract
target is that it's possible to request them to be build with a
particular values of some properties. Each combination of properties may
possible yield different set of real file, so abstract target do not have
a direct correspondence with files.</p>
<p>File targets, on the contary, are associated with concrete files.
Dependency graphs for abstract targets with specific properties are
constructed from file targets. User has no was to create file targets,
however it can specify rules that detect file type for sources, and also
rules for transforming between file targets of different types. That
information is used in constructing dependency graph, as desribed in the
<a href="#generators">next section</a>. <b>Note:</b>File targets are not
the same as targets in Jam sense; the latter are created from file
targets at the latest possible moment. <b>Note:</b>"File target" is a
proposed name for what we call virtual targets. It it more understandable
by users, but has one problem: virtual targets can potentially be
"phony", and not correspond to any file.</p>
<h2 id="dependency_scanning">Dependency scanning</h2>
<p>Dependency scanning is the process of finding implicit dependencies
@@ -208,6 +236,58 @@
bound via LOCATE_TARGET to "build" and we'll call INCLUDE on that found
target, instread of creating a completely unrelated one.</li>
</ol>
<div class="alert">
The remainder of this document is not indended to be read at all. This
will be rearranged in future.
</div>
<h4>File targets</h4>
As described above, file targets corresponds to files that Boost.Build
manages. User's may be concerned about file targets in three ways: when
declaring file target types, when declaring transformations between
types, and when determining where file target will be placed. File
targets can also be connected with actions, that determine how the target
is created. Both file targets and actions are implemented in the
<tt>virtual-target</tt> module.
<h5>Types</h5>
A file target can be given a file, which determines what transformations
can be applied to the file. The <tt>type.register</tt> rule declares new
types. File type can also be assigned a scanner, which is used to find
implicit dependencies. See <a href="#dependency_scanning">dependency
scanning</a> below.
<h4>Target paths</h4>
<p>To distinguish targets build with different properties, they are put
in different directories. Rules for determining target paths are given
below:</p>
<ol>
<li>All targets are placed under directory corresponding to the project
where they are defined.</li>
<li>Each non free, non incidental property cause an additional element
to be added to the target path. That element has the form
<tt>&lt;feature-name&gt;-&lt;feature-value&gt;</tt> for ordinary
features and <tt>&lt;feature-value&gt;</tt> for implicit ones. [Note
about composite features].</li>
<li>If the set of free, non incidental properties is different from the
set of free, non incidental properties for the project in which the
main target that uses the target is defined, a part of the form
<tt>main_target-&lt;name&gt;</tt> is added to the target path.
<b>Note:</b>It would be nice to completely track free features also,
but this appears to be complex and not extremely needed.</li>
</ol>
<p>For example, we might have these paths:</p>
<pre>
debug/optimization-off
debug/main-target-a
</pre>
<hr>
<p class="revision">Last modified: June 30, 2003</p>

154
v2/doc/extending.html Normal file
View File

@@ -0,0 +1,154 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1st April 2002), see www.w3.org">
<!--tidy options: -i -wrap 78 -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="../../boost.css">
<title>Boost.Build v2 extender manual</title>
<style type="text/css">
hr { color: black }
p.revision { text-align: right; font-style: italic }
pre.code { margin-left: 2em }
pre.output { margin-left: 2em }
img.banner { border: 0; float: left }
h1 { text-align: right }
br.clear { clear: left }
div.alert { color: red }
table { align: center; border: thin; }
</style>
</head>
<!-- Things yet to document:
- build request, build request expansion and directly requested targets
- conditional properties
-->
<body>
<p><a href="../../index.htm"><img class="banner" height="86" width="277"
alt="C++ Boost" src="c++boost.gif"></a></p>
<h1>Boost.Build v2 extender manual<br class="clear">
</h1>
<hr>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#target_types">Target types</a></dt>
<dt><a href="#tools">Tools</a></dt>
<dt><a href="#main_target_rules">Main target rules</a></dt>
<dt><a href="#scanners">Scanners</a></dt>
</dl>
<hr>
<h2 id="introduction">Introduction</h2>
<p>This document explains how to extend Boost.Build to accomodate your
local requirements. Let's start with quite simple, but realistic
example.</p>
<p>Say you're writing an application which generates C++ code. If you
ever did this, you know that it's not nice. Embedding large portions of
C++ code in string literals is very awkward. A much better solution
is:</p>
<ol>
<li>Write the template of the code to be generated, leaving
placeholders at the points which will change</li>
<li>Access the template in your application and replace placeholders
with appropriate text.</li>
<li>Write the result.</li>
</ol>
<p>It's quite easy to archive. You write special verbatim files, which
are just C++, except that the very first line of the file gives a name of
variable that should be generated. A simple tool is created which takes
verbatim file and creates a cpp file with a single char* variable, which
name is taken from the first line of verbatim file, and which value is
properly quoted content of the verbatim file.</p>
<p>Let's see what Boost.Build can do.</p>
<p>First off, Boost.Build has no idea about "verbatim files". So, you
must register a new type. The following code does it:</p>
<pre>
import type ;
type.register VERBATIM : verbatim ;
</pre>
<p>The first parameter to 'type.register' gives the name of declared
type. By convention, it's uppercase. The second parameter is suffix for
this type. So, if Boost.Build sees "code.verbatim" in the list of
sources, it knows that it's of type <tt>VERBATIM</tt>.</p>
<p>Lastly, you need to tool to convert verbatim files to C++. Say you've
stetched such a tool in Python. Then, you have to inform Boost.Build
about the tool. The Boost.Build concept which represent tool is
<em>generator</em>.</p>
<p>First, you say that generator 'inline-file' is able to convert
VERBATIM type into C++:</p>
<pre>
import generators ;
generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
</pre>
<p>Second, you must specify the commands to be run to actually perform
convertion:</p>
<pre>
actions inline-file
{
./inline-file.py $(&lt;) $(&gt;)
}
</pre>
<!-- We use verbatim.inline-file in one place and just inline-file in
another. Is this confusing for user?
-->
<p>Now, we're ready to tie it all together. Put all the code above in
file "verbatim.jam", add "import verbatim ;" to "project-root.jam", and
it's possible to write the following in Jamfile:</p>
<pre>
exe codegen : codegen.cpp class_template.verbatim usage.verbatim ;
</pre>
The verbatim files will be automatically converted into C++ and linked
it.
<p>The complete code is available in <a href=
"../examples-v2/customization">examples-v2/customization</a>
directory.</p>
<h2 id="target_types">Target types</h2>
<h2 id="tools">Tools</h2>
<h2 id="main_target_rules">Main target rules</h2>
<h2 id="scanners">Scanners</h2>
<hr>
<p class="revision">Last modified: Jule 3, 2003</p>
<p>&copy; Copyright Vladimir Prus 2002-2003. Permission to copy, use,
modify, sell and distribute this document is granted provided this
copyright notice appears in all copies. This document is provided ``as
is'' without express or implied warranty, and with no claim as to its
suitability for any purpose.</p>
<!-- sf logo -->
</body>
</html>

View File

@@ -3,7 +3,7 @@
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1st March 2002), see www.w3.org">
"HTML Tidy for Linux/x86 (vers 1st April 2002), see www.w3.org">
<meta name="generator" content="Microsoft FrontPage 5.0">
<meta http-equiv="Content-Type" content=
"text/html; charset=windows-1252">
@@ -14,52 +14,66 @@
<body bgcolor="#FFFFFF" text="#000000">
<img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center"
width="277" height="86">
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=7586&amp;type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" align="right"/></a>
width="277" height="86"> <a href="http://sourceforge.net"><img src=
"http://sourceforge.net/sflogo.php?group_id=7586&amp;type=1" width="88"
height="31" border="0" alt="SourceForge.net Logo" align="right"></a>
<h1>Boost Build System V2 &mdash; supported tools</h1>
<h2>Compilers</h2>
<p>The following compilers pass Boost.Build tests:
<ul>
<li>gcc (various versions), on Linux, NT, and Cygwin.
<li>msvc (various version), on NT and Cygwin.
<li>borland, on NT and Cygwin.
<p>The following compilers pass Boost.Build tests:</p>
<ul>
<li>gcc (various versions), on Linux, NT, and Cygwin.</li>
<li>msvc (various version), on NT and Cygwin.</li>
<li>borland, on NT and Cygwin.</li>
</ul>
<h2>Libraries</h2>
<p>Some important libraries have special support in Boost.Build:
<p>Some important libraries have special support in Boost.Build:</p>
<ul>
<li>STLPort &mdash; on gcc.
<li>QT, including the <tt>moc</tt> and <tt>uic</tt> tools &mdash; on gcc.
<ul>
<li><a href="http://stlport.org">STLport</a> &mdash; on gcc and
msvc.</li>
<li><a href="http://www.trolltech.com/products/qt/index.html">QT</a>,
including the <tt>moc</tt> and <tt>uic</tt> tools &mdash; on gcc.</li>
</ul>
<h2>Other tools</h2>
<ul>
<li>Parser/lexer generators <tt>bison</tt> and <tt>lex</tt>.
<li>XSLT processor <tt>xsltproc</tt>.
<li>The Apache FOP tool.
<li>BoostBook documentation format.
<li>Parser/lexer generators <tt>bison</tt> and <tt>lex</tt>.</li>
<li>XSLT processor <a href=
"http://xmlsoft.org/XSLT/">xsltproc</a>.</li>
<li>The Apache <a href="http://xml.apache.org/fop/index.html">FOP</a>
tool.</li>
<li>BoostBook documentation format.</li>
<li>GNU <a href=
"http://www.gnu.org/software/gettext/gettext.html">gettext</a>
internationalization tools.</li>
</ul>
<hr>
<p>&copy; Copyright Vladimir Prus 2003. Permission to
copy, use, modify, sell and distribute this document is granted provided
this copyright notice appears in all copies. This document is provided
"as is" without express or implied warranty, and with no claim as to its
suitability for any purpose.</p>
<p>&copy; Copyright Vladimir Prus 2003. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability for
any purpose.</p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan
-->26 Apr, 2003
-->Jule 3, 2003
<!--webbot bot="Timestamp" endspan i-checksum="13972"
-->
-->
</p>
</body>
</html>