boost/more
1
0
Fork 0
mirror of https://github.com/boostorg/more.git synced 2025-04-01 14:50:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

Added guidelines for libs with separate source, plus appropriate links to it.

Browse Source 
[SVN r20899]
This commit is contained in:
John Maddock 2003-11-21 12:32:44 +00:00
parent a0fad4570c
commit a9282af2b2
3 changed files with 1098 additions and 630 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
index.htm
View File

@ -1,140 +1,113 @@
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<title>Boost More Information</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<title>Boost More Information</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" cellpadding="2" bgcolor="#007F7F">
<body bgcolor="#ffffff" text="#000000">
<table border="1" cellpadding="2" bgcolor="#007f7f">
<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 color="#FFFFFF" size="4"
face="Arial">Home</font></a></td>
<td><a href="../libs/libraries.htm"><font color="#FFFFFF"
size="4" face="Arial">Libraries</font></a></td>
<td><a href="../people/people.htm"><font color="#FFFFFF"
size="4" face="Arial">People</font></a></td>
<td><a href="faq.htm"><font color="#FFFFFF" size="4"
face="Arial">FAQ</font></a></td>
<td><a href="index.htm"><font color="#FFFFFF" size="4"
face="Arial">More</font></a></td>
<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 color="#ffffff" size="4" face="Arial">Home</font></a></td>
<td><a href="../libs/libraries.htm"><font color="#ffffff" size="4" face="Arial">Libraries</font></a></td>
<td><a href="../people/people.htm"><font color="#ffffff" size="4" face="Arial">People</font></a></td>
<td><a href="faq.htm"><font color="#ffffff" size="4" face="Arial">FAQ</font></a></td>
<td><a href="index.htm"><font color="#ffffff" size="4" face="Arial">More</font></a></td>
</tr>
</table>
<h1>More Information</h1>
<h2>Boost Policies</h2>
<blockquote>
<p><a href="discussion_policy.htm"><b>Mailing List Discussion
Policy.</b></a>&nbsp; What's acceptable and what isn't.</p>
<p><a href="lib_guide.htm"><b>Library Requirements and
Guidelines</b></a>.&nbsp; Basic standards for those preparing
a submission.</p>
<p><a href="writingdoc/index.html"><strong>Writing
Documentation for Boost</strong></a> Basic guidelines
for writing documentation and templates for quickly generating
<p><a href="discussion_policy.htm"><b>Mailing List Discussion Policy.</b></a>&nbsp;
What's acceptable and what isn't.</p>
<p><a href="lib_guide.htm"><b>Library Requirements and Guidelines</b></a>.&nbsp;
Basic standards for those preparing a submission.</p>
<P><A href="separate_compilation.html"><STRONG>Guidelines for Libraries with Separate
Source</STRONG></A>.&nbsp; Basic tutorial for libraries that require the
building of a separate link library.</P>
<p><a href="writingdoc/index.html"><strong>Writing Documentation for Boost</strong></a>
Basic guidelines for writing documentation and templates for quickly generating
documentation that follows the guidelines.</p>
<p><a href="test_policy.htm"><b>Test Policy and Protocols</b></a>.&nbsp;
How testing works at Boost.</p>
<p><a href="submission_process.htm"><b>Library Submission
Process</b></a>.&nbsp; How to submit a library to Boost.</p>
<p><a href="formal_review_process.htm"><b>Library Formal
Review Process</b></a>. Including how to submit a review
comment.</p>
<p><a href="header.htm"><b>Header Policy</b></a>.&nbsp;
Headers are where a library contacts its users, so
programming practices are particularly important.</p>
<p><a href="imp_vars.htm"><b>Implementation Variations</b></a>.&nbsp;
Sometimes one size fits all, sometimes it doesn't.&nbsp; This
page deals with the trade-offs.</p>
<p><a href="library_reuse.htm"><b>Library Reuse</b></a>.&nbsp;
Should Boost libraries use other boost libraries?&nbsp; What
about the C++ Standard Library?&nbsp; It's another trade-off.</p>
<p><b><a href="moderators.html">Moderators</a></b>.&nbsp; Who they are and
what they do.</p>
<p><a href="test_policy.htm"><b>Test Policy and Protocols</b></a>.&nbsp; How
testing works at Boost.</p>
<p><a href="submission_process.htm"><b>Library Submission Process</b></a>.&nbsp;
How to submit a library to Boost.</p>
<p><a href="formal_review_process.htm"><b>Library Formal Review Process</b></a>.
Including how to submit a review comment.</p>
<p><a href="header.htm"><b>Header Policy</b></a>.&nbsp; Headers are where a
library contacts its users, so programming practices are particularly
important.</p>
<p><a href="imp_vars.htm"><b>Implementation Variations</b></a>.&nbsp; Sometimes
one size fits all, sometimes it doesn't.&nbsp; This page deals with the
trade-offs.</p>
<p><a href="library_reuse.htm"><b>Library Reuse</b></a>.&nbsp; Should Boost
libraries use other boost libraries?&nbsp; What about the C++ Standard
Library?&nbsp; It's another trade-off.</p>
<p><b><a href="moderators.html">Moderators</a></b>.&nbsp; Who they are and what
they do.</p>
</blockquote>
<h2>Boost Whatever</h2>
<blockquote>
<p><b><a href="license_info.html">License Information</a> </b>&nbsp;Information
about the Boost Software License.</p>
<p><b><a href="bibliograpy.html">Bibliography</a> </b>&nbsp;Print and online
publications relating to Boost and Boost libraries.</p>
<p><a href="../status/compiler_status.html"><b>Compiler
Status</b></a>&nbsp;&nbsp;Describes what library works with
which compiler.</p>
<p><b><a href="links.htm">Links</a></b>&nbsp; Links of special interest to
Boost users.</p>
<p><a href="../status/compiler_status.html"><b>Compiler Status</b></a>&nbsp;&nbsp;Describes
what library works with which compiler.</p>
<p><b><a href="links.htm">Links</a></b>&nbsp; Links of special interest to Boost
users.</p>
<p><b><a href="formal_review_schedule.html">Formal Review Schedule</a></b>&nbsp;
Future, current, and recently past Formal Reviews.</p>
<p><b><a href="release_procedures.htm">Release Procedures</a></b>&nbsp; How
developers and the release manager prepare for a Boost release.</p>
<p><a href="regression.html"><b>Internal Regression Test
Suite</b></a>&nbsp;&nbsp; Describes the tool for generating
the compiler status tables </p>
<p><a href="regression.html"><b>Internal Regression Test Suite</b></a>&nbsp;&nbsp;
Describes the tool for generating the compiler status tables
</p>
<p><b><a href="proposal.pdf">Proposal for a C++ Library Repository Web Site</a></b>&nbsp;
The original 1998 proposal that launched Boost.</p>
<p><b><a href="bugs.htm">How to report bugs</a></b>&nbsp; Ways to report
Boost bugs.</p>
<p><b><a href="requesting_new_features.htm">How to request features</a></b>
Ways to request new library features.</p>
<p><b><a href="cpp_committee_meetings.html">C++ Committee Meetings</a></b>
FAQ for Boost Members wishing to attend a standards committee meeting.</p>
<p><b><a href="bugs.htm">How to report bugs</a></b>&nbsp; Ways to report Boost
bugs.</p>
<p><b><a href="requesting_new_features.htm">How to request features</a></b> Ways
to request new library features.</p>
<p><b><a href="cpp_committee_meetings.html">C++ Committee Meetings</a></b> FAQ for
Boost Members wishing to attend a standards committee meeting.</p>
</blockquote>
<h2>Articles and Papers</h2>
<blockquote>
<p><a href="error_handling.html"><b>Error and Exception
Handling</b></a> describes approaches to errors and
exceptions by <a href="../people/dave_abrahams.htm">David
Abrahams</a>. </p>
<p><a href="count_bdy.htm"><b>Counted Body Techniques</b></a>
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.&nbsp; Originally
published in <a
href="http://www.accu.org/c++sig/public/Overload.html">Overload</a>
magazine.</p>
<p><a href="generic_programming.html"><b>Generic Programming
Techniques</b></a> by <a href="../people/dave_abrahams.htm">David
Abrahams</a> and <a href="../people/jeremy_siek.htm">Jeremy
Siek</a> describe some of the techniques used in Boost
libraries.</p>
<p><a href="feature_model_diagrams.htm"><b>Feature Model
Diagrams in text and HTML</b></a> describes how to represent
feature model diagrams in text form.</p>
<p><a href="borland_cpp.html"><b>Portability Hints: Borland C++
5.5.1</b></a> describes Borland C++ portability issues, with
suggested workarounds.</p>
<p><a href="microsoft_vcpp.html"><b>Portability Hints:
Microsoft VC++ 6.0 SP4</b></a> describes Microsoft C++
portability issues, with suggested workarounds.</p>
<p><a href="int_const_guidelines.htm"><strong>Coding
Guidelines for Integral Constant Expressions</strong></a>
describes how to work through the maze of compiler related
bugs surrounding this tricky topic.</p>
<p><a href="error_handling.html"><b>Error and Exception Handling</b></a> describes
approaches to errors and exceptions by <a href="../people/dave_abrahams.htm">David
Abrahams</a>.
</p>
<p><a href="count_bdy.htm"><b>Counted Body Techniques</b></a> 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.&nbsp; Originally published in <a href="http://www.accu.org/c++sig/public/Overload.html">
Overload</a> magazine.</p>
<p><a href="generic_programming.html"><b>Generic Programming Techniques</b></a> by <a href="../people/dave_abrahams.htm">
David Abrahams</a> and <a href="../people/jeremy_siek.htm">Jeremy Siek</a> describe
some of the techniques used in Boost libraries.</p>
<p><a href="feature_model_diagrams.htm"><b>Feature Model Diagrams in text and HTML</b></a>
describes how to represent feature model diagrams in text form.</p>
<p><a href="borland_cpp.html"><b>Portability Hints: Borland C++ 5.5.1</b></a> describes
Borland C++ portability issues, with suggested workarounds.</p>
<p><a href="microsoft_vcpp.html"><b>Portability Hints: Microsoft VC++ 6.0 SP4</b></a>
describes Microsoft C++ portability issues, with suggested workarounds.</p>
<p><a href="int_const_guidelines.htm"><strong>Coding Guidelines for Integral Constant
Expressions</strong></a> describes how to work through the maze of
compiler related bugs surrounding this tricky topic.</p>
</blockquote>
<hr>
<p> Revised
<p>
Revised
<!--webbot bot="Timestamp" s-type="EDITED"
s-format="%d %B, %Y" startspan -->02 October, 2003<!--webbot bot="Timestamp" endspan i-checksum="38549" --></p>
<p> © Copyright Beman Dawes 2003.</p>
<p> Use, modification, and distribution are subject to the Boost Software
License, Version 1.0. (See accompanying file <a href="../LICENSE_1_0.txt">
LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
www.boost.org/LICENSE_1_0.txt</a>)</p>
s-format="%d %B, %Y" startspan -->
02 October, 2003<!--webbot bot="Timestamp" endspan i-checksum="38549" --></p>
<p>
© Copyright Beman Dawes 2003.</p>
<p>
Use, modification, and distribution are subject to the Boost Software License,
Version 1.0. (See accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

536
lib_guide.htm
View File

@ -1,23 +1,20 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Library Requirements and Guidelines</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage 5.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">
<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="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../people/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>
<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="../libs/libraries.htm"><font face="Arial" color="#ffffff"><big>Libraries</big></font></a></td>
<td><a href="../people/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>
@ -30,7 +27,7 @@
&nbsp;&nbsp;&nbsp; <a href="#Design_and_Programming">Design and programming</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Directory_structure">Directory structure and
filenames</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Naming­_consistency">Naming consistency</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Naming&shy;_consistency">Naming consistency</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Documentation">Documentation</a><br>
<a href="#Rationale">Rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Exception-specification">Exception-specification
@ -42,90 +39,91 @@ rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Rationale_rationale">Rationale rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Acknowledgements">Acknowledgements rationale</a></p>
<h2 align="left"><a name="Introduction">Introduction</a></h2>
<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>
<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"><a name="Requirements">Requirements</a></h2>
<p>To avoid the frustration and wasted time of a proposed library being
rejected, it must meets these requirements:</p>
<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>
<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 must be generally useful and not restricted to a narrow
problem domain.
</li>
<li>The library must meet the <a href="#Portability">portability requirements</a>
<li>
The copyright <a href="#Ownership">ownership</a>
must be clear.
<li>
The library must be generally useful and not restricted to a narrow problem
domain.
<li>
The library must meet the <a href="#Portability">portability requirements</a>
below.&nbsp;
</li>
<li>The library must come reasonably close to meeting the <a href="#Guidelines">Guidelines</a>
<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="#Directory_structure">Directory Structure</a></li>
<li><a href="#Documentation">Documentation</a></li>
<li>
<a href="#Design_and_Programming">Design and Programming</a>
<li>
<a href="#Directory_structure">Directory Structure</a>
<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>
<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
&quot;I just started to read this mailing list ...&quot; seem to fail, often
"I just started to read this mailing list ..." seem to fail, often
embarrassingly.</p>
<h3 align="left"><a name="License">License</a> 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="license_info.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="mailing_lists.htm#main">developers mailing list</a> first.</p>
<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="license_info.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="mailing_lists.htm#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
<li>
Must be simple to read and understand.
<li>
Must grant permission without fee to copy, use and modify the software for any
use (commercial and non-commercial).
<li>
Must require that the license appear on all copies of the software source code.
<li>
Must not require that the license appear with executables or other binary uses
of the library.
<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>
<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.
</li>
particular compiler or operating system.</p>
<li>
<p align="left">A library's implementation must if possible be portable and
not restricted to a particular compiler or operating system.&nbsp; 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>
<p align="left">A library's implementation must if possible be portable and not
restricted to a particular compiler or operating system.&nbsp; 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).</p>
<li>
<p align="left">There is no requirement that a library run on C++ compilers
which do not conform to the ISO standard.&nbsp;
</li>
<p align="left">There is no requirement that a library run on C++ compilers which
do not conform to the ISO standard.&nbsp;</p>
<li>
<p align="left">There is no requirement that a library run on any particular
C++ compiler.&nbsp; Boost contributors often try to ensure their libraries
work with popular compilers.&nbsp; The boost/config.hpp <a href="../libs/config/config.htm">configuration
header</a> is the preferred mechanism for working around compiler
deficiencies.</li>
<p align="left">There is no requirement that a library run on any particular C++
compiler.&nbsp; Boost contributors often try to ensure their libraries work
with popular compilers.&nbsp; The boost/config.hpp <a href="../libs/config/config.htm">
configuration header</a> is the preferred mechanism for working around
compiler deficiencies.</p>
</li>
</ul>
<p align="left">Since there is no absolute way to prove portability, many boost
submissions demonstrate practical portability by compiling and executing
@ -134,13 +132,13 @@ systems.&nbsp; 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?&nbsp;&nbsp; &quot;How to Copyright Software&quot; by MJ Salone, Nolo
Press, 1990 says:</p>
submitting?&nbsp;&nbsp; "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.&nbsp; In this situation, it's best to get a written release from
your employer in advance.</p>
<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.&nbsp;
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 won't accept libraries without clear copyright information.</p>
@ -150,116 +148,147 @@ content a library submission.&nbsp; Not every guideline applies to every
library, but a reasonable effort to comply is expected.</p>
<h3><a name="Design_and_Programming">Design and Programming</a></h3>
<ul>
<li>Aim first for clarity and correctness; optimization should be only a
secondary concern in most Boost libraries.</li>
<li>
Aim first for clarity and correctness; optimization should be only a secondary
concern in most Boost libraries.</li>
</ul>
<ul>
<li>Aim for ISO Standard C++. Than means making effective use of the standard
<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>. See <a href="#Naming­_consistency">Naming consistency</a>.</li>
<li>
Headers should be good neighbors. See the <a href="header.htm">header policy</a>.
See <a href="#Naming&shy;_consistency">Naming consistency</a>.</li>
</ul>
<ul>
<li>Follow quality programming practices. See, for example, &quot;Effective
C++&quot; 2nd Edition, and &quot;More Effective C++&quot;, both by Scott
Meyers, published by Addison Wesley.</li>
<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 C++ Standard Library or other Boost libraries, but only when the
<li>
Use the C++ Standard Library or other Boost libraries, but only when the
benefits outweigh the costs.&nbsp; Do not use libraries other than the C++
Standard Library or Boost. See <a href="library_reuse.htm">Library reuse</a>.</li>
</ul>
<ul>
<li>Read <a href="imp_vars.htm">Implementation Variation</a> to see how to
supply performance, platform, or other implementation variations.</li>
<li>
Read <a href="imp_vars.htm">Implementation Variation</a> to see how to supply
performance, platform, or other implementation variations.</li>
</ul>
<ul>
<li>Use the naming conventions of the C++ Standard Library (See
<a href="#Naming">Naming conventions rationale</a>): <br>
&nbsp;<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>
<li>
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.
</li>
</ul>
<ul>
<li>Choose meaningful names - explicit is better than implicit, and readability counts.
There is a strong preference for clear and descriptive names, even if
<LI>
Use the naming conventions of the C++ Standard Library (See <a href="#Naming">Naming
conventions rationale</a>):
<br>
&nbsp;<ul>
<li>
Names (except as noted below) should be all lowercase, with words separated by
underscores.
<li>
Acronyms should be treated as ordinary names (e.g. <code>xml_parser</code> instead
of <code>XML_parser</code>).
<li>
Template parameter names begin with an uppercase letter.
<li>
Macro (gasp!) names all uppercase and begin with BOOST_.</li>
</ul>
</LI>
</ul>
<ul>
<li>
Choose meaningful names - explicit is better than implicit, and readability
counts. There is a strong preference for clear and descriptive names, even if
lengthy.</li>
</ul>
<ul>
<li>Use exceptions to report errors where appropriate, and write code that is
safe in the face of exceptions.</li>
<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
<li>
Avoid exception-specifications. See <a href="#Exception-specification">exception-specification
rationale</a>.</li>
</ul>
<ul>
<li>Provide sample programs or confidence tests so potential users can see how
to use your library.</li>
<li>
Provide sample programs or confidence tests so potential users can see how to
use your library.</li>
</ul>
<ul>
<li>Provide a regression test program or programs which follow the <a href="test_policy.htm">Test
Policies and Protocols</a>.</li>
<li>
Provide a regression test program or programs which follow the <a href="test_policy.htm">
Test Policies and Protocols</a>.</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:
<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.&nbsp; 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>
<li>
Use fixed-width fonts.&nbsp; See <a href="#code_fonts">fonts rationale</a>.
<li>
Use spaces rather than tabs. See <a href="#Tabs">tabs rationale</a>.
<li>
Limit line lengths to 80 characters.</li>
</ul>
</li>
</ul>
<ul>
<li>End all documentation files (HTML or otherwise) with a copyright message
and a licensing message. See the <a href="#Copyright">end of this file</a> for
an example of the preferred form.</li>
<li>
End all documentation files (HTML or otherwise) with a copyright message and a
licensing message. See the <a href="#Copyright">end of this file</a> for an
example of the preferred form.</li>
</ul>
<ul>
<li>Begin all source files (including programs, headers, scripts, etc.) with:
<li>
Begin all source files (including programs, headers, scripts, etc.) with:
<br>
&nbsp;<ul>
<li>A comment line describing the contents of the file.<br>
&nbsp;</li>
<li>Comments describing copyright and licensing. The preferred form is:<br>
<li>
A comment line describing the contents of the file.<br>
&nbsp;
<li>
Comments describing copyright and licensing. The preferred form is:<br>
<br>
<code>//&nbsp; Copyright Jane Programmer 2002. Use, modification, and
distribution are<br>
//&nbsp; subject to the Boost Software License, Version 1.0. (See
accompanying<br>
<code>//&nbsp; Copyright Jane Programmer 2002. Use, modification, and distribution
are<br>
//&nbsp; subject to the Boost Software License, Version 1.0. (See accompanying<br>
//&nbsp; file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)<br>
</code>
<br>
Please leave an empty line before and after the copyright and license
comments. It is fine if the copyright and license messages are on
different lines, but there should be no other intervening text. Do not
include &quot;All rights reserved&quot; in the copyright message.<br>
Please leave an empty line before and after the copyright and license comments.
It is fine if the copyright and license messages are on different lines, but
there should be no other intervening text. Do not include "All rights reserved"
in the copyright message.<br>
<br>
See <a href="license_info.html">license information page</a> for
more information about the Boost Software License.<br>
See <a href="license_info.html">license information page</a> for more
information about the Boost Software License.<br>
<br>
Note that developers should not include a copy of
<code>LICENSE_1_0.txt</code>
in their libraries; Boost distributions already include a copy in the
Boost root directory.<br>
&nbsp;</li>
<li>A comment line referencing your library on the Boost web site. For
example:<br>
Note that developers should not include a copy of <code>LICENSE_1_0.txt</code> in
their libraries; Boost distributions already include a copy in the Boost root
directory.<br>
&nbsp;
<li>
A comment line referencing your library on the Boost web site. For example:<br>
<br>
<code>//&nbsp; See http://www.boost.org/libs/foo for library home page.</code><br>
<br>
where <code>foo</code> is the directory name (see below) for your library.
As well as aiding users who come across a Boost file detached from its
where <code>foo</code> is the directory name (see below) for your 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.</li>
</ul>
@ -267,15 +296,19 @@ library, but a reasonable effort to comply is expected.</p>
</ul>
<h3><a name="Directory_structure">Directory Structure</a> and Filenames</h3>
<ul>
<li>File and directory names must contain only lowercase ASCII letters ,
numbers, underscores, and a period.&nbsp; Leading character must be
alphabetic. Maximum length 31. Only a single period is permitted.&nbsp;
These requirements ensure file and directory names are relatively portable.</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>
<li>For very simple libraries implemented entirely within the library header,
all files go in the primary directory (except headers, which go in the boost
header directory).</li>
<li>
File and directory names must contain only lowercase ASCII letters , numbers,
underscores, and a period.&nbsp; Leading character must be alphabetic. Maximum
length 31. Only a single period is permitted.&nbsp; These requirements ensure
file and directory names are relatively portable.
<li>
All libraries have at their highest level a primary directory named for the
particular library. See <a href="#Naming&shy;_consistency">Naming consistency</a>.
The primary directory may have sub-directories.
<li>
For very simple libraries implemented entirely within the library header, all
files go in the primary directory (except headers, which go in the boost header
directory).</li>
</ul>
<blockquote>
<p><b>Boost standard sub-directory names</b></p>
@ -319,69 +352,81 @@ 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>If the documentation is in a doc sub-directory, the primary directory index.html file
should just do an automatic redirection to the doc subdirectory:</p>
<p>If the documentation is in a doc sub-directory, the primary directory
index.html file should just do an automatic redirection to the doc
subdirectory:</p>
<blockquote>
<pre>&lt;html&gt;
&lt;head&gt;
&lt;meta http-equiv=&quot;refresh&quot; content=&quot;0; URL=doc/index.html&quot;&gt;
&lt;meta http-equiv="refresh" content="0; URL=doc/index.html"&gt;
&lt;/head&gt;
&lt;body&gt;
Automatic redirection failed, please go to
&lt;a href=&quot;doc/index.html&quot;&gt;doc/index.html&lt;/a&gt;
&lt;a href="doc/index.html"&gt;doc/index.html&lt;/a&gt;
&lt;/body&gt;
&lt;/html&gt;</pre>
</blockquote>
<h3><a name="Naming­_consistency">Naming consistency</a></h3>
<h3><a name="Naming&shy;_consistency">Naming consistency</a></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 which need their own header subdirectories and
namespaces.</p>
<p>Here is how it works. The library is given a name which describes the
contents of the library.&nbsp; Cryptic abbreviations are not acceptable.
Following the practice of the C++ Standard Library, names are usually singular
rather than plural.&nbsp; For example, a library dealing with file systems might
chose the name &quot;filesystem&quot;, but not &quot;filesystems&quot;, &quot;fs&quot; or &quot;nicecode&quot;.</p>
particularly for larger libraries which need their own header subdirectories
and namespaces.</p>
<p>Here is how it works. The library is given a name which describes the contents
of the library.&nbsp; Cryptic abbreviations are not acceptable. Following the
practice of the C++ Standard Library, names are usually singular rather than
plural.&nbsp; 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 <i>boost-root/libs</i>) is
given that same name.&nbsp; For example, <i>boost-root/libs/filesystem</i>.<br>
&nbsp;</li>
<li>The library's primary header directory (in parent <i>boost-root/boost</i>)
is given that same name. For example, <i>boost-root/boost/filesystem</i>.<br>
&nbsp;</li>
<li>The library's primary namespace (in parent <i>::boost</i>) is given that
same name. For example, <i>::boost::filesystem</i>.</li>
<li>
The library's primary directory (in parent <i>boost-root/libs</i>) is given
that same name.&nbsp; For example, <i>boost-root/libs/filesystem</i>.<br>
&nbsp;
<li>
The library's primary header directory (in parent <i>boost-root/boost</i>) is
given that same name. For example, <i>boost-root/boost/filesystem</i>.<br>
&nbsp;
<li>
The library's primary namespace (in parent <i>::boost</i>) is given that same
name. For example, <i>::boost::filesystem</i>.</li>
</ul>
<h3><a name="Documentation">Documentation</a></h3>
<p>Even the simplest library needs some documentation; the amount should be
proportional to the need.&nbsp; 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 not acceptable. The documentation entry point should
always be a file named index.html or index.htm; see <a href="#Redirection">
Redirection</a>.</p>
proportional to the need.&nbsp; 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 not acceptable. The documentation entry point should
always be a file named index.html or index.htm; 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 &quot;average&quot;
C++ programmer to use the library successfully?</p>
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.&nbsp; See <a href="#Rationale">Rationale
rationale</a>.</li>
<li>Acknowledgements.&nbsp; See <a href="#Acknowledgements">Acknowledgments
rationale.</a></li>
<li>
General introduction to the library.
<li>
Description of each class.
<li>
Relationship between classes.
<li>
For each function, as applicable, description, requirements (preconditions),
effects, post-conditions, returns, and throws.
<li>
Discussion of error detection and recovery strategy.
<li>
How to use including description of typical uses.
<li>
How to compile and link.
<li>
How to test.
<li>
Version or revision history.
<li>
Rationale for design decisions.&nbsp; See <a href="#Rationale">Rationale rationale</a>.
<li>
Acknowledgements.&nbsp; 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="writingdoc/index.html">Writing Documentation for Boost</a>.</p>
@ -399,18 +444,18 @@ exception-specification can ever be invoked.&nbsp; 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 &quot;dumb&quot; compiler, however, may make
all kinds of pessimizations.</p>
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.&nbsp; 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 &quot;throws nothing&quot;
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>
@ -418,60 +463,64 @@ exception-specification may have some benefit with some compilers.</p>
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
<li>
Naming conventions are contentious, and although several are widely used, no
one style predominates.
<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>
Once a library settles on a particular convention, a vast majority of
stakeholders want that style to be consistently used.
</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
<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>
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="Tabs">Tabs</a> 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="mailing_lists.htm#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 &quot;no tabs&quot;. Discussions concluded that Boost files should either all use
tabs, or all use spaces, and thus the decision to stick with spaces.</p>
multi-developer projects like Boost, rather than any dislike in principle. See <a href="mailing_lists.htm#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.</p>
<hr>
<h3>ECMAScript/<a name="JavaScript">JavaScript</a> rationale</h3>
<p>Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript
documentation. Controversy followed (see <a href="mailing_lists.htm#archive">
mailing list archives</a>), and the developers were asked to remove the
documentation. Controversy followed (see <a href="mailing_lists.htm#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>&quot;It's just annoying in general.&quot;</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>
<li>
Incompatible with some older browsers and some text based browsers.
<li>
Makes printing docs pages difficult.
<li>
Often results in really bad user interface design.
<li>
"It's just annoying in general."
<li>
Would require Boost to test web pages for ECMAScript/JavaScript compliance.
<li>
Makes docs maintenance by other than the original developer more difficult.</li>
</ul>
<hr>
<h3><a name="Rationale_rationale">Rationale rationale</a></h3>
<p>Rationale is defined as &quot;The fundamental reasons for something;
basis&quot; by the American Heritage Dictionary.</p>
<p>Rationale is defined as "The fundamental reasons for something; basis" by the
American Heritage Dictionary.</p>
<p>Beman Dawes comments:&nbsp; 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
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>
@ -481,18 +530,17 @@ hard to accurately recover even a short time later.</p>
the authors by other boost members.&nbsp; It is a part of the culture of
boost.org to acknowledge such contributions, identifying the person making the
suggestion.&nbsp; Major contributions are usually acknowledged in the
documentation, while minor fixes are often mentioned in comments within the code
itself.</p>
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 -->04 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
<p> © <a name="Copyright">Copyright</a> Beman Dawes 2003.</p>
<p> Use, modification, and distribution are subject to the Boost Software
License, Version 1.0. (See accompanying file <a href="../LICENSE_1_0.txt">
LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
www.boost.org/LICENSE_1_0.txt</a>)</p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->
04 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
<p>
© <a name="Copyright">Copyright</a> Beman Dawes 2003.</p>
<p>
Use, modification, and distribution are subject to the Boost Software License,
Version 1.0. (See accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
</body>
</html>

447
separate_compilation.html Normal file
View File

@ -0,0 +1,447 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Guidelines for Authors of Boost Libraries Containing Separate Source</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<LINK href="../boost.css" type="text/css" rel="stylesheet"></head>
<body>
<P>
<TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
<TR>
<td vAlign="top" width="300">
<h3><A href="../index.htm"><IMG height="86" alt="C++ Boost" src="../c++boost.gif" width="277" border="0"></A></h3>
</td>
<TD width="353">
<H1 align="center">Guidelines for Authors of Boost Libraries Containing Separate
Source</H1>
</TD>
</TR>
</TABLE>
</P>
<HR>
<P>These guidelines are designed for the authors of Boost libraries which have
separate source that need compiling in order to use the library. Throughout,
this guide refers to a fictitious "whatever" library, so replace all
occurrences of "whatever" or "WHATEVER" with your own library's name when
copying the examples.</P>
<H2>Contents</H2>
<P>
<dl class="index">
<dt><A href="#source_changes">Changes Affecting Source Code</A>
<dd>
<dl class="index">
<dt><A href="#abi">Preventing Compiler ABI Clashes</A> <dt><A href="#dlls">Supporting
Windows Dll's</A> <dt><A href="#auto-link">Enabling Automatic Library Selection
and Linking</A> </dt>
</dl>
<dt><A href="#build_changes">Changes Affecting the Build System</A>
<dd>
<dl class="index">
<dt><A href="#jamfile">Creating the Library Jamfile</A> <dt><A href="#testing">Testing
Auto-linking</A> </dt>
</dl>
<dt><A href="#copyright">Copyright</A></dt>
</dl>
<P></P>
<h2><A name="source_changes"></A>Changes Affecting Source Code</h2>
<H3><A name="abi"></A>Preventing Compiler ABI Clashes</H3>
<P>There are some compilers (mostly Microsoft Windows compilers again!), which
feature a range of compiler switches that alter the ABI of C++ classes and
functions. By way of example, consider Borland's compiler which has the
following options:</P>
<PRE>-b (on or off - effects enum sizes).
-Vx (on or off - empty members).
-Ve (on or off - empty base classes).
-aX (alignment - 5 options).
-pX (Calling convention - 4 options).
-VmX (member pointer size and layout - 5 options).
-VC (on or off, changes name mangling).
-Vl (on or off, changes struct layout).
</PRE>
<P>These options are provided in addition to those affecting which runtime library
is used (more on which later); the total number of combinations of options can
be obtained by multiplying together the individual options above, so that gives
2*2*2*5*4*5*2*2 = 3200 combinations!
</P>
<P>The problem is that users often expect to be able to build the Boost libraries
and then just link to them and have everything just plain work, no matter what
their project settings are. Irrespective of whether this is a reasonable
expectation or not, without some means of managing this issue, the user may
well find that their program will experience strange and hard to track down
crashes at runtime unless the library they link to was built with the same
options as their project (changes to the default alignment setting are a prime
culprit). One way to manage this is with "prefix and suffix" headers: these
headers invoke compiler specific #pragma directives to instruct the compiler
that whatever code follows was built (or is to be built) with a specific set of
compiler ABI settings.</P>
<P>Boost.config provides the macro BOOST_HAS_ABI_HEADERS which is set whenever
there are prefix and suffix headers available for the compiler in use, typical
usage is like this:</P>
<PRE>#ifndef BOOST_WHATEVER_HPP
#define BOOST_WHATEVER_HPP
#include &lt;boost/config.hpp&gt;
// this must occur after all of the includes and before any code appears:
#ifdef BOOST_HAS_ABI_HEADERS
# include BOOST_ABI_PREFIX
#endif
//
// this header declares one class, and one function by way of examples:
//
class whatever
{
// details.
};
whatever get_whatever();
// the suffix header occurs after all of our code:
#ifdef BOOST_HAS_ABI_HEADERS
# include BOOST_ABI_SUFFIX
#endif
#endif
</PRE>
<H4>Rationale:</H4>
<P>Without some means of managing this issue, users often report bugs along the
line of "Your silly library always crashes when I try and call it" and so on.
These issues can be extremely difficult and time consuming to track down, only
to discover in the end that it's a compiler setting that's changed the ABI of
the class and/or function types of the program compared to those in the
pre-compiled library. The use of prefix/suffix headers can minimize this
problem, although probably not remove it completely.</P>
<H5>Counter Argument #1:</H5>
<P>Trust the user, if they want 13-byte alignment (!) let them have it.</P>
<H5>Counter Argument #2:</H5>
<P>Prefix/suffix headers have a tendency to "spread" to other boost libraries -
for example if boost::shared_ptr&lt;&gt; forms part of your class's ABI, then
including prefix/suffix headers in your code will be of no use unless
shared_ptr.hpp also uses them. Authors of header-only boost libraries may not
be so keen on this solution - with some justification - since they don't face
the same problem.</P>
<h3><A name="dlls"></A>Supporting Windows Dll's</h3>
<p>On most Unix-like platforms no special annotations of source code are required
in order for that source to be compiled as a shared library because all
external symbols are exposed. However the majority of Windows compilers require
that symbols that are to be imported or exported from a dll, be prefixed with
__declspec(dllimport) or __declspec(dllexport). Without this mangling of source
code, it is not possible to correctly build shared libraries on Windows
(historical note - originally these declaration modifiers were required on
16-bit Windows where the memory layout for exported classes was different from
that of "local" classes - although this is no longer an issue, there is still
no way to instruct the linker to "export everything", it also remains to be
seen whether 64-bit Windows will resurrect the segmented architecture that led
to this problem in the first place. Note also that the mangled names of
exported symbols are different from non-exported ones, so __declspec(dllimport)
is required in order to link to code within a dll).</p>
<p>In order to support the building of shared libraries on MS Windows your code
will have to prefix all the symbols that your library exports with a macro
(lets call it BOOST_WHATEVER_DECL) that your library will define to expand to
either __declspec(dllexport) or __declspec(dllimport) or nothing, depending
upon how your library is being built or used. Typical usage would look like
this:</p>
<pre>#ifndef BOOST_WHATEVER_HPP
#define BOOST_WHATEVER_HPP
#include &lt;boost/config.hpp&gt;
#ifdef BOOST_HAS_DECLSPEC // defined in config system
// we need to import/export our code only if the user has specifically
// asked for it by defining either BOOST_ALL_DYN_LINK if they want all boost
// libraries to be dynamically linked, or BOOST_WHATEVER_DYN_LINK
// if they want just this one to be dynamically liked:
#if defined(BOOST_ALL_DYN_LINK) || defined(BOOST_WHATEVER_DYN_LINK)
// export if this is our own source, otherwise import:
#ifdef BOOST_WHATEVER_SOURCE
# define BOOST_WHATEVER_DECL __declspec(dllexport)
#else
# define BOOST_WHATEVER_DECL __declspec(dllimport)
#endif // BOOST_WHATEVER_SOURCE
#endif // DYN_LINK
#endif // BOOST_HAS_DECLSPEC
//
// if BOOST_WHATEVER_DECL isn't defined yet define it now:
#ifndef BOOST_WHATEVER_DECL
#define BOOST_WHATEVER_DECL
#endif
//
// this header declares one class, and one function by way of examples:
//
class BOOST_WHATEVER_DECL whatever
{
// details.
};
BOOST_WHATEVER_DECL whatever get_whatever();
#endif
</pre>
And then in the source code for this library one would use:
<pre>
//
// define BOOST_WHATEVER SOURCE so that our library's
// setup code knows that we are building the library (possibly exporting code),
// rather than using it (possibly importing code):
//
#define BOOST_WHATEVER_SOURCE
#include &lt;boost/whatever.hpp&gt;
// class members don't need any further annotation:
whatever::whatever() { }
// but functions do:
BOOST_WHATEVER_DECL whatever get_whatever()
{
return whatever();
}
</pre>
<H4>Importing/exporting dependencies</H4>
<P>As well as exporting your main classes and functions (those that are actually
documented), Microsoft Visual C++ will warn loudly and often if you try to
import/export a class whose dependencies are not also exported. Dependencies
include: any base classes, any user defined types used as data members, plus
all of the dependencies of your dependencies and so on. This causes particular
problems when a dependency is a template class, because although it is
technically possible to export these, it is not at all easy, especially if the
template itself has dependencies which are implementation-specific details. In
most cases it's probably better to simply suppress the warnings using:</P>
<PRE>#ifdef BOOST_MSVC
# pragma warning(push)
# pragma warning(disable : 4251 4231 4660)
#endif
// code here
#ifdef BOOST_MSVC
#pragma warning(pop)
#endif
</PRE>
<p>This is safe provided that there are no dependencies that are (template)
classes with non-constant static data members, these really do need exporting,
otherwise there will be multiple copies of the static data members in the
program, and that's really really bad.
</p>
<p>Historical note: on 16-bit Windows you really did have to export all
dependencies or the code wouldn't work, however since the latest Visual Studio
.NET supports the import/export of individual member functions, it's a
reasonably safe bet that Windows compilers won't do anything nasty - like
changing the class's ABI - when importing/exporting a class.</p>
<h4>Rationale:</h4>
<p><EM>Why bother - doesn't the import/export mechanism take up more code that the
classes themselves?</EM></p>
<P>A good point, and probably true, however there are some circumstances where
library code must be placed in a shared library - for example when the
application consists of multiple dll's as well as the executable, and more than
one those dll's link to the same Boost library - in this case if the library
isn't dynamically linked and it contains any global data (even if that data is
private to the internals of the library) then really bad things can happen -
even without global data, we will still get a code bloating effect.
Incidentally, for larger applications, splitting the application into multiple
dll's can be highly advantageous - by using Microsoft's "delay load" feature
the application will load only those parts it really needs at any one time,
giving the impression of a much more responsive and faster-loading application.</P>
<p><EM>Why static linking by default? </EM>
</p>
<P>In the worked example above, the code assumes that the library will be
statically linked unless the user asks otherwise. Most users seem to prefer
this (there are no separate dll's to distribute, and the overall distribution
size is often significantly smaller this way as well: i.e. you pay for what you
use and no more), but this is a subjective call, and some libraries may even
only be available in dynamic versions (Boost.threads for example).</P>
<h3><A name="auto-link"></A>Enabling Automatic Library Selection and Linking</h3>
<p>Many Windows compilers ship with multiple runtime libraries - for example
Microsoft Visual Studio .NET comes with 6 versions of the C and C++ runtime. It
is essential that the Boost library that the user links to is built against the
same C runtime as the program is built against. If that is not the case, then
the user will experience linker errors at best, and runtime crashes at worst.
The Boost build system manages this by providing different build variants, each
of which is build against a different runtime, and gets a slightly different
mangled name depending upon which runtime it is built against. For example the
regex libraries get named as follows when built with Visual Studio .NET 2003:</p>
<pre>boost_regex-vc71-mt-1_31.lib
boost_regex-vc71-mt-gd-1_31.lib
libboost_regex-vc71-mt-1_31.lib
libboost_regex-vc71-mt-gd-1_31.lib
libboost_regex-vc71-mt-s-1_31.lib
libboost_regex-vc71-mt-sgd-1_31.lib
libboost_regex-vc71-s-1_31.lib
libboost_regex-vc71-sgd-1_31.lib
</pre>
<p>The difficulty now is selecting which of these the user should link his or her
code to.</p>
<p>In contrast, most Unix compilers typically only have one runtime (or sometimes
two if there is a separate thread safe option). For these systems the only
choice in selecting the right library variant is whether they want debugging
info, and possibly thread safety.
</p>
<p>Historically Microsoft Windows compilers have managed this issue by providing a
#pragma option that allows the header for a library to automatically select the
library to link to. This makes everything automatic and extremely easy for the
end user: as soon as they include a header file that has separate source code,
the name of the right library build variant gets embedded in the object file,
and as long as that library is in the linker search path, it will get pulled in
by the linker without any user intervention.</p>
<p>This feature can be enabled for Boost libraries by including the header
<boostconfigauto_link.hpp>after defining BOOST_LIB_NAME and BOOST_DYN_LINK as
required, as usual the feature can also be disabled by the user, if they define
either BOOST_ALL_NO_LIB or BOOST_WHATEVER_NO_LIB:</p>
<pre>//
// Automatically link to the correct build variant where possible.
//
#if !defined(BOOST_ALL_NO_LIB) &amp;&amp; !defined(BOOST_WHATEVER_NO_LIB)
//
// Set the name of our library, this will get undef'ed by auto_link.hpp
// once it's done with it:
//
#define BOOST_LIB_NAME boost_whatever
//
// If we're importing code from a dll, then tell auto_link.hpp about it:
//
#if defined(BOOST_ALL_DYN_LINK) || defined(BOOST_WHATEVER_DYN_LINK)
# define BOOST_DYN_LINK
#endif
//
// And include the header that does the work:
//
#include &lt;boost/config/auto_link.hpp&gt;
#endif // auto-linking disabled
</pre>
<P></P>
<P>If for any reason you need to debug this feature, the header
&lt;boost/config/auto_link.hpp&gt; will output some helpful diagnostic messages
if you first define BOOST_LIB_DIAGNOSTIC.</P>
<H2><A name="build_changes"></A>Changes Affecting the Build System</H2>
<H3><a name='build"'></a><A name="jamfile"></A>Creating the library Jamfile</H3>
<P>The Jamfile for building library "whatever" typically lives in
boost-root/libs/whatever/build, start by defining the project root for the
Jamfile:</P>
<PRE>subproject libs/whatever/build ; </PRE>
<P>Then add the static library build target (if supported):</P>
<PRE>lib boost_whatever
:
# list all the sources for this library:
../src/whatever.cpp
:
# all build requirements go here.
# the common names rule ensures that the library will
# be named according to the rules used by the install
# and auto-link features:
[ common-names ]
# set include path for Boost headers:
<sysinclude>$(BOOST_ROOT)
:
# list default build variants here
debug release
; </PRE>
<P>Then add the dll build target (if supported).&nbsp;&nbsp;In this case the build
requirements section get an extra define: so that our sources know to export
their own symbols (and import those from any other boost libs on which we may
be dependent).&nbsp; We also restict shared library builds to dynamic-runtime
build variants, if we don't do this then dll's linked against static runtimes
are unlikely to function correctly (the dll will have a separate runtime from
the executable using it, this generally causing problems with new and
delete,&nbsp;as well as exception handling runtimes).</P>
<PRE>dll boost_whatever
:
# list all the sources for this library:
../src/whatever.cpp
:
# all build requirements go here.
# the common names rule ensures that the library will
# be named according to the rules used by the install
# and auto-link features:
[ common-names ]
# tell our source that we're building (and maybe using) dll's:
&lt;define&gt;BOOST_ALL_DYN_LINK=1
# only build this for dynamic runtimes:
&lt;runtime-link&gt;dynamic
# set include path for Boost headers:
<sysinclude>$(BOOST_ROOT)
:
# list default build variants here
debug release
; </PRE>
<P>Now add an install target so that Boost.Install can find this library to
install:</P>
<pre>install whatever lib
: <dll>boost_whatever <lib>boost_whatever
;
</pre>
<P>Finally add a stage target that will copy the built libraries to a common
sub-directory (boost-root/stage/lib):</P>
<PRE>stage stage/lib : <lib>boost_whatever <dll>boost_whatever
:
# copy to a path rooted at BOOST_ROOT:
<locate>$(BOOST_ROOT)
# make sure the names of the libraries are correctly named:
[ common-names ]
# add this target to the "stage" and "all" psuedo-targets:
<target>stage
<target>all
:
debug release
;
</PRE>
<H3><A name="testing"></A>Testing Auto-linking</H3>
<P>Testing the auto-link feature&nbsp;reasonable straightforward using
the&nbsp;Boost.build system: we need to build the "whatever" library's test
files without explicitly specifying the library to link to in the Jamfile, for
example:</P>
<PRE>
subproject libs/whatever/test/auto-link-test ;
# bring in the rules for testing
import testing ;
# start with a static linking version:
run
# sources
../whatever_test.cpp
:
: # input files
: # requirements
&lt;library-path&gt;../../../../stage/lib
&lt;define&gt;BOOST_LIB_DIAGNOSTIC=1
: # program name
whatever_test
;
# and then a dll linking version:
run
# sources
../whatever_test.cpp
:
: # input files
: # requirements
&lt;library-path&gt;../../../../stage/lib
&lt;define&gt;BOOST_LIB_DIAGNOSTIC=1
&lt;define&gt;BOOST_ALL_DYN_LINK=1
&lt;runtime-link&gt;dynamic
: # program name
whatever_test_dll
;
</PRE>
<P>Please note however that this Jamfile will only build with compilers that do
actually support auto-linking, so it should not be added to the regular
regression tests.&nbsp; The Jamfile should also be built for all possible build
variants, for the Microsoft / Borland compilers that means doing a:</P>
<PRE>bjam -sBUILD="release debug &lt;threading&gt;multi/single &lt;runtime-link&gt;static/dynamic" test
</PRE>
<HR>
<p><A name="copyright"></A>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
21 Nov 2003
<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
<p><i>© Copyright John Maddock&nbsp;1998-
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2003<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
<P><I>Use, modification and distribution are subject to the Boost Software License,
Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>).</I></P>
<P><EM>The use of code snippets from this article does not require the reproduction
of this copyright declaration; if you wish to provide attribution then please
provide a link to this article.</EM></P>
</body>
</html>