Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r59675 - website/public_html/beta/development
From: daniel_james_at_[hidden]
Date: 2010-02-14 07:28:04

Next message: daniel_james_at_[hidden]: "[Boost-commit] svn:boost r59676 - trunk/libs/integer/doc"
Previous message: afojgo_at_[hidden]: "[Boost-commit] svn:boost r59674 - sandbox/itl/libs/itl/prj_home"

Author: danieljames
Date: 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
New Revision: 59675
URL: http://svn.boost.org/trac/boost/changeset/59675

Log:
Move the guidelines over to the wiki.
Removed:
   website/public_html/beta/development/borland_cpp.html
   website/public_html/beta/development/header.html
   website/public_html/beta/development/int_const_guidelines.html
   website/public_html/beta/development/requirements.html
   website/public_html/beta/development/reuse.html
   website/public_html/beta/development/separate_compilation.html
   website/public_html/beta/development/test.html
Text files modified:
   website/public_html/beta/development/.htaccess | 15 ++++++++-------
   1 files changed, 8 insertions(+), 7 deletions(-)

Modified: website/public_html/beta/development/.htaccess
==============================================================================
--- website/public_html/beta/development/.htaccess (original)
+++ website/public_html/beta/development/.htaccess 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
@@ -15,3 +15,11 @@
RewriteRule ^webcheck$ webcheck/index.html [R]
RewriteRule ^webcheck/$ webcheck/index.html [R]
RewriteRule ^webcheck/(.*)$ webcheck_results.php/$1 [L]
+
+RewriteRule ^borland_cpp\.html$ https://svn.boost.org/trac/boost/wiki/Guidelines/Borland [R]
+RewriteRule ^header\.html$ https://svn.boost.org/trac/boost/wiki/Guidelines/Header [R]
+RewriteRule ^int_const_guidelines\.html$ https://svn.boost.org/trac/boost/wiki/Guidelines/IntegralConstants [R]
+RewriteRule ^requirements\.html$ https://svn.boost.org/trac/boost/wiki/Guidelines/Requirements [R]
+RewriteRule ^reuse\.html$ https://svn.boost.org/trac/boost/wiki/Guidelines/Reuse [R]
+RewriteRule ^separate_compilation\.html$ https://svn.boost.org/trac/boost/wiki/Guidelines/Separate [R]
+RewriteRule ^test\.html$ https://svn.boost.org/trac/boost/wiki/Guidelines/Test [R]

Deleted: website/public_html/beta/development/borland_cpp.html
==============================================================================
--- website/public_html/beta/development/borland_cpp.html 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
+++ (empty file)
@@ -1,426 +0,0 @@
-<!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>Portability Hints: Borland C++ 5.5.1</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <link rel="icon" href="/favicon.ico" type="image/ico" />
- <link rel="stylesheet" type="text/css" href=
- "/style/section-development.css" />
- 
-</head>
-
-<body>
- <div id="heading">
- 
- </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>Portability Hints: Borland C++ 5.5.1</h1>
- </div>
-
- <div class="section-body">
- <p>It is a general aim for boost libraries to be <a href=
- "/development/requirements.html#Portability">portable</a>. The
- primary means for achieving this goal is to adhere to ISO
- Standard C++. However, ISO C++ is a broad and complex standard
- and most compilers are not fully conformant to ISO C++ yet. In
- order to achieve portability in the light of this restriction,
- it seems advisable to get acquainted with those language
- features that some compilers do not fully implement yet.</p>
-
- <p>This page gives portability hints on some language features
- of the Borland C++ version 5.5.1 compiler. Furthermore, the
- appendix presents additional problems with Borland C++ version
- 5.5. Borland C++ 5.5.1 is a freely available command-line
- compiler for Win32 available at <a href=
- "http://www.borland.com/">http://www.borland.com/>.</p>
-
- <p>Each entry in the following list describes a particular
- issue, complete with sample source code to demonstrate the
- effect. Most sample code herein has been verified to compile
- with gcc 2.95.2 and Comeau C++ 4.2.44.</p>
-
- <h2>Preprocessor symbol</h2>
-
- <p>The preprocessor symbol <code>__BORLANDC__</code> is defined
- for all Borland C++ compilers. Its value is the version number
- of the compiler interpreted as a hexadecimal number. The
- following table lists some known values.</p>
-
- <table border="1" summary="">
- <tr>
- <th>Compiler</th>
-
- <th><code>__BORLANDC__</code> value</th>
- </tr>
-
- <tr>
- <td>Borland C++ Builder 4</td>
-
- <td>0x0540</td>
- </tr>
-
- <tr>
- <td>Borland C++ Builder 5</td>
-
- <td>0x0550</td>
- </tr>
-
- <tr>
- <td>Borland C++ 5.5</td>
-
- <td>0x0550</td>
- </tr>
-
- <tr>
- <td>Borland C++ 5.5.1</td>
-
- <td>0x0551</td>
- </tr>
-
- <tr>
- <td>Borland C++ Builder 6</td>
-
- <td>0x0560</td>
- </tr>
- </table>
-
- <h2>Core Language</h2>
-
- <h3>[using-directive] Mixing <code>using</code>-declarations
- and <code>using</code>-directives</h3>
-
- <p>Mixing <code>using</code>-directives (which refer to whole
- namespaces) and namespace-level <code>using</code>-declarations
- (which refer to individual identifiers within foreign
- namespaces) causes ambiguities where there are none. The
- following code fragment illustrates this:</p>
- <pre>
-namespace N {
- int x();
-}
-
-using N::x;
-using namespace N;
-
-int main()
-{
- &x; // Ambiguous overload
-}
-</pre>
-
- <h3>[using template] <code>using</code>-declarations for class
- templates</h3>
-
- <p>Identifiers for class templates can be used as arguments to
- <code>using</code>-declarations as any other identifier.
- However, the following code fails to compile with Borland
- C++:</p>
- <pre>
-template<class T>
-class X { };
-
-namespace N
-{
- // "cannot use template 'X<T>' without specifying specialization parameters"
- using ::X;
-};
-</pre>
-
- <h3>[template const arg] Deduction of constant arguments to
- function templates</h3>
-
- <p>Template function type deduction should omit top-level
- constness. However, this code fragment instantiates "f<const
- int>(int)":</p>
- <pre>
-template<class T>
-void f(T x)
-{
- x = 1; // works
- (void) &x;
- T y = 17;
- y = 20; // "Cannot modify a const object in function f<const int>(int)"
- (void) &y;
-}
-
-int main()
-{
- const int i = 17;
- f(i);
-}
-</pre>
-
- <h3>[function address] Resolving addresses of overloaded
- functions</h3>
-
- <p>Addresses of overloaded functions are not in all contexts
- properly resolved (std:13.4 [over.over]); here is a small
- example:</p>
- <pre>
-template<class Arg>
-void f( void(*g)(Arg) );
-
-void h(int);
-void h(double);
-
-template<class T>
-void h2(T);
-
-int main()
-{
- void (*p)(int) = h; // this works (std:13.4-1.1)
- void (*p2)(unsigned char) = h2; // this works as well (std:13.4-1.1)
- f<int>(h2); // this also works (std:13.4-1.3)
-
- // "Cannot generate template specialization from h(int)",
- // "Could not find a match for f<Arg>(void (*)(int))"
- f<double>(h); // should work (std:13.4-1.3)
-
- f( (void(*)(double))h); // C-style cast works (std:13.4-1.6 with 5.4)
-
- // "Overloaded 'h' ambiguous in this context"
- f(static_cast<void(*)(double)>(h)); // should work (std:13.4-1.6 with 5.2.9)
-}
-</pre>
-
- <p><strong>Workaround:</strong> Always use C-style casts when
- determining addresses of (potentially) overloaded
- functions.</p>
-
- <h3>[string conversion] Converting <code>const char *</code> to
- <code>std::string</code></h3>
-
- <p>Implicitly converting <code>const char *</code> parameters
- to <code>std::string</code> arguments fails if template
- functions are explicitly instantiated (it works in the usual
- cases, though):</p>
- <pre>
-#include <string>
-
-template<class T>
-void f(const std::string & s)
-{}
-
-int main()
-{
- f<double>("hello"); // "Could not find a match for f<T>(char *)"
-}
-
-</pre>
-
- <p><strong>Workaround:</strong> Avoid explicit template
- function instantiations (they have significant problems with
- Microsoft Visual C++) and pass default-constructed unused dummy
- arguments with the appropriate type. Alternatively, if you wish
- to keep to the explicit instantiation, you could use an
- explicit conversion to <code>std::string</code> or declare the
- template function as taking a <code>const char *</code>
- parameter.</p>
-
- <h3>[template value defaults] Dependent default arguments for
- template value parameters</h3>
-
- <p>Template value parameters which default to an expression
- dependent on previous template parameters don't work:</p>
- <pre>
-template<class T>
-struct A
-{
- static const bool value = true;
-};
-
-// "Templates must be classes or functions", "Declaration syntax error"
-template<class T, bool v = A<T>::value>
-struct B {};
-
-int main()
-{
- B<int> x;
-}
-
-</pre>
-
- <p><strong>Workaround:</strong> If the relevant non-type
- template parameter is an implementation detail, use inheritance
- and a fully qualified identifier (for example,
- ::N::A<T>::value).</p>
-
- <h3>[function partial ordering] Partial ordering of function
- templates</h3>
-
- <p>Partial ordering of function templates, as described in
- std:14.5.5.2 [temp.func.order], does not work:</p>
- <pre>
-#include <iostream>
-
-template<class T> struct A {};
-
-template<class T1>
-void f(const A<T1> &)
-{
- std::cout << "f(const A<T1>&)\n";
-}
-
-template<class T>
-void f(T)
-{
- std::cout << "f(T)\n";
-}
-
-int main()
-{
- A<double> a;
- f(a); // output: f(T) (wrong)
- f(1); // output: f(T) (correct)
-}
-</pre>
-
- <p><strong>Workaround:</strong> Declare all such functions
- uniformly as either taking a value or a reference
- parameter.</p>
-
- <h3>[instantiate memfun ptr] Instantiation with member function
- pointer</h3>
-
- <p>When directly instantiating a template with some member
- function pointer, which is itself dependent on some template
- parameter, the compiler cannot cope:</p>
- <pre>
-template<class U> class C { };
-template<class T>
-class A
-{
- static const int v = C<void (T::*)()>::value;
-};
-</pre>
-
- <p><strong>Workaround:</strong> Use an intermediate
- <code>typedef</code>:</p>
- <pre>
-template<class U> class C { };
-template<class T>
-class A
-{
- typedef void (T::*my_type)();
- static const int v = C<my_type>::value;
-};
-</pre>
-
- <p>(Extracted from e-mail exchange of David Abrahams, Fernando
- Cacciola, and Peter Dimov; not actually tested.)</p>
-
- <h2>Library</h2>
-
- <h3>[cmath.abs] Function <code>double std::abs(double)</code>
- missing</h3>
-
- <p>The function <code>double std::abs(double)</code> should be
- defined (std:26.5-5 [lib.c.math]), but it is not:</p>
- <pre>
-#include <cmath>
-
-int main()
-{
- double (*p)(double) = std::abs; // error
-}
-</pre>
-
- <p>Note that <code>int std::abs(int)</code> will be used
- without warning if you write <code>std::abs(5.1)</code>.</p>
-
- <p>Similar remarks apply to seemingly all of the other standard
- math functions, where Borland C++ fails to provide
- <code>float</code> and <code>long double</code> overloads.</p>
-
- <p><strong>Workaround:</strong> Use <code>std::fabs</code>
- instead if type genericity is not required.</p>
-
- <h2>Appendix: Additional issues with Borland C++ version
- 5.5</h2>
-
- <p>These issues are documented mainly for historic reasons. If
- you are still using Borland C++ version 5.5, you are strongly
- encouraged to obtain an upgrade to version 5.5.1, which fixes
- the issues described in this section.</p>
-
- <h3>[inline friend] Inline friend functions in template
- classes</h3>
-
- <p>If a friend function of some class has not been declared
- before the friend function declaration, the function is
- declared at the namespace scope surrounding the class
- definition. Together with class templates and inline
- definitions of friend functions, the code in the following
- fragment should declare (and define) a non-template function
- "bool N::f(int,int)", which is a friend of class
- N::A<int>. However, Borland C++ v5.5 expects the function
- f to be declared beforehand:</p>
- <pre>
-namespace N {
-template<class T>
-class A
-{
- // "f is not a member of 'N' in function main()"
- friend bool f(T x, T y) { return x < y; }
-};
-}
-
-int main()
-{
- N::A<int> a;
-}
-</pre>
-
- <p>This technique is extensively used in boost/operators.hpp.
- Giving in to the wish of the compiler doesn't work in this
- case, because then the "instantiate one template, get lots of
- helper functions at namespace scope" approach doesn't work
- anymore. Defining BOOST_NO_OPERATORS_IN_NAMESPACE (a define
- BOOST_NO_INLINE_FRIENDS_IN_CLASS_TEMPLATES would match this
- case better) works around this problem and leads to another
- one, see [using-template].</p>
- </div>
- </div>
- </div>
- </div>
-
- <div id="sidebar">
- 
- 
- </div>
-
- <div class="clear"></div>
- </div>
- </div>
-
- <div id="footer">
- <div id="footer-left">
- <div id="revised">
- <p>Revised $Date: 2007-10-22 22:55:52 +0100 (Mon, 22 Oct 2007) $</p>
- </div>
-
- <div id="copyright">
- <p>Copyright © 2000-2002 <a href=
- "/users/people/jens_maurer.html">Jens Maurer</a></p>
- </div>
- </div>
-
- <div id="footer-right">
- 
- </div>
-
- <div class="clear"></div>
- </div>
-</body>
-</html>

Deleted: website/public_html/beta/development/header.html
==============================================================================
--- website/public_html/beta/development/header.html 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
+++ (empty file)
@@ -1,150 +0,0 @@
-<!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 Header policy</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <link rel="icon" href="/favicon.ico" type="image/ico" />
- <link rel="stylesheet" type="text/css" href=
- "/style/section-development.css" />
- 
-</head>
-
-<body>
- <div id="heading">
- 
- </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 Header policy</h1>
- </div>
-
- <div class="section-body">
- <p>Header files are the place where a library comes into
- contact with user code and other libraries. To co-exist
- peacefully and productively, headers must be "good
- neighbors".</p>
-
- <p>Here are the standards for boost headers. Many of these are
- also reasonable guidelines for general use.</p>
-
- <ul>
- <li>Header filenames should have a .hpp (lowercase)
- extension.</li>
-
- <li>Unless multiple inclusion is intended, wrap the header in
- #ifndef guards. Use a naming convention that minimizes the
- chance of clashes with macro names from other's code. The
- sample header uses the Boost
- convention of all uppercase letters, with the header name
- prefixed by the namespace name, and suffixed with HPP,
- separated by underscores.</li>
-
- <li>Wrap the header contents in a namespace to prevent global
- namespace pollution. The namespace approach to pollution
- control is strongly preferred to older approaches such as
- adding funny prefixes to global names. Libraries which are
- designed to work well with other Boost libraries should be
- placed in namespace <tt>boost</tt>.</li>
-
- <li>Make sure that a translation unit consisting of just the
- contents of the header file will compile successfully.</li>
-
- <li>Place the header file in a sub-directory to prevent
- conflict with identically named header files in other
- libraries. The parent directory is added to the compiler's
- include search path. Then both your code and user code
- specifies the sub-directory in <tt>#include</tt> directives.
- Thus the header sample header
- would be included by <tt>#include
- <boost/furball.hpp></tt></li>
-
- <li>The preferred ordering for class definitions is public
- members, protected members, and finally private members.</li>
-
- <li>Include the boost/config.hpp <a href=
- "/doc/libs/release/libs/config/config.htm">configuration
- header</a> if there is a need to deal with compiler or
- platform configuration issues.</li>
- </ul>
-
- <h2><a name="SampleHeader" id="SampleHeader"></a>Sample
- Header</h2>
- <pre>
-// Boost general library furball.hpp header file ---------------------------//
-
- <<i> Copyright and license notice</i>, as indicated in the <a href=
-"/users/license.html">license page</a> >
-
-// See http://www.boost.org/ for latest version.
-
-#ifndef BOOST_FURBALL_HPP
-#define BOOST_FURBALL_HPP
-
-namespace boost {
-
-// Furball class declaration -----------------------------------------------//
-
- class furball
- {
- public:
- void throw_up();
- private:
- int whatever;
- }; // furball
-
-} // namespace
-
-#endif // include guard
-</pre>
-
- <h2>Coding Style</h2>
-
- <p>The alert reader will have noticed that the <a href=
- "#SampleHeader">sample header</a> employs a certain coding
- style for indentation, positioning braces, commenting ending
- braces, and similar formatting issues. These stylistic issues
- are viewed as personal preferences and are not part of the
- Boost Header Policy.</p>
- </div>
- </div>
- </div>
- </div>
-
- <div id="sidebar">
- 
- 
- </div>
-
- <div class="clear"></div>
- </div>
- </div>
-
- <div id="footer">
- <div id="footer-left">
- <div id="revised">
- <p>Revised $Date: 2007-10-22 22:55:52 +0100 (Mon, 22 Oct 2007) $</p>
- </div>
-
- <div id="copyright">
- <p>Copyright Beman Dawes 1998.</p>
- </div>
- </div>
-
- <div id="footer-right">
- 
- </div>
-
- <div class="clear"></div>
- </div>
-</body>
-</html>

Deleted: website/public_html/beta/development/int_const_guidelines.html
==============================================================================
--- website/public_html/beta/development/int_const_guidelines.html 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
+++ (empty file)
@@ -1,407 +0,0 @@
-<!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>Coding Guidelines for Integral Constant Expressions</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <link rel="icon" href="/favicon.ico" type="image/ico" />
- <link rel="stylesheet" type="text/css" href=
- "/style/section-development.css" />
- 
-</head>
-
-<body>
- <div id="heading">
- 
- </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>Coding Guidelines for Integral Constant Expressions</h1>
- </div>
-
- <div class="section-body">
- <p>Integral Constant Expressions are used in many places in
- C++; as array bounds, as bit-field lengths, as enumerator
- initialisers, and as arguments to non-type template parameters.
- However many compilers have problems handling integral constant
- expressions; as a result of this, programming using non-type
- template parameters in particular can be fraught with
- difficulty, often leading to the incorrect assumption that
- non-type template parameters are unsupported by a particular
- compiler. This short article is designed to provide a set of
- guidelines and workarounds that, if followed, will allow
- integral constant expressions to be used in a manner portable
- to all the compilers currently supported by boost. Although
- this article is mainly targeted at boost library authors, it
- may also be useful for users who want to understand why boost
- code is written in a particular way, or who want to write
- portable code themselves.</p>
-
- <h2>What is an Integral Constant Expression?</h2>
-
- <p>Integral constant expressions are described in section 5.19
- of the standard, and are sometimes referred to as "compile time
- constants". An integral constant expression can be one of the
- following:</p>
-
- <ol>
- <li>A literal integral value, for example <code>0u</code> or
- <code>3L</code>.</li>
-
- <li>An enumerator value.</li>
-
- <li>Global integral constants, for example:
- <pre>
-const int my_INTEGRAL_CONSTANT = 3;
-</pre>
- </li>
-
- <li>Static member constants, for example:
- <pre>
-struct myclass
-{ static const int value = 0; };
-</pre>
- </li>
-
- <li>Member enumerator values, for example:
- <pre>
-struct myclass
-{ enum{ value = 0 }; };
-</pre>
- </li>
-
- <li>Non-type template parameters of integral or enumerator
- type.</li>
-
- <li>The result of a <code>sizeof</code> expression, for
- example:
- <pre>
-sizeof(foo(a, b, c))
-</pre>
- </li>
-
- <li>The result of a <code>static_cast</code>, where the
- target type is an integral or enumerator type, and the
- argument is either another integral constant expression, or a
- floating-point literal.</li>
-
- <li>The result of applying a binary operator to two integral
- constant expressions:
- <pre>
-INTEGRAL_CONSTANT1 op INTEGRAL_CONSTANT2
-</pre>provided that the operator is not an assignment operator, or comma
-operator.
- </li>
-
- <li>The result of applying a unary operator to an integral
- constant expression:
- <pre>
-op INTEGRAL_CONSTANT1
-</pre>provided that the operator is not the increment or decrement operator.
- </li>
- </ol>
-
- <h2>Coding Guidelines</h2>
-
- <p>The following guidelines are declared in no particular order
- (in other words you need to obey all of them - sorry!), and may
- also be incomplete, more guidelines may be added as compilers
- change and/or more problems are encountered.</p>
-
- <h3>When declaring constants that are class members always use
- the macro <code>BOOST_STATIC_CONSTANT.</code></h3>
- <pre>
-template <class T>
-struct myclass
-{
- BOOST_STATIC_CONSTANT(int, value = sizeof(T));
-};
-</pre>
-
- <p>Rationale: not all compilers support inline initialisation
- of member constants, others treat member enumerators in strange
- ways (they're not always treated as integral constant
- expressions). The BOOST_STATIC_CONSTANT macro uses the most
- appropriate method for the compiler in question.</p>
-
- <h3>Don't declare integral constant expressions whose type is
- wider than int.</h3>
-
- <p>Rationale: while in theory all integral types are usable in
- integral constant expressions, in practice many compilers limit
- integral constant expressions to types no wider than
- <code>int</code>.</p>
-
- <h3>Don't use logical operators in integral constant
- expressions; use template meta-programming instead.</h3>
-
- <p>The header <code><boost/type_traits/ice.hpp></code>
- contains a number of workaround templates, that fulfil the role
- of logical operators, for example instead of:</p>
- <pre>
-INTEGRAL_CONSTANT1 || INTEGRAL_CONSTANT2
-</pre>
-
- <p>Use:</p>
- <pre>
-::boost::type_traits::ice_or<INTEGRAL_CONSTANT1,INTEGRAL_CONSTANT2>::value
-</pre>
-
- <p>Rationale: A number of compilers (particularly the Borland
- and Microsoft compilers), tend to not to recognise integral
- constant expressions involving logical operators as genuine
- integral constant expressions. The problem generally only shows
- up when the integral constant expression is nested deep inside
- template code, and is hard to reproduce and diagnose.</p>
-
- <h3>Don't use any operators in an integral constant expression
- used as a non-type template parameter</h3>
-
- <p>Rather than:</p>
- <pre>
-typedef myclass<INTEGRAL_CONSTANT1 ==
- INTEGRAL_CONSTANT2> mytypedef;
-</pre>
-
- <p>Use:</p>
- <pre>
-typedef myclass< some_symbol>
- mytypedef;
-</pre>
-
- <p>Where <code>some_symbol</code> is the symbolic name of a an
- integral constant expression whose value is
- <code>(INTEGRAL_CONSTANT1 == INTEGRAL_CONSTANT2).</code></p>
-
- <p>Rationale: the older EDG based compilers (some of which are
- used in the most recent version of that platform's compiler),
- don't recognise expressions containing operators as non-type
- template parameters, even though such expressions can be used
- as integral constant expressions elsewhere.</p>
-
- <h3>Always use a fully qualified name to refer to an integral
- constant expression.</h3>
-
- <p>For example:</p>
- <pre>
-<code>typedef</code> myclass< ::boost::is_integral<some_type>::value> mytypedef;
-</pre>
-
- <p>Rationale: at least one compiler (Borland's), doesn't
- recognise the name of a constant as an integral constant
- expression unless the name is fully qualified (which is to say
- it starts with <code>::</code>).</p>
-
- <h3>Always leave a space after a '<code><</code>' and before
- '<code>::</code>'</h3>
-
- <p>For example:</p>
- <pre>
-typedef myclass< ::boost::is_integral<some_type>::value> mytypedef;
- ^
- ensure there is space here!
-</pre>
-
- <p>Rationale: <code><:</code> is a legal digraph in it's own
- right, so <code><::</code> is interpreted as the same as
- <code>[:</code>.</p>
-
- <h3>Don't use local names as integral constant expressions</h3>
-
- <p>Example:</p>
- <pre>
-template <class T>
-struct foobar
-{
- BOOST_STATIC_CONSTANT(int, temp = computed_value);
- typedef myclass<temp> mytypedef; // error
-};
-</pre>
-
- <p>Rationale: At least one compiler (Borland's) doesn't accept
- this.</p>
-
- <p>Although it is possible to fix this by using:</p>
- <pre>
-template <class T>
-struct foobar
-{
- BOOST_STATIC_CONSTANT(int, temp = computed_value);
- typedef foobar self_type;
- typedef myclass<(self_type::temp)> mytypedef; // OK
-};
-</pre>
-
- <p>This breaks at least one other compiler (VC6), it is better
- to move the integral constant expression computation out into a
- separate traits class:</p>
- <pre>
-template <class T>
-struct foobar_helper
-{
- BOOST_STATIC_CONSTANT(int, value = computed_value);
-};
-
-template <class T>
-struct foobar
-{
- typedef myclass< ::foobar_helper<T>::value> mytypedef; // OK
-};
-</pre>
-
- <h3>Don't use dependent default parameters for non-type
- template parameters.</h3>
-
- <p>For example:</p>
- <pre>
-template <class T, int I = ::boost::is_integral<T>::value> // Error can't deduce value of I in some cases.
-struct foobar;
-</pre>
-
- <p>Rationale: this kind of usage fails for Borland C++. Note
- that this is only an issue where the default value is dependent
- upon a previous template parameter, for example the following
- is fine:</p>
- <pre>
-template <class T, int I = 3> // OK, default value is not dependent
-struct foobar;
-</pre>
-
- <h2>Unresolved Issues</h2>
-
- <p>The following issues are either unresolved or have fixes
- that are compiler specific, and/or break one or more of the
- coding guidelines.</p>
-
- <h3>Be careful of numeric_limits</h3>
-
- <p>There are three issues here:</p>
-
- <ol>
- <li>The header <limits> may be absent - it is
- recommended that you never include <limits> directly
- but use <boost/pending/limits.hpp> instead. This header
- includes the "real" <limits> header if it is available,
- otherwise it supplies it's own std::numeric_limits
- definition. Boost also defines the macro BOOST_NO_LIMITS if
- <limits> is absent.</li>
-
- <li>The implementation of std::numeric_limits may be defined
- in such a way that its static-const members may not be usable
- as integral constant expressions. This contradicts the
- standard but seems to be a bug that affects at least two
- standard library vendors; boost defines
- BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS in
- <boost/config.hpp> when this is the case.</li>
-
- <li>There is a strange bug in VC6, where the members of
- std::numeric_limits can be "prematurely evaluated" in
- template code, for example:</li>
- </ol>
- <pre>
-template <class T>
-struct limits_test
-{
- BOOST_STATIC_ASSERT(::std::numeric_limits<T>::is_specialized);
-};
-</pre>
-
- <p>This code fails to compile with VC6 even though no instances
- of the template are ever created; for some bizarre reason
- <code>::std::numeric_limits<T>::is_specialized</code>
- always evaluates to false, irrespective of what the template
- parameter T is. The problem seems to be confined to expressions
- which depend on std::numeric_limts: for example if you replace
- <code>::std::numeric_limits<T>::is_specialized</code>
- with <code>::boost::is_arithmetic<T>::value</code>, then
- everything is fine. The following workaround also works but
- conflicts with the coding guidelines:</p>
- <pre>
-template <class T>
-struct limits_test
-{
- BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits<T>::is_specialized);
- BOOST_STATIC_ASSERT(check);
-};
-</pre>
-
- <p>So it is probably best to resort to something like this:</p>
- <pre>
-template <class T>
-struct limits_test
-{
-#ifdef BOOST_MSVC
- BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits<T>::is_specialized);
- BOOST_STATIC_ASSERT(check);
-#else
- BOOST_STATIC_ASSERT(::std::numeric_limits<T>::is_specialized);
-#endif
-};
-</pre>
-
- <h3>Be careful how you use the sizeof operator</h3>
-
- <p>As far as I can tell, all compilers treat sizeof expressions
- correctly when the argument is the name of a type (or a
- template-id), however problems can occur if:</p>
-
- <ol>
- <li>The argument is the name of a member-variable, or a local
- variable (code may not compile with VC6).</li>
-
- <li>The argument is an expression which involves the creation
- of a temporary (code will not compile with Borland C++).</li>
-
- <li>The argument is an expression involving an overloaded
- function call (code compiles but the result is a garbage
- value with Metroworks C++).</li>
- </ol>
-
- <h3>Don't use boost::is_convertible unless you have to</h3>
-
- <p>Since is_convertible is implemented in terms of the sizeof
- operator, it consistently gives the wrong value when used with
- the Metroworks compiler, and may not compile with the Borland's
- compiler (depending upon the template arguments used).</p>
- </div>
- </div>
- </div>
- </div>
-
- <div id="sidebar">
- 
- 
- </div>
-
- <div class="clear"></div>
- </div>
- </div>
-
- <div id="footer">
- <div id="footer-left">
- <div id="revised">
- <p>Revised $Date: 2007-10-22 22:55:52 +0100 (Mon, 22 Oct 2007) $</p>
- </div>
-
- <div id="copyright">
- <p>Copyright Dr John Maddock 2001.</p>
- </div>
- </div>
-
- <div id="footer-right">
- 
- </div>
-
- <div class="clear"></div>
- </div>
-</body>
-</html>

Deleted: website/public_html/beta/development/requirements.html
==============================================================================
--- website/public_html/beta/development/requirements.html 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
+++ (empty file)
@@ -1,917 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
-<head>
- <title>Boost Library Requirements and Guidelines</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <link rel="icon" href="/favicon.ico" type="image/ico" />
- <link rel="stylesheet" type="text/css" href=
- "../style/section-development.css" />
- 
-</head>
-
-<body>
- <div id="heading">
- 
- </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>Introduction</li>
-
- <li>
- Requirements
-
- <ul>
- <li>License requirements</li>
-
- <li><a href="#Portability">Portability
- requirements</a></li>
-
- <li>Ownership</li>
- </ul>
- </li>
-
- <li>
- Guidelines
-
- <ul>
- <li><a href="#Design_and_Programming">Design and
- programming</a></li>
-
- <li><a href="#Directory_structure">Directory structure
- and filenames</a></li>
-
- <li><a href="#Naming_consistency">Naming
- consistency</a></li>
-
- <li>Documentation</li>
- </ul>
- </li>
-
- <li>
- Rationale
-
- <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>Tabs rationale</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 meets these requirements:</p>
-
- <ul>
- <li>The license must meet the <a href="#License">license
- requirements</a> below. Restricted licenses like the GPL and
- LGPL are not acceptable.</li>
-
- <li>The copyright ownership 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> below.</li>
-
- <li>The library must come reasonably close to meeting the
- Guidelines below.
-
- <ul>
- <li><a href="#Design_and_Programming">Design and
- Programming</a></li>
-
- <li><a href="#Directory_structure">Directory
- Structure</a></li>
-
- <li>Documentation</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 Boost Software License. See
- license information. If for
- any reason you do not intend to use the Boost Software License,
- please discuss the issues on the Boost <a href=
- "/community/groups.html#main">developers mailing list</a>
- first.</p>
-
- <p>The license requirements:</p>
-
- <ul>
- <li>Must be simple to read and understand.</li>
-
- <li>Must grant permission without fee to copy, use and modify
- the software for any use (commercial and
- non-commercial).</li>
-
- <li>Must require that the license appear on all copies of the
- software source code.</li>
-
- <li>Must not require that the license appear with executables
- or other binary uses of the library.</li>
-
- <li>Must not require that the source code be available for
- execution or other binary uses of the library.</li>
-
- <li>May restrict the use of the name and description of the
- library to the standard version found on the Boost web
- site.</li>
- </ul>
-
- <h3><a name="Portability" id="Portability"></a>Portability
- requirements</h3>
-
- <ul>
- <li>A library's interface must portable and not restricted to
- a particular compiler or operating system.</li>
-
- <li>A library's implementation must if possible be portable
- and not restricted to a particular compiler or operating
- system. If a portable implementation is not possible,
- non-portable constructions are acceptable if reasonably easy
- to port to other environments, and implementations are
- provided for at least two popular operating systems (such as
- UNIX and Windows).</li>
-
- <li>There is no requirement that a library run on C++
- compilers which do not conform to the ISO standard.</li>
-
- <li>There is no requirement that a library run on any
- particular C++ compiler. Boost contributors often try to
- ensure their libraries work with popular compilers. The
- boost/config.hpp <a href=
- "/doc/libs/release/libs/config/config.htm">configuration
- header</a> is the preferred mechanism for working around
- compiler deficiencies.</li>
- </ul>
-
- <p>Since there is no absolute way to prove portability, many
- boost submissions demonstrate practical portability by
- compiling and executing correctly with two different C++
- compilers, often under different operating systems. Otherwise
- reviewers may disbelieve that porting is in fact practical.</p>
-
- <h3><a name="Ownership" id="Ownership"></a>Ownership</h3>
-
- <p>Are you sure you own the library you are thinking of
- submitting? "How to Copyright Software" by MJ Salone, Nolo
- Press, 1990 says:</p>
-
- <blockquote>
- <p>Doing work on your own time that is very similar to
- programming you do for your employer on company time can
- raise nasty legal problems. In this situation, it's best to
- get a written release from your employer in advance.</p>
- </blockquote>
-
- <p>Place a copyright notice in all the important files you
- submit. Boost won't accept libraries without clear copyright
- information.</p>
-
- <h2><a name="Guidelines" id="Guidelines"></a>Guidelines</h2>
-
- <p>Please use these guidelines as a checklist for preparing the
- content a library submission. Not every guideline applies to
- every library, but a reasonable effort to comply is
- expected.</p>
-
- <h3><a name="Design_and_Programming" id=
- "Design_and_Programming"></a>Design and Programming</h3>
-
- <p>Aim first for clarity and correctness; optimization should
- be only a secondary concern in most Boost libraries.</p>
-
- <p>Aim for ISO Standard C++. Than means making effective use of
- the standard features of the language, and avoiding
- non-standard compiler extensions. It also means using the C++
- Standard Library where applicable.</p>
-
- <p>Headers should be good neighbors. See the <a href=
- "/development/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=
- "/development/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>Read the <a href=
- "/development/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
- Naming conventions rationale):</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="/development/test.html">Test Policies and
- Protocols</a>.</p>
-
- <p>Although some boost members use proportional fonts, tabs,
- and unrestricted line lengths in their own code, boost's widely
- distributed source code should follow more conservative
- guidelines:</p>
-
- <ul>
- <li>Use fixed-width fonts. See <a href="#code_fonts">fonts
- rationale</a>.</li>
-
- <li>Use spaces rather than tabs. See <a href="#Tabs">tabs
- rationale</a>.</li>
-
- <li>Limit line lengths to 80 characters.</li>
- </ul>
-
- <p>End all documentation files (HTML or otherwise) with a
- copyright message and a licensing message. See the <a href=
- "/users/license.html">license information</a> page for the
- preferred form.</p>
-
- <p>Begin all source files (including programs, headers,
- scripts, etc.) with:</p>
-
- <ul>
- <li>A comment line describing the contents of the file.</li>
-
- <li>Comments describing copyright and licensing: again, the
- preferred form is indicated in the <a href=
- "/users/license.html">license information</a> page</li>
-
- <li>Note that developers should not provide a copy of
- <code>LICENSE_1_0.txt</code> with their libraries: Boost
- distributions already include a copy in the Boost root
- directory.</li>
-
- <li>A comment line referencing your library on the Boost web
- site. For example:
- <pre>
-// See http://www.boost.org/libs/foo for library home page.
-</pre>
-
- <p>Where <code>foo</code> is the directory name (see below)
- for the library. As well as aiding users who come across a
- Boost file detached from its documentation, some of Boost's
- automatic tools depend on this comment to identify which
- library header files belong to.</p>
- </li>
- </ul>
-
- <p>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>Directory Structure and
- 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>
-
- <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>
-
- <table summary="Boost standard sub-directory names">
- <caption>
- Boost standard sub-directory names
- </caption>
-
- <thead>
- <tr>
- <th>Sub-directory</th>
-
- <th>Contents</th>
-
- <th>Required</th>
- </tr>
- </thead>
-
- <tbody>
- <tr>
- <td><code>build</code></td>
-
- <td>Library build files such as a Jamfile.</td>
-
- <td>If any build files.</td>
- </tr>
-
- <tr>
- <td><code>doc</code></td>
-
- <td>Documentation (HTML) files.</td>
-
- <td>If several doc files.</td>
- </tr>
-
- <tr>
- <td><code>example</code></td>
-
- <td>Sample program files.</td>
-
- <td>If several sample files.</td>
- </tr>
-
- <tr>
- <td><code>src</code></td>
-
- <td>Source files which must be compiled to build the
- library.</td>
-
- <td>If any source files.</td>
- </tr>
-
- <tr>
- <td><code>test</code></td>
-
- <td>Regression or other test programs or scripts.</td>
-
- <td>If several test files.</td>
- </tr>
- </tbody>
- </table>
-
- <h4><a name="Redirection" id="Redirection"></a>Redirection</h4>
-
- <p>The primary directory should always contain a file named
- index.html (or index.htm). Authors have requested this so that
- they can publish URL's in the form
- <i>http://www.boost.org/libs/lib-name> 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>
- <pre>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
-<head>
- <title>Boost.<var>Name</var> Documentation</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <meta http-equiv="refresh" content="0; URL=doc/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 parent
- <var>boost-root/boost</var>) is given that same name. For
- example, <var>boost-root/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 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
- "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.</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>
-
- <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">
- 
- 
- </div>
-
- <div class="clear"></div>
- </div>
- </div>
-
- <div id="footer">
- <div id="footer-left">
- <div id="revised">
- <p>Revised $Date$</p>
- </div>
-
- <div id="copyright">
- <p>Copyright Beman Dawes, 2003.</p>
- </div>
- </div>
-
- <div id="footer-right">
- 
- </div>
-
- <div class="clear"></div>
- </div>
-</body>
-</html>

Deleted: website/public_html/beta/development/reuse.html
==============================================================================
--- website/public_html/beta/development/reuse.html 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
+++ (empty file)
@@ -1,122 +0,0 @@
-<!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 Reuse</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <link rel="icon" href="/favicon.ico" type="image/ico" />
- <link rel="stylesheet" type="text/css" href=
- "/style/section-development.css" />
- 
-</head>
-
-<body>
- <div id="heading">
- 
- </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 reuse: cost versus benefit trade-offs</h1>
- </div>
-
- <div class="section-body">
- <p>A Boost library <strong>should not</strong> use libraries
- other than Boost or the C++ Standard Library.</p>
-
- <p>A Boost library <strong>should</strong> use other Boost
- Libraries or the C++ Standard Library, but only when the
- benefits outweigh the costs.</p>
-
- <p>The benefits of using components from other libraries may
- include clearer, more understandable code, reduced development
- and maintenance costs, and the assurance which comes from
- reusing well-known and trusted building blocks.</p>
-
- <p>The costs may include undesirable coupling between
- components, and added compilation and runtime costs. If the
- interface to the additional component is complex, using it may
- make code less readable, and thus actually increase development
- and maintenance costs.</p>
-
- <p>Negative effects of coupling become obvious when one library
- uses a second library which uses a third, and so on. The worst
- form of coupling requires the user understand each of the
- coupled libraries. Coupling may also reduce the portability of
- a library - even in case when all used libraries are
- self-sufficient (see example of questionable usage of
- <iostream> library below).</p>
-
- <p><strong>Example where another boost component should
- certainly be used:</strong> boost::noncopyable (in <a href=
- "/doc/libs/release/boost/utility.hpp">boost/utility.hpp</a>)
- has considerable benefits; it simplifies code, improves
- readability, and signals intent. Costs are low as coupling is
- limited; noncopyable itself uses no other classes and its
- header includes only the lightweight headers
- <boost/config.hpp> and <cstddef>. There are no
- runtime costs at all. With costs so low and benefits so high,
- other boost libraries should use boost::noncopyable when the
- need arises except in exceptional circumstances.</p>
-
- <p><strong>Example where a standard library component might
- possibly be used:</strong> Providing diagnostic output as a
- debugging aid can be a nice feature for a library. Yet using
- Standard Library <iostream> can involves a lot of
- additional cost, particularly if <iostream> is unlikely
- to be use elsewhere in the application. In certain GUI or
- embedded applications, coupling to <iostream> would be a
- disqualification. Consider redesign of the boost library in
- question so that the user supplies the diagnostic output
- mechanism.</p>
-
- <p><strong>Example where another boost component should not be
- used:</strong> The boost dir_it library has considerable
- coupling and runtime costs, not to mention portability issues
- for unsupported operating systems. While completely appropriate
- when directory iteration is required, it would not be
- reasonable for another boost library to use dir_it just to
- check that a file is available before opening. C++ Standard
- Library file open functionality does this at lower cost. Don't
- use dir_it just for the sake of using a boost library.</p>
- </div>
- </div>
- </div>
- </div>
-
- <div id="sidebar">
- 
- 
- </div>
-
- <div class="clear"></div>
- </div>
- </div>
-
- <div id="footer">
- <div id="footer-left">
- <div id="revised">
- <p>Revised $Date: 2007-10-22 22:55:52 +0100 (Mon, 22 Oct 2007) $</p>
- </div>
-
- <div id="copyright">
- <p>Copyright Beman Dawes 2000.</p>
- </div>
- </div>
-
- <div id="footer-right">
- 
- </div>
-
- <div class="clear"></div>
- </div>
-</body>
-</html>

Deleted: website/public_html/beta/development/separate_compilation.html
==============================================================================
--- website/public_html/beta/development/separate_compilation.html 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
+++ (empty file)
@@ -1,538 +0,0 @@
-<!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>Guidelines for Authors of Boost Libraries Containing Separate
- Source</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <link rel="icon" href="/favicon.ico" type="image/ico" />
- <link rel="stylesheet" type="text/css" href=
- "/style/section-development.css" />
- 
-</head>
-
-<body>
- <div id="heading">
- 
- </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>Guidelines for Authors of Boost Libraries Containing
- Separate Source</h1>
- </div>
-
- <div class="section-body">
- <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>
-
- <dl class="index">
- <dt><a href="#source_changes">Changes Affecting Source
- Code</a></dt>
-
- <dd>
- <dl class="index">
- <dt><a href="#abi">Preventing Compiler ABI
- Clashes</a></dt>
-
- <dt><a href="#static_or_dynamic">Static or Dymanic
- Libraries</a></dt>
-
- <dt>Supporting Windows Dll's</dt>
-
- <dt><a href="#auto-link">Automatic Library Selection and
- Linking with auto_link.hpp</a></dt>
- </dl>
- </dd>
-
- <dt><a href="#build_changes">Changes Affecting the Build
- System</a></dt>
-
- <dd>
- <dl class="index">
- <dt><a href="#jamfile">Creating the Library
- Jamfile</a></dt>
-
- <dt>Testing Auto-linking</dt>
- </dl>
- </dd>
-
- <dt>Copyright</dt>
- </dl>
-
- <h2><a name="source_changes" id="source_changes"></a>Changes
- Affecting Source Code</h2>
-
- <h3><a name="abi" id="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 in a header like
- this:</p>
- <pre>
-#ifndef BOOST_WHATEVER_HPP
-#define BOOST_WHATEVER_HPP
-
-#include <boost/config.hpp>
-
-// 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>
-
- <p>You can include this code in your library source files as
- well if you want, although you probably shouldn't need to:</p>
-
- <ul>
- <li>If you <em>don't</em> use these in the library source
- files (but do in your library's headers) and the user
- attempts to compile the library source with a non-default ABI
- setting, then they will get compiler errors if there are any
- conflicts.</li>
-
- <li>If you <em>do</em> include them in both the library's
- headers and the library source files, then the code should
- always compile no matter what the compiler settings used,
- although the result might not match what the user was
- expecting: since we've forced the ABI back into default
- mode.</li>
- </ul>
-
- <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<>
- 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="static_or_dynamic" id=
- "static_or_dynamic"></a>Static or Dynamic Libraries</h3>
-
- <p>When the users runtime is dynamically linked the Boost
- libraries can be built either as dynamic libraries (.so's on
- Unix platforms, .dll's on Windows) or as static libraries (.a's
- on Unix, .lib's on Windows). So we have a choice as to which is
- supported by default:</p>
-
- <ul>
- <li>On Unix platforms it typically makes no difference to the
- code: the user just selects in their makesfile which library
- they prefer to link to.</li>
-
- <li>On Windows platforms, the code has to be specially
- annotated to support DLL's, so we need to pick one option as
- the default and one as an alternative.</li>
-
- <li>On Windows platforms, we can inject special code to
- automatically select which library variant to link against:
- so again we need to decide which is to be the default (see
- the section on auto-linking below).</li>
- </ul>
-
- <p>The recomendation is to pick static linking by default.</p>
-
- <h4>Rationale:</h4>
-
- <p>There is no one policy that fits all here.</p>
-
- <p>The rationale for the current behaviour was inherited from
- Boost.Regex (and it's ancestor regex++): this library
- originally used dynamic linking by default whenever the runtime
- was dynamic. It's actually safer that way should you be using
- regex from a dll for example. However, this behavior brought a
- persistent stream of user complaints: mainly about deployment,
- all asking if static linking could be the default. After regex
- changed behavior the complaints stopped, and the author hasn't
- had one complaint about static linking by default being the
- wrong choice.</p>
-
- <p>Note that other libraries might need to make other choices:
- for example libraries that are intended to be used to implement
- dll pluggin's would like need to use dynamic linking in almost
- all cases.</p>
-
- <h3>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 <boost/config.hpp>
-
-#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 <boost/whatever.hpp>
-
-// 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" id="auto-link"></a>Automatic Library
- Selection and Linking with <a href=
- "/doc/libs/release/boost/config/auto_link.hpp">auto_link.hpp</a></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>Automatic library selection and linking can be enabled for a
- Boost library by including the header
- <boost/config/auto_link.hpp>, after first defining
- BOOST_LIB_NAME and, if applicable, BOOST_DYN_LINK.</p>
- <pre>
-//
-// Automatically link to the correct build variant where possible.
-//
-#if !defined(BOOST_ALL_NO_LIB) && !defined(BOOST_WHATEVER_NO_LIB) && !defined(BOOST_WHATEVER_SOURCE)
-//
-// 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 <boost/config/auto_link.hpp>
-#endif // auto-linking disabled
-</pre>
-
- <p>The library's user documentation should note that the
- feature can be disabled by defining either BOOST_ALL_NO_LIB or
- BOOST_WHATEVER_NO_LIB:</p>
-
- <p>If for any reason you need to debug this feature, the header
- <boost/config/auto_link.hpp> will output some helpful
- diagnostic messages if you first define
- BOOST_LIB_DIAGNOSTIC.</p>
-
- <h2><a name="build_changes" id="build_changes"></a>Changes
- Affecting the Build System</h2>
-
- <h3><a name="build" id="build"></a><a name="jamfile" id=
- "jamfile"></a>Creating the library Jamfile</h3>
-
- <p>The Jamfile for building library "whatever" typically lives
- in boost-root/libs/whatever/build, the only extra step required
- is to add a <define> requirement to the library target so
- that your code knows whether it's building a dll or static
- library, a typical Jamfile would like like this:</p>
- <pre>
-lib boost_regex : ../src/whatever.cpp :
- <link>shared:<define>BOOST_WHATEVER_DYN_LINK=1 ;
-
-</pre>
-
- <h3><a name="testing" id="testing"></a>Testing
- Auto-linking</h3>
-
- <p>Testing the auto-link feature is somewhat convoluted, and
- requires access to a compiler that supports the feature: refer
- to <a href=
- "/doc/libs/release/libs/config/test/link/test/Jamfile.v2">libs/config/test/link/test/Jamfile.v2</a>
- for an example.</p>
- </div>
- </div>
- </div>
- </div>
-
- <div id="sidebar">
- 
- 
- </div>
-
- <div class="clear"></div>
- </div>
- </div>
-
- <div id="footer">
- <div id="footer-left">
- <div id="revised">
- <p>Revised $Date: 2007-10-22 22:55:52 +0100 (Mon, 22 Oct 2007) $</p>
- </div>
-
- <div id="copyright">
- <p>Copyright John Maddock 1998.</p>
- </div>
- </div>
-
- <div id="footer-right">
- 
- </div>
-
- <div class="clear"></div>
- </div>
-</body>
-</html>

Deleted: website/public_html/beta/development/test.html
==============================================================================
--- website/public_html/beta/development/test.html 2010-02-14 07:28:03 EST (Sun, 14 Feb 2010)
+++ (empty file)
@@ -1,170 +0,0 @@
-<!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 Test Policies and Protocols</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <link rel="icon" href="/favicon.ico" type="image/ico" />
- <link rel="stylesheet" type="text/css" href=
- "/style/section-development.css" />
- 
-</head>
-
-<body>
- <div id="heading">
- 
- </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 Test Policies and Protocols</h1>
- </div>
-
- <div class="section-body">
- <p>The Boost libraries are intended to be both reliable and
- portable. Every experienced programmer knows that means each
- library must be tested against a suitable number of test cases,
- on a wide range of platforms, and then tested again (regression
- tested) every time a change is made and before every
- release.</p>
-
- <p>"Quality assurance based on a wide range of targeted tests"
- as one of the key answers to C.A.R Hoare's question "How did
- software get so reliable without proof."</p>
-
- <h2>Regression test</h2>
-
- <p>Boost uses an automatic <a href=
- "/doc/libs/release/tools/regression/doc/index.html">regression
- test suite</a> which generates HTML <a href=
- "/development/testing.html#RegressionTesting">compiler status
- tables</a>.</p>
-
- <h2>Test Policy</h2>
-
- <h3>Required</h3>
-
- <ul>
- <li>Every Boost library should supply one or more suitable
- test programs to be exercised by the Boost <a href=
- "/doc/libs/release/tools/regression/doc/index.html">regression
- test suite</a>. In addition to the usual compile-link-run
- tests expecting successful completion, compile-only or
- compile-and-link-only tests may be performed, and success for
- the test may be defined as failure of the steps.</li>
-
- <li>Test program execution must report errors by returning a
- non-zero value. They may also write to stdout or stderr, but
- that output should be relatively brief. Regardless of other
- output, a non-zero return value is the only way the
- regression test framework will recognize an error has
- occurred. Note that test programs to be included in the
- status tables must compile, link, and run quickly since the
- tests are executed many, many, times.</li>
-
- <li>Libraries with time consuming tests should be divided
- into a fast-execution basic test program for the status
- tables, and a separate full-coverage test program for
- exhaustive test cases. The basic test should concentrate on
- compilation issues so that the status tables accurately
- reflect the library's likelihood of correct compilation on a
- platform.</li>
-
- <li>If for any reason the usual test policies do not apply to
- a particular library, an alternate test strategy must be
- implemented.</li>
-
- <li>A <a href=
- "/doc/libs/release/tools/regression/doc/index.html#Adding_new_test">
- Jamfile</a> to drive the regression tests for the
- library.</li>
- </ul>
-
- <h3>Optional (but highly recommended)</h3>
-
- <p>The <a href="/doc/libs/release/libs/test/index.html">Boost
- Test Library</a> provides many useful components which ease the
- construction of test programs.</p>
-
- <ul>
- <li>Use the library's <a href=
- "/doc/libs/release/libs/test/doc/components/test_tools/index.html">
- Test Tools</a> for the construction of simple test programs
- that do not need much structure.</li>
-
- <li>Use the library's <a href=
- "/doc/libs/release/libs/test/doc/components/utf/index.html">Unit
- Test Framework</a> for the construction of more complex test
- programs that need to be structured into individual tests and
- test suites.</li>
- </ul>
-
- <h2>Suggested Protocol for Fixing Bugs or Adding Features.</h2>
-
- <ul>
- <li>First, add regression test cases that detects the bug or
- tests the feature. Sometimes adding one case suggests similar
- untested cases, and they are added too.</li>
-
- <li>Second, for bugs, run the regression test and verify that
- the bug is now detected.</li>
-
- <li>Third, then, and only then, fix the bug or add the
- feature.</li>
-
- <li>Finally, rerun the full regression tests - sometimes the
- change breaks something else.</li>
- </ul>
-
- <h2>History</h2>
-
- <p><a href=
- "/doc/libs/release/tools/regression/doc/index.html#History">See
- Regression Test History</a>.</p>
-
- <h2>Acknowledgements</h2>
-
- <p>Written by Beman Dawes. Jens Maurer, Paul Moore, Gary Powell
- and Jeremy Siek contributed helpful suggestions.</p>
- <hr />
- </div>
- </div>
- </div>
- </div>
-
- <div id="sidebar">
- 
- 
- </div>
-
- <div class="clear"></div>
- </div>
- </div>
-
- <div id="footer">
- <div id="footer-left">
- <div id="revised">
- <p>Revised $Date$</p>
- </div>
-
- <div id="copyright">
- <p>Copyright Beman Dawes 2001.</p>
- </div>
- </div>
-
- <div id="footer-right">
- 
- </div>
-
- <div class="clear"></div>
- </div>
-</body>
-</html>

Next message: daniel_james_at_[hidden]: "[Boost-commit] svn:boost r59676 - trunk/libs/integer/doc"
Previous message: afojgo_at_[hidden]: "[Boost-commit] svn:boost r59674 - sandbox/itl/libs/itl/prj_home"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk