mirror of
https://github.com/boostorg/more.git
synced 2025-01-04 00:50:10 +08:00
386 lines
21 KiB
HTML
386 lines
21 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
<title>Guidelines for Authors of Boost Libraries Containing Separate Source</title>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
<LINK href="../boost.css" type="text/css" rel="stylesheet"></head>
|
||
<body>
|
||
<TABLE summary="Page header" id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
|
||
<TR>
|
||
<td vAlign="top" width="300">
|
||
<h3><A href="../index.htm"><IMG height="86" alt="C++ Boost" src="../boost.png" width="277" border="0"></A></h3>
|
||
</td>
|
||
<TD width="353">
|
||
<H1 align="center">Guidelines for Authors of Boost Libraries Containing Separate
|
||
Source</H1>
|
||
</TD>
|
||
</TR>
|
||
</TABLE>
|
||
<BR>
|
||
<HR>
|
||
<P>These guidelines are designed for the authors of Boost libraries which have
|
||
separate source that need compiling in order to use the library. Throughout,
|
||
this guide refers to a fictitious "whatever" library, so replace all
|
||
occurrences of "whatever" or "WHATEVER" with your own library's name when
|
||
copying the examples.</P>
|
||
<H2>Contents</H2>
|
||
<dl class="index">
|
||
<dt><A href="#source_changes">Changes Affecting Source Code</A>
|
||
<dd>
|
||
<dl class="index">
|
||
<dt><A href="#abi">Preventing Compiler ABI Clashes</A> <DT><A href="#static_or_dynamic">Static
|
||
or Dymanic Libraries</A> <dt><A href="#dlls">Supporting Windows Dll's</A> <dt>
|
||
<a href="#auto-link">Automatic Library Selection and Linking with auto_link.hpp</a>
|
||
</dt>
|
||
</dl>
|
||
<dt><A href="#build_changes">Changes Affecting the Build System</A>
|
||
<dd>
|
||
<dl class="index">
|
||
<dt><A href="#jamfile">Creating the Library Jamfile</A> <dt><A href="#testing">Testing
|
||
Auto-linking</A> </dt>
|
||
</dl>
|
||
<dt><A href="#copyright">Copyright</A></dt>
|
||
</dl>
|
||
<h2><A name="source_changes"></A>Changes Affecting Source Code</h2>
|
||
<H3><A name="abi"></A>Preventing Compiler ABI Clashes</H3>
|
||
<P>There are some compilers (mostly Microsoft Windows compilers again!), which
|
||
feature a range of compiler switches that alter the ABI of C++ classes and
|
||
functions. By way of example, consider Borland's compiler which has the
|
||
following options:</P>
|
||
<PRE>-b (on or off - effects enum sizes).
|
||
-Vx (on or off - empty members).
|
||
-Ve (on or off - empty base classes).
|
||
-aX (alignment - 5 options).
|
||
-pX (Calling convention - 4 options).
|
||
-VmX (member pointer size and layout - 5 options).
|
||
-VC (on or off, changes name mangling).
|
||
-Vl (on or off, changes struct layout).
|
||
</PRE>
|
||
<P>These options are provided in addition to those affecting which runtime library
|
||
is used (more on which later); the total number of combinations of options can
|
||
be obtained by multiplying together the individual options above, so that gives
|
||
2*2*2*5*4*5*2*2 = 3200 combinations!
|
||
</P>
|
||
<P>The problem is that users often expect to be able to build the Boost libraries
|
||
and then just link to them and have everything just plain work, no matter what
|
||
their project settings are. Irrespective of whether this is a reasonable
|
||
expectation or not, without some means of managing this issue, the user may
|
||
well find that their program will experience strange and hard to track down
|
||
crashes at runtime unless the library they link to was built with the same
|
||
options as their project (changes to the default alignment setting are a prime
|
||
culprit). One way to manage this is with "prefix and suffix" headers: these
|
||
headers invoke compiler specific #pragma directives to instruct the compiler
|
||
that whatever code follows was built (or is to be built) with a specific set of
|
||
compiler ABI settings.</P>
|
||
<P>Boost.config provides the macro BOOST_HAS_ABI_HEADERS which is set whenever
|
||
there are prefix and suffix headers available for the compiler in use, typical
|
||
usage 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>
|
||
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"></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>
|
||
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>
|
||
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"></A>Automatic Library Selection and Linking with <a href="../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"></A>Changes Affecting the Build System</H2>
|
||
<H3><a name="build"></a><A name="jamfile"></A>Creating the library Jamfile</H3>
|
||
<P>The Jamfile for building library "whatever" typically lives in
|
||
boost-root/libs/whatever/build, 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"></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="../libs/config/test/link/test/Jamfile.v2">
|
||
libs/config/test/link/test/Jamfile.v2</A> for an example.</P>
|
||
<HR>
|
||
<p><A name="copyright"></A>Revised
|
||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
||
26 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39365" --></p>
|
||
<p><i><EFBFBD> Copyright John Maddock 1998-
|
||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2003<!--webbot bot="Timestamp" endspan i-checksum="746" --></i></p>
|
||
<P><I>Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||
file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
|
||
http://www.boost.org/LICENSE_1_0.txt</a>)</I></P>
|
||
<P><EM>The use of code snippets from this article does not require the reproduction
|
||
of this copyright notice and license declaration; if you wish to provide
|
||
attribution then please provide a link to this article.</EM></P>
|
||
</body>
|
||
</html>
|