mirror of
https://github.com/boostorg/website.git
synced 2026-01-25 06:42:29 +00:00
1217 lines
50 KiB
HTML
1217 lines
50 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
|
<head>
|
|
<title>Boost Library Requirements and Guidelines</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
|
|
<link rel="icon" href="/favicon.ico" type="image/ico" />
|
|
<link rel="stylesheet" type="text/css"
|
|
href="../style-v2/section-development.css" />
|
|
<!--[if IE 7]> <style type="text/css"> body { behavior: url(/style-v2/csshover3.htc); } </style>
|
|
<![endif]-->
|
|
</head>
|
|
<!--
|
|
Note: Editing website content is documented at:
|
|
http://www.boost.org/development/website_updating.html
|
|
-->
|
|
|
|
<body>
|
|
<div id="heading">
|
|
<!--#include virtual="/common/heading.html" -->
|
|
</div>
|
|
|
|
<div id="body">
|
|
<div id="body-inner">
|
|
<div id="content">
|
|
<div class="section" id="intro">
|
|
<div class="section-0">
|
|
<div class="section-title">
|
|
<h1>Boost Library Requirements and Guidelines</h1>
|
|
</div>
|
|
|
|
<div class="section-body">
|
|
<ul class="toc">
|
|
<li><a href="#Introduction">Introduction</a></li>
|
|
|
|
<li><a href="#Requirements">Requirements</a>
|
|
|
|
<ul>
|
|
<li><a href="#License">License requirements</a></li>
|
|
|
|
<li><a href="#Portability">Portability requirements</a></li>
|
|
|
|
<li><a href="#Ownership">Ownership</a></li>
|
|
|
|
<li><a href="#Organization">Organization</a></li>
|
|
|
|
<li><a href="#Integration">Integration</a></li>
|
|
</ul></li>
|
|
|
|
<li><a href="#Guidelines">Guidelines</a>
|
|
|
|
<ul>
|
|
<li><a href="#Design_and_Programming">Design and
|
|
programming</a></li>
|
|
|
|
<li><a href="#Directory_structure">Directory
|
|
structure and filenames</a></li>
|
|
|
|
<li><a href="#Naming_consistency">Naming
|
|
consistency</a></li>
|
|
|
|
<li><a href="#Documentation">Documentation</a></li>
|
|
</ul></li>
|
|
|
|
<li><a href="#Rationale">Rationale</a>
|
|
|
|
<ul>
|
|
<li><a href="#Exception-specification">Exception-specification
|
|
rationale</a></li>
|
|
|
|
<li><a href="#Naming">Naming conventions rationale</a></li>
|
|
|
|
<li><a href="#code_fonts">Source code fonts
|
|
rationale</a></li>
|
|
|
|
<li><a href="#Tabs">Tabs rationale</a></li>
|
|
|
|
<li><a href="#FileNamesRat">Directory and filename
|
|
rationale</a></li>
|
|
|
|
<li><a href="#JavaScript">ECMAScript/JavaScript
|
|
rationale</a></li>
|
|
|
|
<li><a href="#Rationale_rationale">Rationale
|
|
rationale</a></li>
|
|
|
|
<li><a href="#Acknowledgements">Acknowledgements
|
|
rationale</a></li>
|
|
</ul></li>
|
|
</ul>
|
|
|
|
<h2>
|
|
<a name="Introduction" id="Introduction"></a>Introduction
|
|
</h2>
|
|
|
|
<p>This page describes requirements and guidelines for the
|
|
content of a library submitted to Boost.</p>
|
|
|
|
<p>
|
|
See the <a href="submissions.html">Boost Library Submission
|
|
Process</a> page for a description of the process involved.
|
|
</p>
|
|
|
|
<h2>
|
|
<a name="Requirements" id="Requirements"></a>Requirements
|
|
</h2>
|
|
|
|
<p>To avoid the frustration and wasted time of a proposed
|
|
library being rejected, it must meet 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.
|
|
</li>
|
|
|
|
<li>The copyright <a href="#Ownership">ownership</a> must
|
|
be clear.
|
|
</li>
|
|
|
|
<li>The library should be generally useful.</li>
|
|
|
|
<li>The library must meet the <a href="#Portability">portability
|
|
requirements</a> below.
|
|
</li>
|
|
|
|
<li>The library should preferably meet the <a
|
|
href="#Organization">organization requirements</a> below. But
|
|
is only required to meet them after acceptance.
|
|
</li>
|
|
|
|
<li>The library must come reasonably close to meeting the <a
|
|
href="#Guidelines">Guidelines</a> below.
|
|
|
|
<ul>
|
|
<li><a href="#Design_and_Programming">Design and
|
|
Programming</a></li>
|
|
|
|
<li><a href="#Filenames">Filenames</a></li>
|
|
|
|
<li><a href="#Documentation">Documentation</a></li>
|
|
</ul>
|
|
</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>
|
|
<a name="License" id="License"></a>License requirements
|
|
</h3>
|
|
|
|
<p>
|
|
The preferred way to meet the license requirements is to use the
|
|
<a href="../LICENSE_1_0.txt">Boost Software License</a>. See <a
|
|
href="../users/license.html">license information</a>. If for
|
|
any reason you do not intend to use the Boost Software License,
|
|
please discuss the issues on the Boost <a
|
|
href="../community/groups.html#main">developers mailing
|
|
list</a> first.
|
|
</p>
|
|
|
|
<p>The license requirements:</p>
|
|
|
|
<ul>
|
|
<li>Must be simple to read and understand.</li>
|
|
|
|
<li>Must grant permission without fee to copy, use and
|
|
modify the software for any use (commercial and
|
|
non-commercial).</li>
|
|
|
|
<li>Must require that the license appear on all copies of
|
|
the software source code.</li>
|
|
|
|
<li>Must not require that the license appear with
|
|
executables or other binary uses of the library.</li>
|
|
|
|
<li>Must not require that the source code be available for
|
|
execution or other binary uses of the library.</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>
|
|
<a name="Portability" id="Portability"></a>Portability
|
|
requirements
|
|
</h3>
|
|
|
|
<ul>
|
|
<li>A library's interface must portable and not restricted
|
|
to a particular compiler or operating system.</li>
|
|
|
|
<li>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, and implementations are
|
|
provided for at least two popular operating systems (such as
|
|
UNIX and Windows).</li>
|
|
|
|
<li>There is no requirement that a library run on C++
|
|
compilers which do not conform to the ISO standard.</li>
|
|
|
|
<li>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="../doc/libs/release/libs/config/config.htm">configuration
|
|
header</a> is the preferred mechanism for working around
|
|
compiler deficiencies.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>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>
|
|
<a name="Ownership" id="Ownership"></a>Ownership
|
|
</h3>
|
|
|
|
<p>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>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>Place a copyright notice in all the important files you
|
|
submit. Boost won't accept libraries without clear copyright
|
|
information.</p>
|
|
|
|
<h3>
|
|
<a name="Organization" id="Organization"></a>Organization
|
|
</h3>
|
|
|
|
<p>The quality of the Boost libraries is not just about the
|
|
APIs and code design. But also about presenting a consistent
|
|
view to users of the libraries as a whole. Upon acceptance
|
|
libraries must adhere to this directory and file structure:</p>
|
|
|
|
<table summary="Boost standard library organization">
|
|
<caption>Boost standard library organization</caption>
|
|
|
|
<thead>
|
|
<tr>
|
|
<th>Sub-directory or file</th>
|
|
|
|
<th>Contents</th>
|
|
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<td><code>build</code></td>
|
|
|
|
<td>Library build files such as a Jamfile, IDE
|
|
projects, Makefiles, Cmake files, etc.</td>
|
|
|
|
<td>Required if the library has sources to build.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>doc</code></td>
|
|
|
|
<td>Sources to build with and built documentation for
|
|
the library. If the library needs to build documentation
|
|
from non-HTML files this location must be buildable with
|
|
Boost Build.</td>
|
|
|
|
<td>Required for all libraries.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>doc/html</code></td>
|
|
|
|
<td>Documentation (HTML) files.</td>
|
|
|
|
<td>Required for all libraries with pregenerated
|
|
documentation. And generated documentation must be
|
|
generated here.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>example</code></td>
|
|
|
|
<td>Sample program files.</td>
|
|
|
|
<td>Required if library has sample files. Which is
|
|
highly recommended.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>index.html</code></td>
|
|
|
|
<td>Redirection to HTML documentation. See <a
|
|
href="#Redirection">"Redirection"</a> for a template for
|
|
this file.
|
|
</td>
|
|
|
|
<td>Required for all libraries.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>
|
|
include/boost/<em>library</em>
|
|
</code></td>
|
|
|
|
<td>Header files for the library.</td>
|
|
|
|
<td>Required for all libraries.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>meta</code></td>
|
|
|
|
<td>Meta-data about the library.</td>
|
|
|
|
<td>Required for all libraries.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>meta/libraries.json</code></td>
|
|
|
|
<td>Contains information about the library used to
|
|
generate website and documentation for the Boost C++
|
|
Libraries collection.</td>
|
|
|
|
<td>Required for all libraries.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>src</code></td>
|
|
|
|
<td>Source files which must be compiled to build the
|
|
library.</td>
|
|
|
|
<td>Required if the library has source files to build.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>test</code></td>
|
|
|
|
<td>Regression or other test programs or scripts. This
|
|
is the <em>only</em> location considered for automated
|
|
testing. If you have additional locations that need to be
|
|
part of automated testing it is required that this
|
|
location refer to the additional test locations.
|
|
</td>
|
|
|
|
<td>Required for all libraries.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>tools</code></td>
|
|
|
|
<td>Tools used, or offered, by the library. The
|
|
structure within this is up to the library, but it's
|
|
recommended to use similar structure as a regular Boost
|
|
library or tool.</td>
|
|
|
|
<td>Required for libraries that have runable tools.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>
|
|
<a name="Integration" id="Integration"></a>Integration
|
|
</h3>
|
|
|
|
<p>
|
|
Once a library is accepted as part of the Boost C++ Libraries it
|
|
is required that it integrate properly into the development,
|
|
testing, documentation, and release processes. This integration
|
|
increases the eventual quality of all the libraries and is
|
|
integral to the expected quality of the whole of the Boost C++
|
|
Libraries from users. In addition to the <a href="#Organization">organization
|
|
requirements</a> above the following integration is required:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt>Building Sources</dt>
|
|
<dd>
|
|
<p>The library needs to provide a Boost Build project that
|
|
the user, and the top level Boost project, can use to build
|
|
the library if it has sources to build. The Jamfile for the
|
|
source build needs to minimally declare the project, the
|
|
library target(s), and register the target(s) for
|
|
installation. For example:</p>
|
|
<p>
|
|
<pre>project boost/my_lib ;
|
|
|
|
lib boost_my_lib : a.cpp ;
|
|
|
|
boost-install boost_my_lib ;</pre>
|
|
</p>
|
|
</dd>
|
|
<dt>Testing</dt>
|
|
<dd>
|
|
<p>
|
|
The library needs to provide a Boost Build project that the
|
|
user, and the root Boost test script, can use to build and
|
|
run the tests for the library. The testing build project
|
|
must be buildable from the
|
|
<tt>project-root/test</tt>
|
|
directory. And must contain the following targets:
|
|
</p>
|
|
<ul>
|
|
<li><tt>minimal</tt> - Tests that are quick to perform.
|
|
They are only run durgin the continuous integration
|
|
testing.</li>
|
|
<li><tt>full</tt> - The <tt>minimal</tt> tests, plus
|
|
additional tests to do resonably full coverave for full
|
|
regression testing. These are run on the non-CI dedicated
|
|
testing machines (and possible on some CI setups).</li>
|
|
<li><tt>extra</tt> - Additional tests, not including
|
|
the <tt>full</tt> tests, that provide testing for optional
|
|
features, or relevant to particular users.</li>
|
|
</ul>
|
|
<p>
|
|
You can also define additional targets as you see fit. For
|
|
example you might define a
|
|
<tt>performance</tt>
|
|
target to run performance measurement tests.
|
|
</p>
|
|
<p>
|
|
Note, we recommend that the
|
|
<tt>full</tt>
|
|
target be the default. For example:
|
|
</p>
|
|
<pre>using testing ;
|
|
|
|
project test ;
|
|
|
|
test-suite minimal : [ run a.cpp ] ;
|
|
test-suite full : minimal [ compile b.cpp ] ;
|
|
test-suite extra : [ run c.cpp ] ;
|
|
|
|
explicit minimal ;
|
|
explicit extra ;</pre>
|
|
<p>WARNING: This is the only location considered for
|
|
testing by the top level testing script. If you want to test
|
|
additional locations you must declare such that they are
|
|
built as dependencies to the above targets.</p>
|
|
</dd>
|
|
<dt>Building Documentation</dt>
|
|
<dd>
|
|
<p>
|
|
The library needs to provide a Boost Build project for
|
|
building the documentation for the library. The
|
|
<tt>project-root/doc</tt>
|
|
project is the only location refered to by the top level
|
|
documentation build scripts and the release building
|
|
scripts. The documentation build project must have the
|
|
following two features:
|
|
</p>
|
|
<ol>
|
|
<li>Define a <tt>boostdoc</tt> target. This target
|
|
should likely be an alias that looks roughly like:<br />
|
|
<pre>alias boostdoc : my_boostbook_target
|
|
: : : <implicit-dependency>my_boostbook_target ;</pre> But if your project
|
|
doesn't integrate into the global documentation book you
|
|
can use an empty alias like:<br /> <pre>alias boostdoc ;</pre></li>
|
|
<li>The project must default to building standalone
|
|
documentation if it has any. The release scripts build
|
|
this default so as to guarantee all projects have up to
|
|
date documentation.</li>
|
|
</ol>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2>
|
|
<a name="Guidelines" id="Guidelines"></a>Guidelines
|
|
</h2>
|
|
|
|
<p>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>
|
|
<a name="Design_and_Programming" id="Design_and_Programming"></a>Design
|
|
and Programming
|
|
</h3>
|
|
|
|
<p>Aim first for clarity and correctness; optimization should
|
|
be only a secondary concern in most Boost libraries.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>
|
|
Headers should be good neighbors. See the <a
|
|
href="./header.html">header policy</a>. See <a
|
|
href="#Naming_consistency">Naming consistency</a>.
|
|
</p>
|
|
|
|
<p>Follow quality programming practices. See, for example,
|
|
"Effective C++" 2nd Edition, and "More Effective C++", both by
|
|
Scott Meyers, published by Addison Wesley.</p>
|
|
|
|
<p>
|
|
Use the C++ Standard Library or other Boost libraries, but only
|
|
when the benefits outweigh the costs. Do not use libraries other
|
|
than the C++ Standard Library or Boost. See <a
|
|
href="./reuse.html">Library reuse</a>.
|
|
</p>
|
|
|
|
<p>
|
|
Read <a href="../community/implementation_variations.html">Implementation
|
|
Variation</a> to see how to supply performance, platform, or other
|
|
implementation variations.
|
|
</p>
|
|
|
|
<p>
|
|
Browse through <a
|
|
href="https://svn.boost.org/trac/boost/wiki/BestPracticeHandbook">
|
|
the Best Practices Handbook</a> for ideas and links to source code
|
|
in existing Boost libraries.
|
|
</p>
|
|
|
|
<p>
|
|
Read the <a href="./separate_compilation.html">guidelines
|
|
for libraries with separate source</a> to see how to ensure that
|
|
compiled link libraries meet user expectations.
|
|
</p>
|
|
|
|
<p>
|
|
Use the naming conventions of the C++ Standard Library (See <a
|
|
href="#Naming">Naming conventions rationale</a>):
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Names (except as noted below) should be all lowercase,
|
|
with words separated by underscores.</li>
|
|
|
|
<li>Acronyms should be treated as ordinary names (e.g. <code>xml_parser</code>
|
|
instead of <code>XML_parser</code>).
|
|
</li>
|
|
|
|
<li>Template parameter names begin with an uppercase
|
|
letter.</li>
|
|
|
|
<li>Macro (gasp!) names all uppercase and begin with
|
|
BOOST_.</li>
|
|
</ul>
|
|
|
|
<p>Choose meaningful names - explicit is better than implicit,
|
|
and readability counts. There is a strong preference for clear
|
|
and descriptive names, even if lengthy.</p>
|
|
|
|
<p>Use exceptions to report errors where appropriate, and
|
|
write code that is safe in the face of exceptions.</p>
|
|
|
|
<p>
|
|
Avoid exception-specifications. See <a
|
|
href="#Exception-specification">exception-specification
|
|
rationale</a>.
|
|
</p>
|
|
|
|
<p>Provide sample programs or confidence tests so potential
|
|
users can see how to use your library.</p>
|
|
|
|
<p>
|
|
Provide a regression test program or programs which follow the <a
|
|
href="./test.html">Test Policies and Protocols</a>.
|
|
</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<ul>
|
|
<li>Use fixed-width fonts. See <a href="#code_fonts">fonts
|
|
rationale</a>.
|
|
</li>
|
|
|
|
<li>Use spaces rather than tabs. See <a href="#Tabs">tabs
|
|
rationale</a>.
|
|
</li>
|
|
|
|
<li>Limit line lengths to 80 characters.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
End all documentation files (HTML or otherwise) with a copyright
|
|
message and a licensing message. See the <a
|
|
href="../users/license.html">license information</a> page for
|
|
the preferred form.
|
|
</p>
|
|
|
|
<p>Begin all source files (including programs, headers,
|
|
scripts, etc.) with:</p>
|
|
|
|
<ul>
|
|
<li>A comment line describing the contents of the file.</li>
|
|
|
|
<li>Comments describing copyright and licensing: again, the
|
|
preferred form is indicated in the <a
|
|
href="../users/license.html">license information</a> page
|
|
</li>
|
|
|
|
<li>Note that developers should not provide a copy of <code>LICENSE_1_0.txt</code>
|
|
with their libraries: Boost distributions already include a
|
|
copy in the Boost root directory.
|
|
</li>
|
|
|
|
<li>A comment line referencing your library on the Boost
|
|
web site. For example: <pre>
|
|
// See http://www.boost.org/libs/foo for library home page.
|
|
</pre>
|
|
|
|
<p>
|
|
Where
|
|
<code>foo</code>
|
|
is the directory name (see below) for the library. As well
|
|
as aiding users who come across a Boost file detached from
|
|
its documentation, some of Boost's automatic tools depend on
|
|
this comment to identify which library header files belong
|
|
to.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<strong>Assertions:</strong> If you want to add runtime
|
|
assertions to your code (you should!), avoid C's
|
|
<code>assert</code>
|
|
macro and use Boost's
|
|
<code>BOOST_ASSERT</code>
|
|
macro (in
|
|
<code>boost/assert.hpp</code>
|
|
) instead. It is more configurable. Use
|
|
<code>BOOST_ASSERT</code>
|
|
in public headers and in library source code (for separately
|
|
compiled libraries). Use of C's
|
|
<code>assert</code>
|
|
macro is ok in examples and in documentation.
|
|
</p>
|
|
|
|
<p>
|
|
Make sure your code compiles in the presence of the
|
|
<code>min()</code>
|
|
and
|
|
<code>max()</code>
|
|
macros. Some platform headers define
|
|
<code>min()</code>
|
|
and
|
|
<code>max()</code>
|
|
macros which cause some common C++ constructs to fail to
|
|
compile. Some simple tricks can protect your code from
|
|
inappropriate macro substitution:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>If you want to call <code>std::min()</code> or <code>std::max()</code>:
|
|
|
|
<ul>
|
|
<li>If you do not require argument-dependent look-up,
|
|
use <code>(std::min)(a,b)</code>.
|
|
</li>
|
|
|
|
<li>If you do require argument-dependent look-up, you
|
|
should:
|
|
|
|
<ul>
|
|
<li><code>#include <boost/config.hpp></code></li>
|
|
|
|
<li>Use <code>BOOST_USING_STD_MIN();</code> to
|
|
bring <code>std::min()</code> into the current scope.
|
|
</li>
|
|
|
|
<li>Use <code>min
|
|
BOOST_PREVENT_MACRO_SUBSTITUTION (a,b);</code> to make an
|
|
argument-dependent call to <code>min(a,b)</code>.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>If you want to call <code>std::numeric_limits<int>::max()</code>,
|
|
use <code>(std::numeric_limits<int>::max)()</code>
|
|
instead.
|
|
</li>
|
|
|
|
<li>If you want to call a <code>min()</code> or <code>max()</code>
|
|
member function, instead to doing <code>obj.min()</code>, use
|
|
<code>(obj.min)()</code>.
|
|
</li>
|
|
|
|
<li>If you want to declare or define a function or a member
|
|
function named <code>min</code> or <code>max</code>, then you
|
|
must use the <code>BOOST_PREVENT_MACRO_SUBSTITUTION</code>
|
|
macro. Instead of writing <code>int min() { return 0; }</code>
|
|
you should write <code>int min
|
|
BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; }</code> This is
|
|
true regardless if the function is a free (namespace scope)
|
|
function, a member function or a static member function, and
|
|
it applies for the function declaration as well as for the
|
|
function definition.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>
|
|
<a name="Filenames" id="Filenames"></a>Filenames
|
|
</h3>
|
|
|
|
<p>Naming requirements ensure that file and directory names
|
|
are relatively portable, including to ISO 9660:1999 (with
|
|
extensions) and other relatively limited file systems.
|
|
Superscript links are provided to detailed rationale for each
|
|
choice.</p>
|
|
|
|
<ul>
|
|
<li>Names must contain only <strong>lowercase</strong><sup><a
|
|
href="#Filename_rationale_1">1</a></sup> ASCII letters (<code>'a'</code>-<code>'z'</code>),
|
|
numbers (<code>'0'</code>-<code>'9'</code>), underscores (<code>'_'</code>),
|
|
hyphens (<code>'-'</code>), and periods (<code>'.'</code>).
|
|
Spaces are not allowed<sup><a
|
|
href="#Filename_rationale_2">2</a></sup>.
|
|
</li>
|
|
|
|
<li>Directory names must not contain periods (<code>'.'</code>)<sup><a
|
|
href="#Filename_Rationale_3">3</a></sup>.
|
|
</li>
|
|
|
|
<li>The first and last character of a file name must not be
|
|
a period (<code>'.'</code>)<sup><a
|
|
href="#Filename_rationale_4">4</a></sup>.
|
|
</li>
|
|
|
|
<li>The first character of names must not be a hyphen (<code>'-'</code>)<sup><a
|
|
href="#Filename_rationale_5">5</a></sup>.
|
|
</li>
|
|
|
|
<li>The maximum length of directory and file names is 31
|
|
characters<sup><a href="#Filename_rationale_6">6</a></sup>.
|
|
</li>
|
|
|
|
<li>The total path length must not exceed 207 characters<sup><a
|
|
href="#Filename_rationale_7">7</a></sup>.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Other conventions ease communication:</p>
|
|
|
|
<ul>
|
|
<li>Files intended to be processed by a C++ compiler as
|
|
part of a translation unit should have <strong>a
|
|
three-letter filename extension ending in "pp"</strong>. Other files
|
|
should <i>not</i> use extensions ending in "pp". This
|
|
convention makes it easy to identify all of the C++ source in
|
|
Boost.
|
|
</li>
|
|
|
|
<li>All libraries have at their highest level a primary
|
|
directory named for the particular library. See <a
|
|
href="#Naming_consistency">Naming consistency</a>. The primary
|
|
directory may have sub-directories.
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>
|
|
<a name="Redirection" id="Redirection"></a>Redirection
|
|
</h4>
|
|
|
|
<p>
|
|
The primary directory should always contain a file named
|
|
index.html. Authors have requested this so that they can publish
|
|
URL's in the form <i>http://www.boost.org/libs/lib-name</i> with
|
|
the assurance a documentation reorganization won't invalidate
|
|
the URL. Boost's internal tools are also simplified by knowing
|
|
that a library's documentation is always reachable via the
|
|
simplified URL.
|
|
</p>
|
|
|
|
<p>
|
|
The primary directory
|
|
<code>index.html</code>
|
|
file should just do an automatic redirection to the
|
|
<code>doc/html</code>
|
|
subdirectory:
|
|
</p>
|
|
<pre>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
|
<head>
|
|
<title>Boost.<var>Name</var> Documentation</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
|
|
<meta http-equiv="refresh" content="0; URL=doc/html/index.html" />
|
|
</head>
|
|
|
|
<body>
|
|
Automatic redirection failed, please go to <a href=
|
|
"doc/index.html">doc/index.html</a>
|
|
</body>
|
|
</html>
|
|
</pre>
|
|
|
|
<h3>
|
|
<a name="Naming_consistency" id="Naming_consistency"></a>Naming
|
|
consistency
|
|
</h3>
|
|
|
|
<p>As library developers and users have gained experience with
|
|
Boost, the following consistent naming approach has come to be
|
|
viewed as very helpful, particularly for larger libraries that
|
|
need their own header subdirectories and namespaces.</p>
|
|
|
|
<p>Here is how it works. The library is given a name that
|
|
describes the contents of the library. Cryptic abbreviations are
|
|
strongly discouraged. Following the practice of the C++ Standard
|
|
Library, names are usually singular rather than plural. For
|
|
example, a library dealing with file systems might chose the
|
|
name "filesystem", but not "filesystems", "fs" or "nicecode".</p>
|
|
|
|
<ul>
|
|
<li>The library's primary directory (in parent <var>boost-root/libs</var>)
|
|
is given that same name. For example, <var>boost-root/libs/filesystem</var>.
|
|
</li>
|
|
|
|
<li>The library's primary header directory (in <var>boost-root/libs/name/include</var>)
|
|
is given that same name. For example, <var>boost-root/libs/filesystem/boost/filesystem</var>.
|
|
</li>
|
|
|
|
<li>The library's primary namespace (in parent <em>::boost</em>)
|
|
is given that same name, except when there's a component with
|
|
that name (e.g., <em>boost::tuple</em>), in which case the
|
|
namespace name is pluralized. For example, <em>::boost::filesystem</em>.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>When documenting Boost libraries, follow these conventions
|
|
(see also the following section of this document):</p>
|
|
|
|
<ul>
|
|
<li>The library name is set in roman type.</li>
|
|
|
|
<li>The library name is capitalized.</li>
|
|
|
|
<li>A period between "Boost" and the library name (e.g.,
|
|
Boost.Bind) is used if and only if the library name is not
|
|
followed by the word "library".</li>
|
|
|
|
<li>The word "library" is not part of the library name and
|
|
is therefore lowercased.</li>
|
|
</ul>
|
|
|
|
<p>Here are a few examples of how to apply these conventions:</p>
|
|
|
|
<ul>
|
|
<li>Boost.Bind was written by Peter Dimov.</li>
|
|
|
|
<li>The Boost Bind library was written by Peter Dimov.</li>
|
|
|
|
<li>I regularly use Bind, a Boost library written by Peter
|
|
Dimov.</li>
|
|
</ul>
|
|
|
|
<h3>
|
|
<a name="Documentation" id="Documentation"></a>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. Style
|
|
sheets are acceptable. ECMAScript/JavaScript is discouraged. The
|
|
documentation entry point should always be a file named
|
|
index.html; see <a href="#Redirection">Redirection</a>.
|
|
</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:</p>
|
|
|
|
<ul>
|
|
<li>General introduction to the library. The introduction
|
|
particularly needs to include:
|
|
|
|
<ul>
|
|
<li>A very high-level overview of what the library is
|
|
good for, and perhaps what it isn't good for,
|
|
understandable even by those with no prior knowledge of
|
|
the problem domain.</li>
|
|
|
|
<li>The simplest possible ("hello world") example of
|
|
using the library.</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>Tutorial covering basic use cases.</li>
|
|
|
|
<li>Reference documentation:
|
|
|
|
<ul>
|
|
<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>
|
|
</ul>
|
|
</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>
|
|
|
|
<p>
|
|
If you need more help with how to write documentation you can
|
|
check out the article on <a
|
|
href="../doc/libs/release/more/writingdoc/index.html">Writing
|
|
Documentation for Boost</a>.
|
|
</p>
|
|
|
|
<h2>
|
|
<a name="Rationale" id="Rationale"></a>Rationale
|
|
</h2>
|
|
|
|
<p>Rationale for some of the requirements and guidelines
|
|
follows.</p>
|
|
|
|
<h3>
|
|
<a name="Exception-specification" id="Exception-specification"></a>Exception-specification
|
|
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 improve performance. But consider the
|
|
following 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 <strong>very</strong> 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>
|
|
|
|
<h3>
|
|
<a name="Naming" id="Naming"></a>Naming 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.</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.</li>
|
|
|
|
<li>Once a library settles on a particular convention, a
|
|
vast majority of stakeholders want that style to be
|
|
consistently used.</li>
|
|
</ul>
|
|
|
|
<h3>
|
|
<a name="code_fonts" id="code_fonts"></a>Source code fonts
|
|
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>
|
|
|
|
<h3>
|
|
<a name="Tabs" id="Tabs"></a>Tabs rationale
|
|
</h3>
|
|
|
|
<p>
|
|
Tabs are banned because of the practical problems caused by tabs
|
|
in multi-developer projects like Boost, rather than any dislike
|
|
in principle. See <a href="../community/groups.html#archive">mailing
|
|
list archives</a>. Problems include maintenance of a single source
|
|
file by programmers using tabs and programmers using spaces, and
|
|
the difficulty of enforcing a consistent tab policy other than
|
|
just "no tabs". Discussions concluded that Boost files should
|
|
either all use tabs, or all use spaces, and thus the decision to
|
|
stick with spaces for indentation.
|
|
</p>
|
|
|
|
<h3>
|
|
<a name="FileNamesRat" id="FileNamesRat"></a>Directory and File
|
|
Names rationale
|
|
</h3>
|
|
|
|
<p>
|
|
<a name="Filename_rationale_1" id="Filename_rationale_1">1</a>.
|
|
Some legacy file systems require single-case names. Single-case
|
|
names eliminate casing mistakes when moving from
|
|
case-insensitive to case-sensitive file systems.
|
|
</p>
|
|
|
|
<p>
|
|
<a name="Filename_rationale_2" id="Filename_rationale_2">2</a>.
|
|
This is the lowercase portion of the POSIX portable filename
|
|
character set. To quote the POSIX standard, "Filenames should be
|
|
constructed from the portable filename character set because the
|
|
use of other characters can be confusing or ambiguous in certain
|
|
contexts."
|
|
</p>
|
|
|
|
<p>
|
|
<a name="Filename_Rationale_3" id="Filename_Rationale_3">3</a>.
|
|
Strict implementations of ISO 9660:1999 and some legacy
|
|
operating systems prohibit dots in directory names. The need for
|
|
this restriction is fading, and it will probably be removed
|
|
fairly soon.
|
|
</p>
|
|
|
|
<p>
|
|
<a name="Filename_rationale_4" id="Filename_rationale_4">4</a>.
|
|
POSIX has special rules for names beginning with a period.
|
|
Windows prohibits names ending in a period.
|
|
</p>
|
|
|
|
<p>
|
|
<a name="Filename_rationale_5" id="Filename_rationale_5">5</a>.
|
|
Would be too confusing or ambiguous in certain contexts.
|
|
</p>
|
|
|
|
<p>
|
|
<a name="Filename_rationale_6" id="Filename_rationale_6">6</a>.
|
|
We had to draw the line somewhere, and so the limit imposed by a
|
|
now obsolete Apple file system was chosen years ago. It still
|
|
seems a reasonable limit to aid human comprehension.
|
|
</p>
|
|
|
|
<p>
|
|
<a name="Filename_rationale_7" id="Filename_rationale_7">7</a>.
|
|
ISO 9660:1999.
|
|
</p>
|
|
|
|
<h3>
|
|
<a name="JavaScript" id="JavaScript"></a>ECMAScript/JavaScript
|
|
rationale
|
|
</h3>
|
|
|
|
<p>
|
|
Before the 1.29.0 release, two Boost libraries added
|
|
ECMAScript/JavaScript documentation. Controversy followed (see <a
|
|
href="../community/groups.html#archive">mailing list
|
|
archives</a>), and the developers were asked to remove the
|
|
ECMAScript/JavaScript. Reasons given for banning included:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Incompatible with some older browsers and some text
|
|
based browsers.</li>
|
|
|
|
<li>Makes printing docs pages difficult.</li>
|
|
|
|
<li>Often results in really bad user interface design.</li>
|
|
|
|
<li>"It's just annoying in general."</li>
|
|
|
|
<li>Would require Boost to test web pages for
|
|
ECMAScript/JavaScript compliance.</li>
|
|
|
|
<li>Makes docs maintenance by other than the original
|
|
developer more difficult.</li>
|
|
</ul>
|
|
|
|
<p>Please conside those reasons if you decide that JavaScript
|
|
is something you must use. In particular please keep in mind
|
|
that the Boost community is not responsible for testing your use
|
|
of JavaScript. And hence it is up to you to ensure that the
|
|
above issues are fully resolved in your use case.</p>
|
|
|
|
<p>ECMAScript/JavaScript use is allowed but discouraged for
|
|
the reasons above.</p>
|
|
|
|
<h3>
|
|
<a name="Rationale_rationale" id="Rationale_rationale"></a>Rationale
|
|
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
|
|
be 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>
|
|
|
|
<h3>
|
|
<a name="Acknowledgements" id="Acknowledgements"></a>Acknowledgements
|
|
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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="sidebar">
|
|
<!--#include virtual="/common/sidebar-common.html" -->
|
|
<!--#include virtual="/common/sidebar-development.html" -->
|
|
</div>
|
|
|
|
<div class="clear"></div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<div id="footer-left">
|
|
<div id="copyright">
|
|
<p>Copyright Beman Dawes, 2003.</p>
|
|
<p>Copyright Rene Rivera, 2015.</p>
|
|
</div>
|
|
<!--#include virtual="/common/footer-license.html" -->
|
|
</div>
|
|
|
|
<div id="footer-right">
|
|
<!--#include virtual="/common/footer-banners.html" -->
|
|
</div>
|
|
|
|
<div class="clear"></div>
|
|
</div>
|
|
</body>
|
|
</html>
|