diff --git a/index.htm b/index.htm index 7e60af5..57801ee 100644 --- a/index.htm +++ b/index.htm @@ -1,140 +1,113 @@ - - - - - -Boost More Information - - - - - - - - - - - - - -
- c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
- -

More Information

- -

Boost Policies

- -
-

Mailing List Discussion - Policy.  What's acceptable and what isn't.

-

Library Requirements and - Guidelines.  Basic standards for those preparing - a submission.

-

Writing - Documentation for Boost Basic guidelines - for writing documentation and templates for quickly generating - documentation that follows the guidelines.

-

Test Policy and Protocols.  - How testing works at Boost.

-

Library Submission - Process.  How to submit a library to Boost.

-

Library Formal - Review Process. Including how to submit a review - comment.

-

Header Policy.  - Headers are where a library contacts its users, so - programming practices are particularly important.

-

Implementation Variations.  - Sometimes one size fits all, sometimes it doesn't.  This - page deals with the trade-offs.

-

Library Reuse.  - Should Boost libraries use other boost libraries?  What - about the C++ Standard Library?  It's another trade-off.

-

Moderators.  Who they are and - what they do.

-
- -

Boost Whatever

- -
-

License Information  Information - about the Boost Software License.

-

Bibliography  Print and online - publications relating to Boost and Boost libraries.

-

Compiler - Status  Describes what library works with - which compiler.

-

Links  Links of special interest to - Boost users.

-

Formal Review Schedule  - Future, current, and recently past Formal Reviews.

-

Release Procedures  How - developers and the release manager prepare for a Boost release.

-

Internal Regression Test - Suite   Describes the tool for generating - the compiler status tables

-

Proposal for a C++ Library Repository Web Site  - The original 1998 proposal that launched Boost.

-

How to report bugs  Ways to report - Boost bugs.

-

How to request features - Ways to request new library features.

-

C++ Committee Meetings - FAQ for Boost Members wishing to attend a standards committee meeting.

-
- -

Articles and Papers

- -
-

Error and Exception - Handling describes approaches to errors and - exceptions by David - Abrahams.

-

Counted Body Techniques - by Kevlin Henney is - must reading for those interested in reference counting, a - widely used object management idiom.  Originally - published in Overload - magazine.

-

Generic Programming - Techniques by David - Abrahams and Jeremy - Siek describe some of the techniques used in Boost - libraries.

-

Feature Model - Diagrams in text and HTML describes how to represent - feature model diagrams in text form.

-

Portability Hints: Borland C++ - 5.5.1 describes Borland C++ portability issues, with - suggested workarounds.

-

Portability Hints: - Microsoft VC++ 6.0 SP4 describes Microsoft C++ - portability issues, with suggested workarounds.

-

Coding - Guidelines for Integral Constant Expressions - describes how to work through the maze of compiler related - bugs surrounding this tricky topic.

-
- -
- -

Revised -02 October, 2003

- -

© Copyright Beman Dawes 2003.

-

Use, modification, and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file -LICENSE_1_0.txt or copy at -www.boost.org/LICENSE_1_0.txt)

- - \ No newline at end of file + + Boost More Information + + + + + + + + + + + + + + +
+ c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
+

More Information

+

Boost Policies

+
+

Mailing List Discussion Policy.  + What's acceptable and what isn't.

+

Library Requirements and Guidelines.  + Basic standards for those preparing a submission.

+

Guidelines for Libraries with Separate + Source.  Basic tutorial for libraries that require the + building of a separate link library.

+

Writing Documentation for Boost + Basic guidelines for writing documentation and templates for quickly generating + documentation that follows the guidelines.

+

Test Policy and Protocols.  How + testing works at Boost.

+

Library Submission Process.  + How to submit a library to Boost.

+

Library Formal Review Process. + Including how to submit a review comment.

+

Header Policy.  Headers are where a + library contacts its users, so programming practices are particularly + important.

+

Implementation Variations.  Sometimes + one size fits all, sometimes it doesn't.  This page deals with the + trade-offs.

+

Library Reuse.  Should Boost + libraries use other boost libraries?  What about the C++ Standard + Library?  It's another trade-off.

+

Moderators.  Who they are and what + they do.

+
+

Boost Whatever

+
+

License Information  Information + about the Boost Software License.

+

Bibliography  Print and online + publications relating to Boost and Boost libraries.

+

Compiler Status  Describes + what library works with which compiler.

+

Links  Links of special interest to Boost + users.

+

Formal Review Schedule  + Future, current, and recently past Formal Reviews.

+

Release Procedures  How + developers and the release manager prepare for a Boost release.

+

Internal Regression Test Suite   + Describes the tool for generating the compiler status tables +

+

Proposal for a C++ Library Repository Web Site  + The original 1998 proposal that launched Boost.

+

How to report bugs  Ways to report Boost + bugs.

+

How to request features Ways + to request new library features.

+

C++ Committee Meetings FAQ for + Boost Members wishing to attend a standards committee meeting.

+
+

Articles and Papers

+
+

Error and Exception Handling describes + approaches to errors and exceptions by David + Abrahams. +

+

Counted Body Techniques by + Kevlin Henney is must reading for those interested in reference + counting, a widely used object management idiom.  Originally published in + Overload magazine.

+

Generic Programming Techniques by + David Abrahams and Jeremy Siek describe + some of the techniques used in Boost libraries.

+

Feature Model Diagrams in text and HTML + describes how to represent feature model diagrams in text form.

+

Portability Hints: Borland C++ 5.5.1 describes + Borland C++ portability issues, with suggested workarounds.

+

Portability Hints: Microsoft VC++ 6.0 SP4 + describes Microsoft C++ portability issues, with suggested workarounds.

+

Coding Guidelines for Integral Constant + Expressions describes how to work through the maze of + compiler related bugs surrounding this tricky topic.

+
+
+

+ Revised + + 02 October, 2003

+

+ © Copyright Beman Dawes 2003.

+

+ Use, modification, and distribution are subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt + or copy at www.boost.org/LICENSE_1_0.txt)

+ + diff --git a/lib_guide.htm b/lib_guide.htm index b6d65b8..c59a9de 100644 --- a/lib_guide.htm +++ b/lib_guide.htm @@ -1,498 +1,546 @@ - - - -Boost Library Requirements and Guidelines - - - - - - - - - - - - - - - - -
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
-

Boost Library Requirements and Guidelines

-

Introduction
-Requirements
-    License requirements
-    Portability requirements
-    Ownership
-Guidelines
-    Design and programming
-    Directory structure and -filenames
-    Naming consistency
-    Documentation
-Rationale
-    Exception-specification -rationale
-    Naming conventions rationale
-    Source code fonts rationale
-    Tabs rationale
-    ECMAScript/JavaScript rationale
-    Rationale rationale
-    Acknowledgements rationale

-

Introduction

-

This page describes requirements and guidelines for the content -of a library submitted to Boost.

-

See the Boost Library -Submission Process page for a description of the process involved.

-

Requirements

-

To avoid the frustration and wasted time of a proposed library being -rejected, it must meets these requirements:

- -

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.

-

License requirements

-

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 -developers mailing list first.

-

The license requirements:

- -

Portability requirements

- -

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.

-

Ownership

-

Are you sure you own the library you are thinking of -submitting?   "How to Copyright Software" by MJ Salone, Nolo -Press, 1990 says:

-
-

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.

-
-

Place a copyright notice in all the important files you submit. -Boost won't accept libraries without clear copyright information.

-

Guidelines

-

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.

-

Design and Programming

- - - - - - - - - - - - - - - -

Directory Structure and Filenames

- -
-

Boost standard sub-directory names

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Sub-directoryContentsRequired
buildLibrary build files such as a Jamfile.If any build files.
docDocumentation (HTML) files.If several doc files.
exampleSample program files.If several sample files.
srcSource files which must be compiled to build the library. If any source files.
testRegression or other test programs or scripts.If several test files.
-
-

Redirection

-

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 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.

-

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:

-
- 
<html>
+   
+      Boost Library Requirements and Guidelines
+      
+      
+      
+      
+   
+   
+      
+         
+            
+            
+            
+            
+            
+            
+         
+      
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore

+      
Boost Library Requirements and Guidelines

+      
Introduction

+         Requirements

+             License requirements

+             Portability requirements

+             Ownership

+         Guidelines

+             Design and programming

+             Directory structure and 
+            filenames

+             Naming consistency

+             Documentation

+         Rationale

+             Exception-specification 
+            rationale

+             Naming conventions rationale

+             Source code fonts rationale

+             Tabs rationale

+             ECMAScript/JavaScript rationale

+             Rationale rationale

+             Acknowledgements rationale

+      
Introduction

+      
This page describes requirements and guidelines for the content of 
+         a library submitted to Boost.

+      
See the Boost Library Submission 
+            Process page for a description of the process involved.

+      
Requirements

+      
To avoid the frustration and wasted time of a proposed library being rejected, 
+         it must meets these requirements:

+      
+      
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.

+      
License requirements

+      
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 developers 
+            mailing list first.

+      
The license requirements:

+      
+      
Portability requirements

+      
+      
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.

+      
Ownership

+      
Are you sure you own the library you are thinking of 
+         submitting?   "How to Copyright Software" by MJ Salone, Nolo Press, 
+         1990 says:

+      

+         
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.

+      

+      
Place a copyright notice in all the important files you submit. 
+         Boost won't accept libraries without clear copyright information.

+      
Guidelines

+      
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.

+      
Design and Programming

+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
Directory Structure and Filenames

+      
+      

+         
Boost standard sub-directory names

+         
+            
+               
+               
+               
+            
+            
+               
+               
+               
+            
+            
+               
+               
+               
+            
+            
+               
+               
+               
+            
+            
+               
+               
+               
+            
+            
+               
+               
+               
+            
+         
Sub-directoryContentsRequired
buildLibrary build files such as a Jamfile.If any build files.
docDocumentation (HTML) files.If several doc files.
exampleSample program files.If several sample files.
srcSource files which must be compiled to build the library. If any source files.
testRegression or other test programs or scripts.If several test files.

+      

+      
Redirection

+      
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 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.

+      
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:

+      

+         
<html>
 <head>
-<meta http-equiv="refresh" content="0; URL=doc/index.html">
+<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>
+<a href="doc/index.html">doc/index.html</a>
 </body>
 </html>

-

-
Naming consistency

-
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.

-
Here is how it works. The library is given a name which describes the 
-contents of the library.  Cryptic abbreviations are not acceptable. 
-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".

-
-
Documentation

-
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.

-
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 
-Redirection.

-
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?

-
Appropriate topics for documentation often include:
-

-
If you need more help with how to write documentation you can check out the 
-  article on Writing Documentation for Boost.

-
Rationale

-
Rationale for some of the requirements and guidelines follows.

-

-
Exception-specification rationale

-
Exception specifications [ISO 15.4] are sometimes coded to indicate what
-exceptions may be thrown, or because the programmer hopes they will improved
-performance.  But consider the following member from a smart pointer:

-
    T& operator*() const throw()  { return *ptr; }

-
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.

-
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.

-
Although initially appealing, an exception-specification tends to have
-consequences that require very 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.

-
A non-inline function is the one place a "throws nothing"
-exception-specification may have some benefit with some compilers.

-

-
Naming conventions rationale

-
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:

-
-

-
Source code fonts rationale

-
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.

-

-
Tabs rationale

-
Tabs are banned because of the practical problems caused by tabs in 
-multi-developer projects like Boost, rather than any dislike in principle. See
-mailing list archives. 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.

-

-
ECMAScript/JavaScript rationale

-
Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript 
-documentation. Controversy followed (see 
-mailing list archives), and the developers were asked to remove the 
-ECMAScript/JavaScript. Reasons given for banning included:

-
-

-
Rationale rationale

-
Rationale is defined as "The fundamental reasons for something;
-basis" by the American Heritage Dictionary.

-
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.

-
Rationale is fairly easy to provide at the time decisions are made, but very
-hard to accurately recover even a short time later.

-

-
Acknowledgements rationale

-
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.

-

-
Revised 
-04 November, 2003

-
-
 © Copyright Beman Dawes 2003.

-
 Use, modification, and distribution are subject to the Boost Software 
-License, Version 1.0. (See accompanying file 
-LICENSE_1_0.txt or copy at 
-www.boost.org/LICENSE_1_0.txt)

-
-
-
-
\ No newline at end of file
+
+

Naming consistency

+

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.

+

Here is how it works. The library is given a name which describes the contents + of the library.  Cryptic abbreviations are not acceptable. 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".

+ +

Documentation

+

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.

+

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 Redirection.

+

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?

+

Appropriate topics for documentation often include: +

+

If you need more help with how to write documentation you can check out the + article on Writing Documentation for Boost.

+

Rationale

+

Rationale for some of the requirements and guidelines follows.

+
+

Exception-specification rationale

+

Exception specifications [ISO 15.4] are sometimes coded to indicate what + exceptions may be thrown, or because the programmer hopes they will improved + performance.  But consider the following member from a smart pointer:

+ 
    T& operator*() const throw()  { return *ptr; }
+

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.

+

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.

+

Although initially appealing, an exception-specification tends to have + consequences that require very 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.

+

A non-inline function is the one place a "throws nothing" + exception-specification may have some benefit with some compilers.

+
+

Naming conventions rationale

+

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:

+ +
+

Source code fonts rationale

+

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.

+
+

Tabs rationale

+

Tabs are banned because of the practical problems caused by tabs in + multi-developer projects like Boost, rather than any dislike in principle. See + mailing list archives. 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.

+
+

ECMAScript/JavaScript rationale

+

Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript + documentation. Controversy followed (see mailing + list archives), and the developers were asked to remove the + ECMAScript/JavaScript. Reasons given for banning included:

+ +
+

Rationale rationale

+

Rationale is defined as "The fundamental reasons for something; basis" by the + American Heritage Dictionary.

+

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.

+

Rationale is fairly easy to provide at the time decisions are made, but very + hard to accurately recover even a short time later.

+
+

Acknowledgements rationale

+

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.

+
+

Revised + + 04 November, 2003

+

+ © Copyright Beman Dawes 2003.

+

+ Use, modification, and distribution are subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt + or copy at www.boost.org/LICENSE_1_0.txt)

+ + diff --git a/separate_compilation.html b/separate_compilation.html new file mode 100644 index 0000000..77fe8c0 --- /dev/null +++ b/separate_compilation.html @@ -0,0 +1,447 @@ + + + + Guidelines for Authors of Boost Libraries Containing Separate Source + + + +

+ + + + + +
+

C++ Boost

+ 		+

Guidelines for Authors of Boost Libraries Containing Separate + Source

+
+

+
+

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.

+

Contents

+

+

+
Changes Affecting Source Code +
+
+
Preventing Compiler ABI Clashes
Supporting + Windows Dll's
Enabling Automatic Library Selection + and Linking
+
+
Changes Affecting the Build System +
+
+
Creating the Library Jamfile
Testing + Auto-linking
+
+
Copyright
+
+

+

Changes Affecting Source Code

+

Preventing Compiler ABI Clashes

+

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:

+ 
-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). 
+
+

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! +

+

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.

+

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:

+ 
#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
+
+

Rationale:

+

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.

+
Counter Argument #1:
+

Trust the user, if they want 13-byte alignment (!) let them have it.

+
Counter Argument #2:
+

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.

+

Supporting Windows Dll's

+

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).

+

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:

+ 
#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
+
+ And then in the source code for this library one would use: + 
 
+// 
+// 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();
+}
+
+

Importing/exporting dependencies

+

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:

+ 
#ifdef BOOST_MSVC
+#  pragma warning(push)
+#  pragma warning(disable : 4251 4231 4660)
+#endif
+
+// code here
+
+#ifdef BOOST_MSVC
+#pragma warning(pop)
+#endif
+
+

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. +

+

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.

+

Rationale:

+

Why bother - doesn't the import/export mechanism take up more code that the + classes themselves?

+

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.

+

Why static linking by default? +

+

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).

+

Enabling Automatic Library Selection and Linking

+

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:

+ 
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
+
+

The difficulty now is selecting which of these the user should link his or her + code to.

+

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. +

+

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.

+

This feature can be enabled for Boost libraries by including the header + 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:

+ 
//
+// Automatically link to the correct build variant where possible.
+//
+#if !defined(BOOST_ALL_NO_LIB) && !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 <boost/config/auto_link.hpp>
+#endif  // auto-linking disabled
+
+

+

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.

+

Changes Affecting the Build System

+

Creating the library Jamfile

+

The Jamfile for building library "whatever" typically lives in + boost-root/libs/whatever/build, start by defining the project root for the + Jamfile:

+ 
subproject libs/whatever/build ;
+

Then add the static library build target (if supported):

+ 
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:
+      $(BOOST_ROOT)
+   : 
+      # list default build variants here
+      debug release 
+   ;
+

Then add the dll build target (if supported).  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).  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, as well as exception handling runtimes).

+ 
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:
+      <define>BOOST_ALL_DYN_LINK=1
+      # only build this for dynamic runtimes:
+      <runtime-link>dynamic
+      # set include path for Boost headers:
+      $(BOOST_ROOT)
+   : 
+      # list default build variants here
+      debug release 
+   ;
+

Now add an install target so that Boost.Install can find this library to + install:

+ 
install whatever lib
+    : boost_whatever boost_whatever
+    ;
+
+

Finally add a stage target that will copy the built libraries to a common + sub-directory (boost-root/stage/lib):

+ 
stage stage/lib : boost_whatever boost_whatever
+    :
+        # copy to a path rooted at BOOST_ROOT:
+        $(BOOST_ROOT)
+        # make sure the names of the libraries are correctly named:
+        [ common-names ]
+        # add this target to the "stage" and "all" psuedo-targets:
+        stage
+        all
+    :
+        debug release
+    ;
+
+

Testing Auto-linking

+

Testing the auto-link feature reasonable straightforward using + the 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:

+ 
+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
+      <library-path>../../../../stage/lib
+      <define>BOOST_LIB_DIAGNOSTIC=1
+   : 	# program name
+      whatever_test          
+   ;
+
+   # and then a dll linking version:
+   run 
+   # sources
+      ../whatever_test.cpp
+   :
+   :	# input files
+   : 	# requirements
+      <library-path>../../../../stage/lib
+      <define>BOOST_LIB_DIAGNOSTIC=1
+      <define>BOOST_ALL_DYN_LINK=1
+      <runtime-link>dynamic
+   : 	# program name
+      whatever_test_dll          
+   ;
+
+
+

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.  The Jamfile should also be built for all possible build + variants, for the Microsoft / Borland compilers that means doing a:

+ 
bjam -sBUILD="release debug <threading>multi/single <runtime-link>static/dynamic" test
+
+
+

Revised + + 21 Nov 2003 +

+

© Copyright John Maddock 1998- + 2003

+

Use, modification and distribution are subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt).

+

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.

+ +