mirror of
https://github.com/boostorg/website.git
synced 2026-01-19 04:42:17 +00:00
1182 lines
50 KiB
HTML
1182 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=utf-8" />
|
|
<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]-->
|
|
<script defer data-domain="original.boost.org" src="https://plausible.io/js/script.js"></script></head><!--
|
|
Note: Editing website content is documented at:
|
|
https://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="#Backwards_compatibility">Backwards Compatibility</a></li>
|
|
<li><a href="#Design_and_Programming">Design and
|
|
programming</a></li>
|
|
|
|
<li><a href="#Filenames">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>A library runs on at least two C++ compilers implementing
|
|
the latest ISO C++ standard.</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>config</code></td>
|
|
|
|
<td>Files used for build-time configuration checks. This
|
|
directory may contain source files and build system
|
|
scripts to be used when building the library, tests or
|
|
examples to check if the target system satisfies certain
|
|
conditions. For example, a check may test if the compiler
|
|
implements a certain feature, or if the target system
|
|
supports a certain API.</td>
|
|
|
|
<td>Optional.</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><a title="Library Metadata File Format" href=
|
|
"library_metadata.html">A JSON file containing
|
|
information about the library</a> used to generate
|
|
website and documentation for the Boost C++ Libraries
|
|
collection.</td>
|
|
|
|
<td>Required for all libraries.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>meta/explicit-failures-markup.xml</code></td>
|
|
|
|
<td>XML file describing expected test failures, used to
|
|
generate the test report.</td>
|
|
|
|
<td>Optional</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>
|
|
|
|
<h4>Building Sources</h4>
|
|
|
|
<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>
|
|
<pre>
|
|
project boost/my_lib ;
|
|
|
|
lib boost_my_lib : a.cpp ;
|
|
|
|
boost-install boost_my_lib ;
|
|
</pre>
|
|
|
|
<h4>Testing</h4>
|
|
|
|
<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
|
|
reside in the <tt>project-root/test</tt> directory and must be
|
|
buildable from this or another directory (for example, <tt>b2
|
|
libs/<em>library</em>/test</tt> from the Boost root must
|
|
work.)</p>
|
|
|
|
<p>An example <tt>test/Jamfile</tt> is given below:</p>
|
|
<pre>
|
|
import testing ;
|
|
|
|
run default_constructor.cpp ;
|
|
run copy_constructor.cpp ;
|
|
compile nested_value_type.cpp ;
|
|
compile-fail invalid_conversion_1.cpp ;
|
|
</pre>
|
|
|
|
<p><em>WARNING:</em> 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 or by using <tt>build-project</tt>.</p>
|
|
|
|
<p>If the library requires a level of C++ conformance that
|
|
precludes certain compilers or configurations from working,
|
|
it's possible (and recommended) to declare these requirements
|
|
in the test <tt>Jamfile</tt> so that the tests aren't run, to
|
|
conserve test resources, as given in the example below:</p>
|
|
<pre>
|
|
import testing ;
|
|
import ../../config/checks/config : requires ;
|
|
|
|
project : requirements [ requires cxx11_variadic_templates cxx11_template_aliases ] ;
|
|
|
|
run cpp11_test.cpp ;
|
|
</pre>
|
|
|
|
<p>For more information, see the <a href=
|
|
"../libs/config/doc/html/boost_config/build_config.html">documentation
|
|
of Boost.Config</a>.</p>
|
|
|
|
<h4>Building Documentation</h4>
|
|
|
|
<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>
|
|
|
|
<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="Backwards_compatibility" id=
|
|
"Backwards_compatibility"></a>Backwards Compatibility</h3>
|
|
|
|
Boost libraries generally have a large and diverse user base.
|
|
To ensure successful transitions from old APIs to newer APIs
|
|
under those circumstances, library authors are encouraged to
|
|
follow a few guidelines when introducing breaking changes in
|
|
their library:
|
|
|
|
<ol>
|
|
<li>
|
|
Non-breaking changes can be done without restriction.
|
|
</li>
|
|
<li>
|
|
Small breaking changes can be made, but users should be
|
|
given notice a few releases before the change is published.
|
|
Most breaking changes fall into this category.
|
|
</li>
|
|
<li>
|
|
For large breaking changes <it>with</it> a migration path from
|
|
the old API to the new API (for example <tt>boost::filesystem</tt>
|
|
v2 to v3), the new API should be introduced in a separate
|
|
directory/namespace, and users should be noticed and given
|
|
a few releases to move over. The old API can be removed after
|
|
some time.
|
|
</li>
|
|
<li>
|
|
For large breaking changes <it>without</it> a migration path
|
|
(for example <tt>boost::spirit</tt> v2 to v3), the new API
|
|
should be provided in a separate directory/namespace, and the
|
|
old API should be preserved (because there's no migration path).
|
|
Removing the API should be considered the same as removing a
|
|
Boost library, which can be done but needs a more extensive
|
|
deprecation period.
|
|
</li>
|
|
<li>
|
|
Large breaking changes that are equivalent to a redesign or
|
|
rewrite of the library should be treated as a new library
|
|
and a formal review (or at least a mini review) is encouraged.
|
|
</li>
|
|
</ol>
|
|
|
|
<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 are allowed to provide a copy of
|
|
the license text in <code>LICENSE_1_0.txt</code>,
|
|
<code>LICENSE.txt</code> or <code>LICENSE</code>
|
|
file within repositories of their libraries.</li>
|
|
|
|
<li>A comment line referencing your library on the Boost web
|
|
site. For example:
|
|
<pre>
|
|
// See https://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="Directory_structure" id="Directory_structure"></a>
|
|
<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>https://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=utf-8" />
|
|
<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>
|