mirror of
https://github.com/boostorg/more.git
synced 2025-02-25 09:20:13 +08:00
Initial HTML commit
[SVN r7640]
This commit is contained in:
Beman Dawes
commit
9e9491d8d9
1166
count_bdy.htm
Normal file
1166
count_bdy.htm
Normal file
File diff suppressed because it is too large
Load Diff
118
faq.htm
Normal file
118
faq.htm
Normal file
@ -0,0 +1,118 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<title>FAQ</title>
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="Microsoft Theme" content="none, default">
|
||||
<meta name="Microsoft Border" content="none, default">
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<table border="1" bgcolor="#007F7F" cellpadding="2">
|
||||
<tr>
|
||||
<td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" WIDTH="277"
|
||||
HEIGHT="86"></td>
|
||||
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font></a></td>
|
||||
<td><a href="../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big></font></a></td>
|
||||
<td><a href="../people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font></a></td>
|
||||
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font></a></td>
|
||||
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h1>Frequently Asked Questions</h1>
|
||||
|
||||
<p><b>How is a library accepted for posting on the site?</b> An initial review by the
|
||||
library master filters out libraries which do not meet the absolute requirements (must be
|
||||
C++, ownership clear, reasonable format, etc.) The author is free to rework and
|
||||
resubmit libraries which do not pass initial muster. This is encouraged, particularly when
|
||||
reviewers like the idea behind a library but feel that details are lacking.</p>
|
||||
|
||||
<p><b>Is there any assurance libraries actually work as claimed?</b> No. The review
|
||||
process will hopefully eliminate the most seriously flawed libraries, but a well
|
||||
constructed library with hidden defects is likely to slip through. Encouraging ordinary
|
||||
users to report their experience with a library is intended to address such concerns. </p>
|
||||
|
||||
<p><b>How does someone submit a comment?</b> Send email to <a
|
||||
href="mailto:boost@egroups.com">boost@egroups.com</a>. </p>
|
||||
|
||||
<p><strong>How does someone submit a library?</strong> See <a href="lib_guide.htm">Library
|
||||
Guidelines</a></p>
|
||||
|
||||
<p><b>Are commercial libraries requiring a fee acceptable?</b> No. However, a library that
|
||||
a commercial enterprise makes available without fee is acceptable. If the description of
|
||||
the library makes a low-key plug for the supplier, that is acceptable as long as the
|
||||
library delivers real value and isn’t just a Trojan horse for the plug.</p>
|
||||
|
||||
<p><b>Are shareware libraries acceptable?</b> No. At least initially, only free libraries
|
||||
will be accepted.</p>
|
||||
|
||||
<p><strong>Are open source license libraries acceptable?</strong> No, not currently.
|
||||
Open source licenses often require redistribution or availability of source code,
|
||||
inclusion of license document with machine-executable redistribution, give the initial
|
||||
developer rights to licensee modifications, and need a lawyer to understand. These
|
||||
would be immediate disqualifications for many business, commercial, and consumer
|
||||
applications. Boost aims to avoid subjecting users to hard-to-comply-with license terms.<br>
|
||||
<br>
|
||||
This is subject to review for a particularly important piece of software, or as the
|
||||
industry changes.</p>
|
||||
|
||||
<p><b>Must full source code be provided?</b> Yes, these are source code libraries.</p>
|
||||
|
||||
<p><b>What about documentation?</b> A very simple library might be accepted with only a
|
||||
well commented header file. For more substantial libraries, some form of documentation is
|
||||
certainly going to be expected. HTML is the preferred form.</p>
|
||||
|
||||
<p><b>Are platform specific libraries acceptable?</b> There is a preference for portable
|
||||
libraries. Libraries will be accepted that have portable interfaces but require platform
|
||||
specific implementations, as long as the author supplies implementations for a couple of
|
||||
disparate major operating systems.</p>
|
||||
|
||||
<p><b>Must a library do useful work? </b>No. A library meant as a teaching example or
|
||||
demonstration might not actually do any work.</p>
|
||||
|
||||
<p><b>Who owns the libraries?</b> Presumably many authors will copyright their libraries.
|
||||
Others authors may wish to place their libraries in the public domain. The Boost.org
|
||||
policy is to only accept libraries with a clear copyright notice. It is up to
|
||||
potential users to decide if they find the copyright terms acceptable, and to not use
|
||||
libraries with unacceptable copyrights.</p>
|
||||
|
||||
<p><b>What support is available for the libraries?</b> Try the <a
|
||||
href="mailto:boost@egroups.com">boost@egroups.com</a> mailing list. </p>
|
||||
|
||||
<p><b>Is there a relationship between Boost.org and the C++ Standards Committee?</b>
|
||||
No. The people who started Boost.org were all on the committee, but that was just
|
||||
happenstance.</p>
|
||||
|
||||
<p><b>Will the Boost.org libraries become part of the next C++ Standard?</b> Some
|
||||
might, someday off in the future, but that is up to the standards committee. To the
|
||||
extent a library becomes "existing practice", the likelihood increases that
|
||||
someone will propose it for future standardization. Submitting a library to Boost.org is
|
||||
one way to establish existing practice - as long as enough people are interested to
|
||||
download and use it!</p>
|
||||
|
||||
<p><b>Is the site a commercial business?</b> No. It is just some people getting together
|
||||
as a kind of cyberspace civic association. If it ever needs to incorporate, it would be as
|
||||
non-profit organization.</p>
|
||||
|
||||
<p><b>Is there any charge for submitting libraries or reviews to Boost.org?</b> No. Unlike
|
||||
the standards committees, you don’t have to pay to volunteer!</p>
|
||||
|
||||
<p><b>Will the site include material beyond libraries?</b> The main focus is on libraries,
|
||||
but if people contribute occasional articles or other material to make the site more
|
||||
interesting, that could be a nice fit.</p>
|
||||
|
||||
<p><strong>How do I unzip the distribution files on my [whatever] computer?</strong>
|
||||
The .zip format is used for distribution because there are free decoders and
|
||||
encoders available for many, many different platforms. See the <a
|
||||
HREF="http://www.info-zip.org/pub/infozip/">Info-ZIP</a> web site, which includes a FAQ and
|
||||
much other useful information about the .zip format. Many commercial compressor-archiver
|
||||
utilities also support this format.</p>
|
||||
|
||||
<p>-- End of FAQ --</p>
|
||||
|
||||
<p>Revised May 17, 1999</p>
|
||||
</body>
|
||||
</html>
|
||||
103
feature_model_diagrams.htm
Normal file
103
feature_model_diagrams.htm
Normal file
@ -0,0 +1,103 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<title>Feature Model Diagrams</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<h1>Feature Model Diagrams in text and HTML</h1>
|
||||
<p>By <a href="../people/beman_dawes.html">Beman Dawes</a></p>
|
||||
<h2>Introduction</h2>
|
||||
<p>In their seminal book, Generative Programming, Czarnecki and Eisenecker (<a href="#Generative Programming">C&E</a>)
|
||||
describe how to build feature models [C&E 4.4] consisting of a feature
|
||||
diagram plus semantic, rationale, and other attributes. Feature models are
|
||||
then used to drive design cycles which eventually lead to manual or automatic
|
||||
assembly of configurations.</p>
|
||||
<p>Feature models provide a language to describe the library variability that is
|
||||
often such an issue in boost.org discussions. The Whorf hypothesis that
|
||||
"Language shapes the way we think, and determines what we can think
|
||||
about" seems to apply. In discussion of library variability issues,
|
||||
we have been crippled by lack of a good language. With feature models we now
|
||||
have a language to carry on the dialog.</p>
|
||||
<p>The graphical feature diagrams presented by C&E are not in a suitable
|
||||
form for the email discussions boost.org depends upon. The hierarchical nature
|
||||
of feature diagrams can be represented by a simple text-based feature diagram
|
||||
language. A feature model can also take advantage of the hyperlinks
|
||||
inherent in HTML.</p>
|
||||
<h2><a name="Grammar">Grammar</a></h2>
|
||||
<p>The grammar for the feature diagram language is expressed in Extended
|
||||
Bakus-Naur Form; ::= represents productions, [...] represents options, {...}
|
||||
represents zero or more instances, and represents | alternatives.</p>
|
||||
<blockquote>
|
||||
<pre>feature-model ::= concept-name details { feature }</pre>
|
||||
<pre>feature ::= feature-name [details]</pre>
|
||||
<pre>details ::= "(" feature-list ")" // required features
|
||||
| "[" feature-list "]" // optional features</pre>
|
||||
<pre>feature-list ::= element { "|" element } // one only
|
||||
| element { "+" element } // one or more
|
||||
| element { "," element } // all
|
||||
// [a+b] equivalent to [a,b]</pre>
|
||||
<pre>element ::= feature
|
||||
| details</pre>
|
||||
<pre>concept-name ::= name</pre>
|
||||
<pre>feature-name ::= name</pre>
|
||||
</blockquote>
|
||||
<p>The usual lexical conventions apply. Names are case-insensitive and consist
|
||||
of a leading letter, followed by letters, digits, underscores or hyphens, with
|
||||
no spaces allowed.</p>
|
||||
<p>At least one instance of each name should be hyperlinked to the corresponding
|
||||
<a href="#Feature Descriptions">Feature Description</a>.</p>
|
||||
<p>While the grammar is intended for written communication between people, it
|
||||
may also be trivially machine parsed for use by automatic tools.</p>
|
||||
<h2><a name="Feature Descriptions">Feature Description</a></h2>
|
||||
<p>Descriptive information is associated with each concept or feature. According
|
||||
to [C&E 4.4.2] this includes:</p>
|
||||
<ul>
|
||||
<li>Semantic descriptions.</li>
|
||||
<li>Rationale.</li>
|
||||
<li>Stakeholders and client programs.</li>
|
||||
<li>Exemplar systems.</li>
|
||||
<li>Constraints and default dependency rules.</li>
|
||||
<li>Availability sites, binding sites, and binding mode.</li>
|
||||
<li>Open/Closed attribute.</li>
|
||||
</ul>
|
||||
<h2>What is a Feature?</h2>
|
||||
<p>A feature [C&E 4.9.1] is "anything users or client programs might
|
||||
want to control about a concept. Thus, during feature modeling, we
|
||||
document no only functional features ... but also implementation features, ...,
|
||||
various optimizations, alternative implementation techniques, and so on."</p>
|
||||
<h2>Example</h2>
|
||||
<blockquote>
|
||||
<pre>special-container ( organization,
|
||||
performance,
|
||||
interface ) // all required</pre>
|
||||
<pre>organization [ ordered + indexed ] // zero or more (4 configurations)</pre>
|
||||
<pre>indexed [ hash-function ] // zero or one (2 configurations)</pre>
|
||||
<pre>performance ( fast | small | balanced ) // exactly one (3 configurations)</pre>
|
||||
<pre>interface ( STL-style + cursor-style ) // one or more (3 configurations)</pre>
|
||||
</blockquote>
|
||||
<p>There should be feature descriptions for <code>some-container, organization,
|
||||
ordered, indexed, hash-function, performance, fast, small, balanced, interface,
|
||||
STL-style, and cursor-style</code>.</p>
|
||||
<p>The number of possible configurations is (2 + 2*2) * 3 * 3 = 54,
|
||||
assuming no constraints.</p>
|
||||
<p>There are equivalent representations. For example:</p>
|
||||
<blockquote>
|
||||
<pre>special-container ( organization[ ordered+indexed[ hash-function ]],
|
||||
performance( fast|small|balanced ),
|
||||
interface( STL-style+cursor-style ) )</pre>
|
||||
</blockquote>
|
||||
<h2>References</h2>
|
||||
<p>Krzysztof Czarnecki and Ulrich W. Eisenecker, <a name="Generative Programming" href="http://www.generative-programming.org">Generative
|
||||
Programming</a>, Addison-Wesley, 2000, ISBN 0-210-30977-7</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->23 July 2000<!--webbot bot="Timestamp" endspan i-checksum="18762" --></p>
|
||||
<p>© Copyright Beman Dawes, 2000</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
94
formal_review_process.htm
Normal file
94
formal_review_process.htm
Normal file
@ -0,0 +1,94 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<title>Formal Review Process</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<table border="1" bgcolor="#007F7F" cellpadding="2">
|
||||
<tr>
|
||||
<td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
|
||||
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
|
||||
<td><a href="../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
|
||||
<td><a href="../people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
|
||||
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
|
||||
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<h1>Formal Review Process</h1>
|
||||
<p>The Formal Review process determines if a proposed library should be accepted
|
||||
as a Boost library.</p>
|
||||
<p>The final "accept" or "reject" decision is made by the
|
||||
Review Manager, based on review comments received from boost mailing list
|
||||
members.</p>
|
||||
<p>Members only can see <a href="http://www.egroups.com/files/boost/Members+Only/formal_review_schedule.htm">Formal
|
||||
Review Schedule</a> for the current review schedule. </p>
|
||||
<h2>Comments</h2>
|
||||
<p>All Boost mailing list members are encouraged to submit Formal Review
|
||||
comments:</p>
|
||||
<blockquote>
|
||||
<ul>
|
||||
<li>Publicly on the mailing list.</li>
|
||||
<li>Privately to the Review Manager. (See Formal Review Status page )</li>
|
||||
<li>Privately to the library submitter.</li>
|
||||
</ul>
|
||||
</blockquote>
|
||||
<p>Private comments to a library submitter may be helpful to her or him, but
|
||||
won't help the Review Manager reach a decision, so the other forms are
|
||||
preferred.</p>
|
||||
<h2>Preparing review comments</h2>
|
||||
<p>Comments may be brief or lengthy, but basically the Review Manager needs your
|
||||
answers to several questions. If you identify problems along the way,
|
||||
please note if they are minor, serious, or showstoppers.</p>
|
||||
<ul>
|
||||
<li>What is your evaluation of the design?<br>
|
||||
</li>
|
||||
<li>What is your evaluation of the implementation?<br>
|
||||
</li>
|
||||
<li>What is your evaluation of the documentation?<br>
|
||||
</li>
|
||||
<li>What is your evaluation of the potential usefulness of the library?<br>
|
||||
</li>
|
||||
<li>Did you try to use the library? With what compiler? Did you
|
||||
have any problems?<br>
|
||||
</li>
|
||||
<li>How much effort did you put into your evaluation? A glance? A quick
|
||||
reading? In-depth study?<br>
|
||||
</li>
|
||||
<li>Are you knowledgeable about the problem domain?<br>
|
||||
</li>
|
||||
<li>Finally, do you think the library should be accepted as a Boost
|
||||
library? Be sure to say this explicitly so that your other comments
|
||||
don't obscure your overall opinion.</li>
|
||||
</ul>
|
||||
<h2>Results</h2>
|
||||
<p>At the conclusion of the comment period, the Review Manager will post a
|
||||
message to the mailing list saying if the library has been accepted or
|
||||
rejected. A rationale should be provided, but its extent is up to the
|
||||
Review Manager.</p>
|
||||
<h2>Notes for Review Managers</h2>
|
||||
<p>Consider writing a Review page for posting on the web site.</p>
|
||||
<p>In Review pages or mailing list postings, do quote review comments if you
|
||||
wish, but don't identify authors of private comments.</p>
|
||||
<h2>Notes for Library Authors</h2>
|
||||
<p>A proposed library should remain stable during the review period; it is just
|
||||
going to confuse and irritate reviewers if there are numerous changes. It
|
||||
is, however, useful to upload fixes for serious bugs right away, particularly
|
||||
those which prevent reviewers from fully evaluating the library. Post a
|
||||
notice of such fixes on the mailing list.</p>
|
||||
<p>Library improvements suggested by reviewers should be held until after the
|
||||
completion of review period. Such changes can then be incorporated in the <a href="submission_process.htm#Final">final
|
||||
submission file</a> sent to the webmaster for posting. If the suggested
|
||||
changes might affect reviewer's judgments, post a notice of the pending
|
||||
change on the mailing list.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->13 June, 2000<!--webbot bot="Timestamp" endspan i-checksum="19835" --></p>
|
||||
<p> </p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
102
header.htm
Normal file
102
header.htm
Normal file
@ -0,0 +1,102 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<title>Header policy</title>
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<meta name="Microsoft Border" content="none, default">
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<table border="1" bgcolor="#007F7F" cellpadding="2">
|
||||
<tr>
|
||||
<td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
|
||||
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
|
||||
<td><a href="../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
|
||||
<td><a href="../people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
|
||||
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
|
||||
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<h1>Header Policy</h1>
|
||||
<p>Header files are the place where a library comes into contact with user code
|
||||
and other libraries. To co-exist peacefully and productively, headers must
|
||||
be "good neighbors".</p>
|
||||
<p>Here are the standards for namespace boost headers. Many of
|
||||
these are also reasonable guidelines for general use.
|
||||
<ul>
|
||||
<li>Headers should have a .hpp (lowercase) filename extension. </li>
|
||||
<li>Identify the file with an initial comment line. The sample header
|
||||
identifies both the name of the header and the library it is a part of.</li>
|
||||
<li>Specify copyright ownership and any restrictions on use. If you
|
||||
don't want to retain ownership, say something like "Written by Jane
|
||||
Programmer and placed in the public domain".</li>
|
||||
<li>Supply version information, possibly generated automatically by your
|
||||
version control system.</li>
|
||||
<li>Macro names should be all uppercase, and begin with the namespace
|
||||
name. Underscores separate words.</li>
|
||||
<li>Wrap the header in #ifndef guards so that multiple inclusion is
|
||||
benign. Use a naming convention that minimizes the chance of clashes
|
||||
with macro names from other's code. The <a href="#Sample header">sample
|
||||
header</a> uses the Boost convention of all uppercase letters, with the
|
||||
header name prefixed by the namespace name, and suffixed with HPP, separated
|
||||
by underscores.</li>
|
||||
<li>Wrap the header contents in a namespace to prevent global namespace
|
||||
pollution. The namespace approach to pollution control is strongly preferred
|
||||
to older approaches such as adding funny prefixes to global names.
|
||||
Libraries which are designed to work well with other Boost libraries should
|
||||
be placed namespace <tt>boost</tt>.</li>
|
||||
<li>Place the header file in a sub-directory to prevent conflict with
|
||||
identically named header files in other libraries. The parent
|
||||
directory is added to the compiler's include search path. Then both
|
||||
your code and user code specifies the sub-directory in <tt>#include</tt>
|
||||
directives. Thus the header <a href="#Sample header">sample header</a>
|
||||
would be included by <tt>#include <boost/furball.hpp></tt></li>
|
||||
<li>The preferred ordering for class definitions is public members, protected
|
||||
members, and finally private members.</li>
|
||||
<li>Include the boost/config.hpp <a href="../libs/config/index.htm">configuration
|
||||
header</a> if there is a need to deal with compiler or platform
|
||||
configuration issues.</li>
|
||||
</ul>
|
||||
<h2><a name="Sample header"></a>Sample Header</h2>
|
||||
<pre><tt>// Boost general library furball.hpp header file ---------------------------//
|
||||
|
||||
// (C) Copyright Your Name 1998. Permission to copy, use, modify, sell and
|
||||
// distribute this software is granted provided this copyright notice appears
|
||||
// in all copies. This software is provided "as is" without express or implied
|
||||
// warranty, and with no claim as to its suitability for any purpose.
|
||||
|
||||
// $Id$ or other version information
|
||||
|
||||
#ifndef BOOST_FURBALL_HPP
|
||||
#define BOOST_FURBALL_HPP
|
||||
|
||||
namespace boost {
|
||||
|
||||
// Furball class declaration -----------------------------------------------//
|
||||
|
||||
class furball
|
||||
{
|
||||
public:
|
||||
void throw_up();
|
||||
private:
|
||||
int whatever;
|
||||
}; // furball
|
||||
|
||||
} // namespace
|
||||
|
||||
#endif // BOOST_FURBALL_HPP</tt></pre>
|
||||
<h2>Coding Style</h2>
|
||||
<p>The alert reader will have noticed that the <a href="#Sample header">sample
|
||||
header</a> employs a certain coding style for indentation, positioning braces,
|
||||
commenting ending braces, and similar formatting issues. These stylistic
|
||||
issues are viewed as personal preferences and are not part of the Boost Header
|
||||
Policy.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->23 June, 2000<!--webbot bot="Timestamp" endspan i-checksum="19836" --></p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
201
imp_vars.htm
Normal file
201
imp_vars.htm
Normal file
@ -0,0 +1,201 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<title>Implementation Variations</title>
|
||||
</head>
|
||||
|
||||
<body link="#0000ff" vlink="#800080" bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<table border="1" bgcolor="#007F7F" cellpadding="2">
|
||||
<tr>
|
||||
<td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
|
||||
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
|
||||
<td><a href="../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
|
||||
<td><a href="../people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
|
||||
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
|
||||
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<h1>Implementation Variations</h1>
|
||||
<h2>Separation of interface and implementation</h2>
|
||||
<p>The interface specifications for boost.org library components (as well as for
|
||||
quality software in general) are conceptually separate from implementations of
|
||||
those interfaces. This may not be obvious, particularly when a component is
|
||||
implemented entirely within a header, but this separation of interface and
|
||||
implementation is always assumed. From the perspective of those concerned with
|
||||
software design, portability, and standardization, the interface is what is
|
||||
important, while the implementation is just a detail.</p>
|
||||
<p>Dietmar Kühl, one of the original boost.org contributors, comments "The
|
||||
main contribution is the interface, which is augmented with an implementation,
|
||||
proving that it is possible to implement the corresponding class and providing a
|
||||
free implementation."</p>
|
||||
<b>
|
||||
<h2>Implementation variations</h2>
|
||||
</b>
|
||||
<p>There may be a need for multiple implementations of an interface, to
|
||||
accommodate either platform dependencies or performance tradeoffs. Examples of
|
||||
platform dependencies include compiler shortcomings, file systems, thread
|
||||
mechanisms, and graphical user interfaces. The classic example of a performance
|
||||
tradeoff is a fast implementation which uses a lot of memory versus a slower
|
||||
implementation which uses less memory.</p>
|
||||
<p>Boost libraries generally use a <a href="../libs/config/index.htm">configuration
|
||||
header</a>, boost/config.hpp, to capture compiler and platform
|
||||
dependencies. Although the use of boost/config.hpp is not required, it is
|
||||
the preferred approach for simple configuration problems. </p>
|
||||
<h2>Boost policy</h2>
|
||||
<p>The Boost policy is to avoid platform dependent variations in interface
|
||||
specifications, but supply implementations which are usable over a wide range of
|
||||
platforms and applications. That means boost libraries will use the
|
||||
techniques below described as appropriate for dealing with platform
|
||||
dependencies.</p>
|
||||
<p>The Boost policy toward implementation variations designed to enhance
|
||||
performance is to avoid them unless the benefits greatly exceed the full
|
||||
costs. The term "full costs" is intended to include both
|
||||
tangible costs like extra maintenance, and intangible cost like increased
|
||||
difficulty in user understanding.</p>
|
||||
<b>
|
||||
<h2>Techniques for providing implementation variations</h2>
|
||||
</b>
|
||||
<p>Several techniques may be used to provide implementation variations. Each is
|
||||
appropriate in some situations, and not appropriate in other situations.</p>
|
||||
<h3>Single general purpose implementation</h3>
|
||||
<p>The first technique is to simply not provide implementation variation at
|
||||
all. Instead, provide a single general purpose implementation, and forgo
|
||||
the increased complexity implied by all other techniques.</p>
|
||||
<p><b>Appropriate:</b> When it is possible to write a single portable
|
||||
implementation which has reasonable performance across a wide range of
|
||||
platforms. Particularly appropriate when alternative implementations differ only
|
||||
in esoteric ways.</p>
|
||||
<p><b>Not appropriate:</b> When implementation requires platform specific
|
||||
features, or when there are multiple implementation possible with widely
|
||||
differing performance characteristics.</p>
|
||||
<p>Beman Dawes comments "In design discussions some implementation is often
|
||||
alleged to be much faster than another, yet a timing test discovers no
|
||||
significant difference. The lesson is that while algorithmic differences may
|
||||
affect speed dramatically, coding differences such as changing a class from
|
||||
virtual to non-virtual members or removing a level of indirection are unlikely
|
||||
to make any measurable difference unless deep in an inner loop. And even in an
|
||||
inner loop, modern CPU’s often execute such competing code sequences in the
|
||||
same number of clock cycles! A single general purpose implementation is
|
||||
often just fine."</p>
|
||||
<p>Or as Donald Knuth said, "Premature optimization is the root of all
|
||||
evil." (Computing Surveys, vol 6, #4, p 268).</p>
|
||||
<h3>Macros</h3>
|
||||
<p>While the evils of macros are well known, there remain a few cases where
|
||||
macros are the preferred solution:</p>
|
||||
<blockquote>
|
||||
<ul>
|
||||
<li> Preventing multiple inclusion of headers via #include guards.</li>
|
||||
<li> Passing minor configuration information from a configuration
|
||||
header to other files.</li>
|
||||
</ul>
|
||||
</blockquote>
|
||||
<p><b>Appropriate:</b> For small compile-time variations which would
|
||||
otherwise be costly or confusing to install, use, or maintain. More appropriate
|
||||
to communicate within and between library components than to communicate with
|
||||
library users.</p>
|
||||
<p><b>Not appropriate: </b> If other techniques will do.</p>
|
||||
<p>To minimize the negative aspects of macros:</p>
|
||||
<blockquote>
|
||||
<ul>
|
||||
<li>Only use macros when they are clearly superior to other
|
||||
techniques. They should be viewed as a last resort.</li>
|
||||
<li>Names should be all uppercase, and begin with the namespace name. This
|
||||
will minimize the chance of name collisions. For example, the #include
|
||||
guard for a boost header called foobar.h might be named BOOST_FOOBAR_H.</li>
|
||||
</ul>
|
||||
</blockquote>
|
||||
<h3>Separate files</h3>
|
||||
<p>A library component can have multiple variations, each contained in its own
|
||||
separate file or files. The files for the most appropriate variation are
|
||||
copied to the appropriate include or implementation directories at installation
|
||||
time.</p>
|
||||
<p>The way to provide this approach in boost libraries is to include specialized
|
||||
implementations as separate files in separate sub-directories in the .ZIP
|
||||
distribution file. For example, the structure within the .ZIP distribution file
|
||||
for a library named foobar which has both default and specialized variations
|
||||
might look something like:</p>
|
||||
<blockquote>
|
||||
<pre>foobar.h // The default header file
|
||||
foobar.cpp // The default implementation file
|
||||
readme.txt // Readme explains when to use which files
|
||||
self_contained/foobar.h // A variation with everything in the header
|
||||
linux/foobar.cpp // Implementation file to replace the default
|
||||
win32/foobar.h // Header file to replace the default
|
||||
win32/foobar.cpp // Implementation file to replace the default</pre>
|
||||
</blockquote>
|
||||
<p><b>Appropriate:</b> When different platforms require different
|
||||
implementations, or when there are major performance differences between
|
||||
possible implementations. </p>
|
||||
<p><b>Not appropriate:</b> When it makes sense to use more that one of the
|
||||
variations in the same installation.</p>
|
||||
<h3>Separate components</h3>
|
||||
<p>Rather than have several implementation variations of a single component,
|
||||
supply several separate components. For example, the Boost library currently
|
||||
supplies <code>scoped_ptr</code> and <code>shared_ptr</code> classes rather than
|
||||
a single <code>smart_ptr</code> class parameterized to distinguish between the
|
||||
two cases. There are several ways to make the component choice:</p>
|
||||
<blockquote>
|
||||
<ul>
|
||||
<li>Hardwired by the programmer during coding.</li>
|
||||
<li>Chosen by programmer written runtime logic (trading off some extra
|
||||
space, time, and program complexity for the ability to select the
|
||||
implementation at run-time.)</li>
|
||||
</ul>
|
||||
</blockquote>
|
||||
<p><b>Appropriate: </b>When the interfaces for the variations diverge, and when
|
||||
it is reasonably to use more than one of the variations. When run-time selection
|
||||
of implementation is called for.</p>
|
||||
<p><b>Not appropriate:</b> When the variations are data type, traits, or
|
||||
specialization variations which can be better handled by making the component a
|
||||
template. Also not appropriate when choice of variation is best done by some
|
||||
setup or installation mechanism outside of the program itself. Thus
|
||||
usually not appropriate to cope with platform differences.</p>
|
||||
<p><b>Note:</b> There is a related technique where the interface is specified as
|
||||
an abstract (pure virtual) base class (or an interface definition language), and
|
||||
the implementation choice is passed off to some third-party, such as a
|
||||
dynamic-link library or object-request broker. While that is a powerful
|
||||
technique, it is way beyond the scope of this discussion.</p>
|
||||
<h3>Template-based approaches</h3>
|
||||
<p>Turning a class or function into a template is often an elegant way to cope
|
||||
with variations. Template-based approaches provide optimal space and time
|
||||
efficiency in return for constraining the implementation selection to compile
|
||||
time. </p>
|
||||
<p>Important template techniques include:</p>
|
||||
<blockquote>
|
||||
<ul>
|
||||
<li>Data type parameterization. This allows a single component to
|
||||
operate on a variety of data types, and is why templates were originally
|
||||
invented.</li>
|
||||
<li>Traits parameterization. If parameterization is complex, bundling
|
||||
up aspects into a single traits helper class can allow great variation
|
||||
while hiding messy details. The C++ Standard Library provides
|
||||
several examples of this idiom, such as <code>iterator_traits<></code>
|
||||
(24.3.1 lib.iterator.traits) and <tt>char_traits<></tt> (21.2
|
||||
lib.char.traits).</li>
|
||||
<li>Specialization. A template parameter can be used purely for the
|
||||
purpose of selecting a specialization. For example:</li>
|
||||
</ul>
|
||||
<blockquote>
|
||||
<blockquote>
|
||||
<pre>SomeClass<fast> my_fast_object; // fast and small are empty classes
|
||||
SomeClass<small> my_small_object; // used just to select specialization</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
<p><b>Appropriate: </b>When the need for variation is due to data type or
|
||||
traits, or is performance related like selecting among several algorithms, and
|
||||
when a program might reasonably use more than one of the variations.</p>
|
||||
<p><b>Not appropriate:</b> When the interfaces for variations are
|
||||
different, or when choice of variation is best done by some mechanism outside of
|
||||
the program itself. Thus usually not appropriate to cope with platform
|
||||
differences.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->23 June, 2000<!--webbot bot="Timestamp" endspan i-checksum="19836" --></p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
62
index.htm
Normal file
62
index.htm
Normal file
@ -0,0 +1,62 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<title>More Information</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<table border="1" bgcolor="#007F7F" cellpadding="2">
|
||||
<tr>
|
||||
<td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
|
||||
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
|
||||
<td><a href="../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
|
||||
<td><a href="../people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
|
||||
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
|
||||
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<h1>More Information</h1>
|
||||
<h2>Boost Policies</h2>
|
||||
<p>These policies explain what is expected of boost libraries and the process
|
||||
for library submissions.</p>
|
||||
<blockquote>
|
||||
<p><b><a href="lib_guide.htm">Library Requirements and Guidelines</a></b>.
|
||||
Basic standards for those preparing a submission.</p>
|
||||
<p><a href="submission_process.htm"><b>Library Submission Process</b></a>.
|
||||
How to submit a library to Boost.</p>
|
||||
<p><b><a href="formal_review_process.htm">Library Formal Review Process</a></b>.
|
||||
Including how to submit a review comment.</p>
|
||||
<p><b><a href="header.htm">Header Policy</a></b>. Headers are where a
|
||||
library contacts its users, so programming practices are particularly
|
||||
important.</p>
|
||||
<p><b><a href="imp_vars.htm">Implementation Variations</a></b>.
|
||||
Sometimes one size fits all, sometimes it doesn't. This page deals with
|
||||
the trade-offs.</p>
|
||||
</blockquote>
|
||||
<h2>Links</h2>
|
||||
<blockquote>
|
||||
<p>The C++ Standard (ISO/IEC 14882) is available online as a PDF file from the
|
||||
<a href="http://www.ansi.org">ANSI</a> (American National Standards Institute)
|
||||
Electronic Standards Store. The price is $US 18.00. The document is
|
||||
certainly not a tutorial, but is interesting to those who care about the
|
||||
precise specification of the language and the standard library.</p>
|
||||
</blockquote>
|
||||
<h2>Articles and Papers</h2>
|
||||
<blockquote>
|
||||
<p><b><a href="count_bdy.htm">Counted Body Techniques</a></b> by <a href="../people/kevlin_henney.htm">Kevlin
|
||||
Henney</a> is must reading for those interested in reference counting, a
|
||||
widely used object management idiom. Originally published in <a href="http://www.accu.org/c++sig/public/Overload.html">Overload</a>
|
||||
magazine.</p>
|
||||
<p><b><a href="feature_model_diagrams.htm">Feature Model Diagrams in text and
|
||||
HTML</a></b> describes how to represent feature model diagrams in text form.</p>
|
||||
</blockquote>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->16 July, 2000<!--webbot bot="Timestamp" endspan i-checksum="21057" --></p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
268
lib_guide.htm
Normal file
268
lib_guide.htm
Normal file
@ -0,0 +1,268 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<title>Library Requirements and Guidelines</title>
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<meta name="Microsoft Border" content="none, default">
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<table border="1" bgcolor="#007F7F" cellpadding="2">
|
||||
<tr>
|
||||
<td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
|
||||
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
|
||||
<td><a href="../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
|
||||
<td><a href="../people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
|
||||
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
|
||||
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<h1 align="left">Boost Library Requirements and Guidelines</h1>
|
||||
<p align="left">This page describes requirements and guidelines for the content
|
||||
of a library submitted to Boost.</p>
|
||||
<p align="left">See the <a href="submission_process.htm">Boost Library
|
||||
Submission Process</a> page for a description of the process involved.</p>
|
||||
<h2 align="left">Requirements</h2>
|
||||
<p>To avoid the frustration and wasted time of a proposed library being
|
||||
rejected, it must meets these requirements:</p>
|
||||
<ul>
|
||||
<li>The license must meet the <a href="#License">license requirements</a>
|
||||
below. Restricted licenses like the GPL and LGPL are not acceptable. The
|
||||
copyright <a href="#Ownership">ownership</a> must be clear.<br>
|
||||
</li>
|
||||
<li>The library must be generally useful and not restricted to a narrow
|
||||
problem domain.<br>
|
||||
</li>
|
||||
<li>The library must meet the <a href="#Portability">portability requirements</a>
|
||||
below. <br>
|
||||
</li>
|
||||
<li>The library must come reasonably close to meeting the <a href="#Guidelines">Guidelines</a>
|
||||
below.<br>
|
||||
</li>
|
||||
<li>The author must be willing to participate in discussions on the mailing
|
||||
list, and to refine the library accordingly.</li>
|
||||
</ul>
|
||||
<p>There's no requirement that an author read the mailing list for a time before
|
||||
making a submission. It has been noted, however, that submissions which begin
|
||||
"I just started to read this mailing list ..." seem to fail, often
|
||||
embarrassingly.</p>
|
||||
<h3 align="left"><a name="License">License</a> requirements</h3>
|
||||
<ul>
|
||||
<li>Must be simple to read and understand.<br>
|
||||
</li>
|
||||
<li>Must grant permission to copy, use and modify the software for any use
|
||||
(commercial and non-commercial) for no fee.<br>
|
||||
</li>
|
||||
<li>Must require that the license appear on all copies of the software source
|
||||
code.<br>
|
||||
</li>
|
||||
<li>Must not require that the license appear with executables or other binary
|
||||
uses of the library. Must not require that the source code be
|
||||
available for execution or other binary uses of the library.<br>
|
||||
</li>
|
||||
<li>May restrict the use of the name and description of the library to the
|
||||
standard version found on the Boost web site.</li>
|
||||
</ul>
|
||||
<h3 align="left"><a name="Portability">Portability</a> requirements</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<p align="left">A library's interface must portable and not restricted to a
|
||||
particular compiler or operating system.<br>
|
||||
</li>
|
||||
<li>
|
||||
<p align="left">A library's implementation must if possible be portable and
|
||||
not restricted to a particular compiler or operating system. If a
|
||||
portable implementation is not possible, non-portable constructions are
|
||||
acceptable if reasonably easy to port to other environments.<br>
|
||||
</li>
|
||||
<li>
|
||||
<p align="left">There is no requirement that a library run on all C++
|
||||
compilers. <br>
|
||||
</li>
|
||||
<li>
|
||||
<p align="left">There is no requirement that a library run on any particular
|
||||
C++ compiler. Boost contributors often try to ensure their libraries
|
||||
work with popular compilers. The boost/config.hpp <a href="../libs/config/index.htm">configuration
|
||||
header</a> is the preferred mechanism for working around compiler
|
||||
deficiencies.</li>
|
||||
</ul>
|
||||
<p align="left">Since there is no absolute way to prove portability, many boost
|
||||
submissions demonstrate practical portability by compiling and executing
|
||||
correctly with two different C++ compilers, often under different operating
|
||||
systems. Otherwise reviewers may disbelieve that porting is in fact
|
||||
practical.</p>
|
||||
<h3 align="left"><a name="Ownership">Ownership</a></h3>
|
||||
<p align="left">Are you sure you own the library you are thinking of
|
||||
submitting? "How to Copyright Software" by MJ Salone, Nolo
|
||||
Press, 1990 says:</p>
|
||||
<blockquote>
|
||||
<p align="left">Doing work on your own time that is very similar to
|
||||
programming you do for your employer on company time can raise nasty legal
|
||||
problems. In this situation, it's best to get a written release from
|
||||
your employer in advance.</p>
|
||||
</blockquote>
|
||||
<p align="left">Place a copyright notice in all the important files you submit.
|
||||
Boost.org won't accept libraries without clear copyright information.</p>
|
||||
<h2 align="left"><a name="Guidelines">Guidelines</a></h2>
|
||||
<p align="left">Please use these guidelines as a checklist for preparing the
|
||||
content a library submission. Not every guideline applies to every
|
||||
library, but a reasonable effort to comply is expected.</p>
|
||||
<h3>Design and Programming</h3>
|
||||
<ul>
|
||||
<li>Aim for ISO Standard C++. Than means making effective use of the standard
|
||||
features of the language, and avoiding non-standard compiler extensions. It
|
||||
also means using the C++ Standard Library where applicable.</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>Headers should be good neighbors. See the <a href="header.htm">header
|
||||
policy</a>.</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>Follow the <a href="imp_vars.htm">implementation variation policy</a>. </li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>Follow quality programming practices. See, for example, "Effective
|
||||
C++" 2nd Edition, and "More Effective C++", both by Scott
|
||||
Meyers, published by Addison Wesley.</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>Use the lowercase/underscore <a href="#Naming">naming conventions</a> of
|
||||
the C++ standard library. Template parameter names begin with an
|
||||
uppercase letter. Macro (gasp!) names should be all uppercase and begin with
|
||||
BOOST_.</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>Use exceptions to report errors where appropriate, and write code that is
|
||||
safe in the face of exceptions.</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>Avoid exception-specifications. See <a href="#Exception-specification">exception-specification
|
||||
rationale</a>.</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>Provide sample programs, confidence tests, or regression tests so
|
||||
potential users can see how to use your library and verify that it has
|
||||
compiled correctly.</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>Although some boost members use proportional fonts, tabs, and unrestricted
|
||||
line lengths in their own code, boost's widely distributed source code
|
||||
should follow more conservative guidelines:
|
||||
<ul>
|
||||
<li>Use fixed-width fonts. See <a href="#code fonts">fonts rationale</a>.</li>
|
||||
<li>Use spaces rather than tabs.</li>
|
||||
<li>Limit line lengths to 80 characters.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<h3>Documentation</h3>
|
||||
<p>Even the simplest library needs some documentation; the amount should be
|
||||
proportional to the need. The documentation should assume the readers have
|
||||
a basic knowledge of C++, but are not necessarily experts.</p>
|
||||
<p>The format for documentation should be HTML, and should not require an
|
||||
advanced browser or server-side extensions.</p>
|
||||
<p>There is no single right way to do documentation. HTML documentation is often
|
||||
organized quite differently from traditional printed documents. Task-oriented
|
||||
styles differ from reference oriented styles. In the end, it comes down to the
|
||||
question: Is the documentation sufficient for the mythical "average"
|
||||
C++ programmer to use the library successfully?</p>
|
||||
<p>Appropriate topics for documentation often include:
|
||||
<ul>
|
||||
<li>General introduction to the library.</li>
|
||||
<li>Description of each class.</li>
|
||||
<li>Relationship between classes.</li>
|
||||
<li>For each function, as applicable, description, requirements
|
||||
(preconditions), effects, post-conditions, returns, and throws.</li>
|
||||
<li>Discussion of error detection and recovery strategy.</li>
|
||||
<li>How to use including description of typical uses.</li>
|
||||
<li>How to compile and link.</li>
|
||||
<li>How to test.</li>
|
||||
<li>Version or revision history.</li>
|
||||
<li>Rationale for design decisions. See <a href="#Rationale">Rationale
|
||||
rationale</a>.</li>
|
||||
<li>Acknowledgements. See <a href="#Acknowledgements">Acknowledgments
|
||||
rationale.</a></li>
|
||||
</ul>
|
||||
<h2>Rationale</h2>
|
||||
<p>Rationale for some of the requirements and guidelines follows.</p>
|
||||
<h3><a name="Exception-specification">Exception-specification</a> rationale</h3>
|
||||
<p>Exception specifications [ISO 15.4] are sometimes coded to indicate what
|
||||
exceptions may be thrown, or because the programmer hopes they will improved
|
||||
performance. But consider the follow member from a smart pointer:</p>
|
||||
<pre> T& operator*() const throw() { return *ptr; }</pre>
|
||||
<p>This function calls no other functions; it only manipulates fundamental data
|
||||
types like pointers Therefore, no runtime behavior of the
|
||||
exception-specification can ever be invoked. The function is completely
|
||||
exposed to the compiler; indeed it is declared inline Therefore, a smart
|
||||
compiler can easily deduce that the functions are incapable of throwing
|
||||
exceptions, and make the same optimizations it would have made based on the
|
||||
empty exception-specification. A "dumb" compiler, however, may make
|
||||
all kinds of pessimizations.</p>
|
||||
<p>For example, some compilers turn off inlining if there is an
|
||||
exception-specification. Some compilers add try/catch blocks. Such
|
||||
pessimizations can be a performance disaster which makes the code unusable in
|
||||
practical applications.</p>
|
||||
<p>Although initially appealing, an exception-specification tends to have
|
||||
consequences that require <b>very</b> careful thought to understand. The biggest
|
||||
problem with exception-specifications is that programmers use them as though
|
||||
they have the effect the programmer would like, instead of the effect they
|
||||
actually have.</p>
|
||||
<p>A non-inline function is the one place a "throws nothing"
|
||||
exception-specification may have some benefit with some compilers.</p>
|
||||
<hr>
|
||||
<h3><a name="Naming">Naming</a> conventions rationale</h3>
|
||||
<p>The C++ standard committee's Library Working Group discussed this issue in
|
||||
detail, and over a long period of time. The discussion was repeated again in
|
||||
early boost postings. A short summary:</p>
|
||||
<ul>
|
||||
<li>Naming conventions are contentious, and although several are widely used,
|
||||
no one style predominates.<br>
|
||||
</li>
|
||||
<li>Given the intent to propose portions of boost for the next revision of the
|
||||
C++ standard library, boost decided to follow the standard library's
|
||||
conventions.<br>
|
||||
</li>
|
||||
<li>Once a library settles on a particular convention, a vast majority of
|
||||
stakeholders want that style to be consistently used.<br>
|
||||
</li>
|
||||
<li>There is a strong preference for clear and descriptive names, even if
|
||||
lengthy.</li>
|
||||
</ul>
|
||||
<hr>
|
||||
<h3>Source <a name="code fonts">code fonts</a> rationale</h3>
|
||||
<p>Dave Abrahams comments: An important purpose (I daresay the primary purpose)
|
||||
of source code is communication: the documentation of intent. This is a doubly
|
||||
important goal for boost, I think. Using a fixed-width font allows us to
|
||||
communicate with more people, in more ways (diagrams are possible) right there
|
||||
in the source. Code written for fixed-width fonts using spaces will read
|
||||
reasonably well when viewed with a variable-width font, and as far as I can tell
|
||||
every editor supporting variable-width fonts also supports fixed width. I don't
|
||||
think the converse is true.</p>
|
||||
<hr>
|
||||
<h3><a name="Rationale">Rationale</a> rationale</h3>
|
||||
<p>Rationale is defined as "The fundamental reasons for something;
|
||||
basis." by the American Heritage Dictionary.</p>
|
||||
<p>Beman Dawes comments: Failure to supply contemporaneous rationale for
|
||||
design decisions is a major defect in many software projects. Lack of accurate
|
||||
rationale causes issues to revisited endlessly, causes maintenance bugs when a
|
||||
maintainer changes something without realizing it was done a certain way for
|
||||
some purpose, and shortens the useful lifetime of software.</p>
|
||||
<p>Rationale is fairly easy to provide at the time decisions are made, but very
|
||||
hard to accurately recover even a short time later.</p>
|
||||
<hr>
|
||||
<h3><a name="Acknowledgements">Acknowledgements</a> rationale</h3>
|
||||
<p>As a library matures, it almost always accumulates improvements suggested to
|
||||
the authors by other boost members. It is a part of the culture of
|
||||
boost.org to acknowledge such contributions, identifying the person making the
|
||||
suggestion. Major contributions are usually acknowledged in the
|
||||
documentation, while minor fixes are often mentioned in comments within the code
|
||||
itself.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->24 July, 2000<!--webbot bot="Timestamp" endspan i-checksum="21054" --></p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
169
submission_process.htm
Normal file
169
submission_process.htm
Normal file
@ -0,0 +1,169 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<title>Library Submission Process</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<table border="1" bgcolor="#007F7F" cellpadding="2">
|
||||
<tr>
|
||||
<td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
|
||||
<td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
|
||||
<td><a href="../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
|
||||
<td><a href="../people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
|
||||
<td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
|
||||
<td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<h1>Boost Library Submission Process</h1>
|
||||
<p>This page describes the process of getting a library accepted by Boost.
|
||||
The process is still evolving, so if you have suggestions for improvement by all
|
||||
means post them on the mailing list.</p>
|
||||
<p>See the <a href="lib_guide.htm">Boost Library Requirements and Guidelines</a>
|
||||
page for issues of content.</p>
|
||||
<h3><b>Steps for getting a library accepted by Boost:</b></h3>
|
||||
<ul>
|
||||
<li><a href="#Learn">Learn about Boost</a>.</li>
|
||||
<li><a href="#interest">Determine interest</a>.</li>
|
||||
<li><a href="#Preliminary">Preliminary submission</a>.</li>
|
||||
<li><a href="#Refinement">Refinement</a>.</li>
|
||||
<li><a href="#Review">Formal Review</a>.</li>
|
||||
<li><a href="#site posting">Web site posting</a>.</li>
|
||||
<li><a href="#Lifecycle">Lifecycle</a>.</li>
|
||||
</ul>
|
||||
<h2><a name="Learn">Learn</a> about Boost</h2>
|
||||
<p>Subscribe to the <a href="../index.htm#Mailing List">mailing list</a> for a
|
||||
while, or look through the <a href="http://www.egroups.com/messages/boost">archives</a>.
|
||||
Click around the <a href="../index.htm">web site</a>. Understand the <a href="lib_guide.htm">Requirements</a>.
|
||||
Read the rest of this page to learn about the process. Otherwise, you will
|
||||
just end up wasting everyone's time.</p>
|
||||
<p>There is a culture associated with Boost, aimed at encouraging high quality
|
||||
libraries by a process of discussion and refinement.</p>
|
||||
<p>If what you really want is a site that will just post your library without
|
||||
even looking at it, you should go elsewhere.</p>
|
||||
<h2>Determine <a name="interest">interest</a></h2>
|
||||
<p>Potential library submitters should use the <a href="../index.htm#Mailing List">mailing
|
||||
list</a> as a forum to gauge interest a possible submission.</p>
|
||||
<p>A message might be as simple as "Is there any interest in a library
|
||||
which solves Traveling Salesperson problems in linear time?"</p>
|
||||
<p>A bit of further description or snippet of code may be helpful. Messages
|
||||
should be plain text; not rich text, HTML, etc.</p>
|
||||
<p>Please don't post lengthy descriptions, documentation, or code to the mailing
|
||||
list, and no attachments, even small ones. Please post lengthy material in
|
||||
the eGroups boost <a href="http://www.egroups.com/files/boost/">Files section</a>
|
||||
(formerly called the " vault"). </p>
|
||||
<h2><a name="Preliminary">Preliminary</a> submission</h2>
|
||||
<p>If response to an initial query indicates interest, then post preliminary
|
||||
files in the <a href="http://www.egroups.com/files/boost/">Files section</a> of
|
||||
the boost eGroups web site if you haven't already done so.</p>
|
||||
<h2><a name="Refinement">Refinement</a></h2>
|
||||
<p>Discuss, refine, resubmit. Repeat until satisfied.</p>
|
||||
<p>The exact details of this process varies a lot. Sometimes it is public,
|
||||
on the mailing list, sometimes a lot of discussion happens in private
|
||||
emails. For some libraries the process is over quickly, for others it goes
|
||||
on for months. It's often challenging, and sometimes leads off in
|
||||
completely unexpected directions. </p>
|
||||
<p>The <a href="http://www.egroups.com/messages/boost">archive</a> of past
|
||||
messages is one way to see how this process worked for other boost
|
||||
libraries. </p>
|
||||
<h2>Formal <a name="Review">Review</a></h2>
|
||||
<p><i>[The Formal Review procedure is new as of 9 May, 2000, and will be refined
|
||||
as experience dictates.]</i></p>
|
||||
<p>Once a library author feels a submission (which presumably is now in the
|
||||
files/vault) has matured enough for formal review, the author sends a message
|
||||
requesting a formal review to the mailing list. Please use a subject in
|
||||
the form "Review Request: library" where <i>library</i> is replaced by
|
||||
the library name.</p>
|
||||
<p>Reviews are scheduled so that:</p>
|
||||
<ul>
|
||||
<li>Each library gets review time proportional to its size, complexity, and
|
||||
importance.</li>
|
||||
<li>Only a small number of libraries are under active review at any one time.</li>
|
||||
<li>Members know ahead of time when a particular library will be under active
|
||||
review. </li>
|
||||
</ul>
|
||||
<p>Before a library can be scheduled for review, an active boost member not
|
||||
connected with the library submission must volunteer to be the "Review
|
||||
Manager" for that library. The review manager decides on the schedule,
|
||||
posts a notice when the review period starts, how long it lasts, and how boost
|
||||
members can contribute their comments. The review manager collects comments,
|
||||
chairs any discussions, and then when the review period is over, decides if
|
||||
there is enough consensus to accept the library.</p>
|
||||
<p>See <a href="formal_review_process.htm">Formal Review Process</a> for
|
||||
details.</p>
|
||||
<p>Members only can see <a href="http://www.egroups.com/files/boost/Members+Only/formal_review_schedule.htm">Formal
|
||||
Review Schedule</a> for the current library review schedule. </p>
|
||||
<p><i>[The plan is that the first several reviews will be managed by long-time
|
||||
boost contributors who will be encouraged to experiment with the review
|
||||
process. Presumably, successful processes will evolve over time and
|
||||
can then be documented.]</i></p>
|
||||
<h2>Boost <a name="site posting">site posting</a></h2>
|
||||
<h3>Packaging</h3>
|
||||
<p>All of the files which make up the library should be combined and compressed
|
||||
into a single final submission file using the .zip format. Free encoders
|
||||
and decoders for this format running on many different platforms are available
|
||||
at the <a href="http://www.info-zip.org/pub/infozip/">Info-ZIP</a> web site, which
|
||||
includes a FAQ and much other useful information about the .zip format. Many
|
||||
commercial compressor-archiver utilities also support this format.</p>
|
||||
<h3><a name="Final">Final</a> Submission file</h3>
|
||||
<p>The final submission file contains the material that will live on the
|
||||
boost.org web site. The closer the submission file mirrors the directory
|
||||
structure and format of the web site, the easier it is for the webmaster to
|
||||
integrate it into the web site.
|
||||
<p>The submission file for a library named <b>foo</b> should include these
|
||||
subdirectories, with the contents indicated:
|
||||
<blockquote>
|
||||
<p><b>libs/foo</b>
|
||||
<ul>
|
||||
<li>An introductory page named index.html or index.htm which looks like the
|
||||
initial page of other libraries. <a href="../libs/rational/index.html">Rational</a>
|
||||
is a model for single part libraries, <a href="../libs/integer/index.htm">Integer</a>
|
||||
or <a href="../libs/utility/index.htm">Utility</a> are models for
|
||||
multi-part libraries.</li>
|
||||
<li>The documentation page or pages, also in HTML format.</li>
|
||||
<li>Source files implementing the library if it isn't entirely header
|
||||
based. The boost file type convention for source files is <b>.cpp</b>.</li>
|
||||
<li>Test programs and data files if supplied.</li>
|
||||
<li>If the library has a large number of subsidiary files which aren't
|
||||
linked to from the documentation pages, these subsidiary files can be
|
||||
combined into a single .zip file.</li>
|
||||
</ul>
|
||||
<p><b>boost</b></p>
|
||||
<ul>
|
||||
<li>Public header files as described in the documentation for the
|
||||
library. The boost file type convention for header files is <b>.hpp</b>.</li>
|
||||
</ul>
|
||||
<p><b>boost/detail</b></p>
|
||||
<ul>
|
||||
<li>Implementation header files not normally accessed by library users.</li>
|
||||
</ul>
|
||||
</blockquote>
|
||||
<h3>Transmission</h3>
|
||||
<p>Submit via email to <a href="mailto:webmaster@boost.org">webmaster@boost.org</a>.
|
||||
Attach the .zip submission file. In the email message, please include your
|
||||
email address, postal mail address, and telephone number, if boost.org doesn't
|
||||
already have them. Your addresses and phone number will not appear on the web
|
||||
site (unless you include them in your biography). Anonymous postings are
|
||||
not accepted.</p>
|
||||
<h3>People pages</h3>
|
||||
<p>If the boost.org web site doesn't already have your capsule biography
|
||||
and picture (optional, with not-too-serious pictures preferred), please
|
||||
send them <a href="../index.htm#webmaster">mailto:webmaster@boost.org</a>. It is
|
||||
up to you as to whether or not the biography includes your email address or
|
||||
other contact information. The preferred picture format is .jpg, but other
|
||||
common formats are acceptable. The preferred image size is 500x375 but the
|
||||
webmaster has photo editing software and can do the image preparation if
|
||||
necessary.</p>
|
||||
<h2><a name="Lifecycle">Lifecycle</a></h2>
|
||||
<p>Libraries are software; they loose their value over time if not
|
||||
maintained. Details still hazy.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 June, 2000<!--webbot bot="Timestamp" endspan i-checksum="19847" --></p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
52
use_other_libs.htm
Normal file
52
use_other_libs.htm
Normal file
@ -0,0 +1,52 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<title>Use other Boost or C</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<ul>
|
||||
<li>Use other Boost or C++ Standard Library components only when the benefits
|
||||
outweigh the costs.</li>
|
||||
</ul>
|
||||
<p>(Details)</p>
|
||||
<p>The benefits of using components from other libraries include clearer, more
|
||||
understandable, code, reduced development and maintenance costs, and the
|
||||
assurance which comes from using well-known and trusted building blocks.</p>
|
||||
<p>The costs incurred may include added compilation and runtime costs, and
|
||||
undesirable coupling between components. If the interface to the
|
||||
additional component is complex, using it may make code less readable, and thus
|
||||
actually increase development and maintenance costs.</p>
|
||||
<p><b>Example where another boost component should be used:</b>
|
||||
boost::noncopyable (in boost/utility.hpp) has considerable benefits; it
|
||||
simplifies code, improves readability, and signals intent. Costs are low
|
||||
as coupling is limited; it uses no other classes and includes only the
|
||||
generally lightweight headers <boost/config.hpp> and <cstddef>.
|
||||
There are no runtime costs at all. With costs so low and benefits so high, other
|
||||
boost libraries should use boost::noncopyable except in exceptional
|
||||
circumstances.</p>
|
||||
<p><b>Example where a standard library component might be used:</b> Providing
|
||||
diagnostic output as a debugging aid can be a nice feature for a library. Yet
|
||||
using Standard Library iostreams for the purpose involves a lot of additional
|
||||
coupling, if iostreams is otherwise unused, and may be a complete waste if the
|
||||
library is used in a GUI or embedded application. It might be better to
|
||||
redesign the boost library so that the user supplies the output mechanism,
|
||||
avoiding marginal use of iostreams.</p>
|
||||
<p><b>Example where another boost component should not be used:</b> The
|
||||
boost dir_it library has considerable coupling and runtime costs, not to mention
|
||||
portability issues with unsupported operating systems. While completely
|
||||
appropriate when directory iteration is required, it would not be reasonable for
|
||||
another boost library to use dir_it just to check that a file is available
|
||||
before opening, since Standard Library file open functionality does this at
|
||||
lower cost. Don't use dir_it just for the sake of using a boost library.</p>
|
||||
<p> </p>
|
||||
<p> </p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
Loading…
Reference in New Issue
Block a user