|
|
@@ -5,18 +5,17 @@
|
|
|
<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>
|
|
|
+ <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
|
|
|
@@ -25,24 +24,23 @@
|
|
|
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="#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>
|
|
|
-
|
|
|
+ <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
|
|
|
@@ -103,10 +101,19 @@ whatever get_whatever();
|
|
|
|
|
|
#endif
|
|
|
</PRE>
|
|
|
- <P>You can include this code in your source files as well if you want - although
|
|
|
- you probably shouldn't need to - these headers fix the ABI to the default used
|
|
|
- by the compiler, and if the user attempts to compile the source with any other
|
|
|
- setting then they will get compiler errors if there are any conflicts.</P>
|
|
|
+ <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.
|
|
|
@@ -124,7 +131,38 @@ whatever get_whatever();
|
|
|
shared_ptr.hpp also uses them. Authors of header-only boost libraries may not
|
|
|
be so keen on this solution - with some justification - since they don't face
|
|
|
the same problem.</P>
|
|
|
- <h3><A name="dlls"></A>Supporting Windows Dll's</h3>
|
|
|
+ <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>
|
|
|
+ <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
|
|
|
@@ -311,7 +349,6 @@ libboost_regex-vc71-sgd-1_31.lib
|
|
|
#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
|
|
|
@@ -442,12 +479,12 @@ run
|
|
|
26 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39365" --></p>
|
|
|
<p><i>© 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><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>
|
|
|
+
|
John Maddock