boost/more
1
0
Fork 0
mirror of https://github.com/boostorg/more.git synced 2025-02-06 06:10:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

Added more explanation about static vs dynamic libraries.

Browse Source 
[SVN r36345]
This commit is contained in:
John Maddock 2006-12-12 13:37:03 +00:00
parent fe54e4d5d0
commit d72028818e
1 changed files with 77 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
separate_compilation.html
View File

@ -5,18 +5,17 @@
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<LINK href="../boost.css" type="text/css" rel="stylesheet"></head> <LINK href="../boost.css" type="text/css" rel="stylesheet"></head>
<body> <body>
<TABLE summary="Page header" id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
<TABLE summary="Page header" id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0"> <TR>
<TR> <td vAlign="top" width="300">
<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>
<h3><A href="../index.htm"><IMG height="86" alt="C++ Boost" src="../boost.png" width="277" border="0"></A></h3> </td>
</td> <TD width="353">
<TD width="353"> <H1 align="center">Guidelines for Authors of Boost Libraries Containing Separate
<H1 align="center">Guidelines for Authors of Boost Libraries Containing Separate Source</H1>
Source</H1> </TD>
</TD> </TR>
</TR> </TABLE>
</TABLE>
<BR> <BR>
<HR> <HR>
<P>These guidelines are designed for the authors of Boost libraries which have <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 occurrences of "whatever" or "WHATEVER" with your own library's name when
copying the examples.</P> copying the examples.</P>
<H2>Contents</H2> <H2>Contents</H2>
<dl class="index">
<dl class="index"> <dt><A href="#source_changes">Changes Affecting Source Code</A>
<dt><A href="#source_changes">Changes Affecting Source Code</A> <dd>
<dd> <dl class="index">
<dl class="index"> <dt><A href="#abi">Preventing Compiler ABI Clashes</A> <DT><A href="#static_or_dynamic">Static
<dt><A href="#abi">Preventing Compiler ABI Clashes</A> <dt><A href="#dlls">Supporting or Dymanic Libraries</A>&nbsp; <dt><A href="#dlls">Supporting Windows Dll's</A> <dt>
Windows Dll's</A> <dt><a href="#auto-link">Automatic Library Selection and Linking <a href="#auto-link">Automatic Library Selection and Linking with auto_link.hpp</a>
with auto_link.hpp</a> </dt> </dt>
</dl> </dl>
<dt><A href="#build_changes">Changes Affecting the Build System</A> <dt><A href="#build_changes">Changes Affecting the Build System</A>
<dd> <dd>
<dl class="index"> <dl class="index">
<dt><A href="#jamfile">Creating the Library Jamfile</A> <dt><A href="#testing">Testing <dt><A href="#jamfile">Creating the Library Jamfile</A> <dt><A href="#testing">Testing
Auto-linking</A> </dt> Auto-linking</A> </dt>
</dl> </dl>
<dt><A href="#copyright">Copyright</A></dt> <dt><A href="#copyright">Copyright</A></dt>
</dl> </dl>
<h2><A name="source_changes"></A>Changes Affecting Source Code</h2> <h2><A name="source_changes"></A>Changes Affecting Source Code</h2>
<H3><A name="abi"></A>Preventing Compiler ABI Clashes</H3> <H3><A name="abi"></A>Preventing Compiler ABI Clashes</H3>
<P>There are some compilers (mostly Microsoft Windows compilers again!), which <P>There are some compilers (mostly Microsoft Windows compilers again!), which
@ -103,10 +101,19 @@ whatever get_whatever();
#endif #endif
</PRE> </PRE>
<P>You can include this code in your source files as well if you want - although <P>You can include this code in your library source files as well if you want,
you probably shouldn't need to - these headers fix the ABI to the default used although you probably shouldn't need to:&nbsp;&nbsp;</P>
by the compiler, and if the user attempts to compile the source with any other <UL>
setting then they will get compiler errors if there are any conflicts.</P> <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> <H4>Rationale:</H4>
<P>Without some means of managing this issue, users often report bugs along the <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. 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 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 be so keen on this solution - with some justification - since they don't face
the same problem.</P> 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).&nbsp; 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&nbsp;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,&nbsp;this
behavior&nbsp;brought a persistent stream of user complaints: mainly about
deployment, all asking if static linking could be the default. After&nbsp;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 <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 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 external symbols are exposed. However the majority of Windows compilers require
@ -311,7 +349,6 @@ libboost_regex-vc71-sgd-1_31.lib
#include &lt;boost/config/auto_link.hpp&gt; #include &lt;boost/config/auto_link.hpp&gt;
#endif // auto-linking disabled #endif // auto-linking disabled
</pre> </pre>
<p>The library's user documentation should note that the feature can be disabled <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> 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 <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> 26 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39365" --></p>
<p><i>© Copyright John Maddock&nbsp;1998- <p><i>© Copyright John Maddock&nbsp;1998-
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2003<!--webbot bot="Timestamp" endspan i-checksum="746" --></i></p> <!--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 <P><I>Distributed under the Boost Software License, Version 1.0. (See accompanying
accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy 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">
at <a href= http://www.boost.org/LICENSE_1_0.txt</a>)</I></P>
"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 <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 of this copyright notice and license declaration; if you wish to provide
attribution then please provide a link to this article.</EM></P> attribution then please provide a link to this article.</EM></P>
</body> </body>
</html> </html>