mirror of
https://github.com/boostorg/documentation-fixes.git
synced 2026-01-19 04:12:08 +00:00
Website: Update config docs for 1.51 and 1.52. Refs #7676.
[SVN r81443]
This commit is contained in:
Daniel James
@@ -0,0 +1,62 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Acknowledgements</title>
|
||||
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Boost.Config">
|
||||
<link rel="prev" href="rationale.html" title="Rationale">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.acknowledgements"></a><a class="link" href="acknowledgements.html" title="Acknowledgements">Acknowledgements</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
Beman Dawes provided the original <code class="computeroutput"><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code> and
|
||||
part of this document.
|
||||
</p>
|
||||
<p>
|
||||
Vesa Karvonen provided a description of the principles (see <a class="link" href="rationale.html" title="Rationale">rationale</a>)
|
||||
and put together an early version of the current configuration setup.
|
||||
</p>
|
||||
<p>
|
||||
John Maddock put together the configuration current code, the test programs,
|
||||
the configuration script and the reference section of this document.
|
||||
</p>
|
||||
<p>
|
||||
Matias Capeletto converted the docs to quickbook format.
|
||||
</p>
|
||||
<p>
|
||||
Numerous boost members, past and present, have contributed fixes to boost's
|
||||
configuration.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
|
||||
Maddock<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,377 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Guidelines for Boost Authors</title>
|
||||
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Boost.Config">
|
||||
<link rel="prev" href="boost_macro_reference.html" title="Boost Macro Reference">
|
||||
<link rel="next" href="rationale.html" title="Rationale">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="boost_macro_reference.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.guidelines_for_boost_authors"></a><a class="link" href="guidelines_for_boost_authors.html" title="Guidelines for Boost Authors">Guidelines for
|
||||
Boost Authors</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings">Disabling
|
||||
Compiler Warnings</a></span></dt>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros">Adding
|
||||
New Defect Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros">Adding
|
||||
New Feature Test Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers">Modifying
|
||||
the Boost Configuration Headers</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
The <a href="../../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
header is used to pass configuration information to other boost files, allowing
|
||||
them to cope with platform dependencies such as arithmetic byte ordering, compiler
|
||||
pragmas, or compiler shortcomings. Without such configuration information,
|
||||
many current compilers would not work with the Boost libraries.
|
||||
</p>
|
||||
<p>
|
||||
Centralizing configuration information in this header reduces the number of
|
||||
files that must be modified when porting libraries to new platforms, or when
|
||||
compilers are updated. Ideally, no other files would have to be modified when
|
||||
porting to a new platform.
|
||||
</p>
|
||||
<p>
|
||||
Configuration headers are controversial because some view them as condoning
|
||||
broken compilers and encouraging non-standard subsets. Adding settings for
|
||||
additional platforms and maintaining existing settings can also be a problem.
|
||||
In other words, configuration headers are a necessary evil rather than a desirable
|
||||
feature. The boost config.hpp policy is designed to minimize the problems and
|
||||
maximize the benefits of a configuration header.
|
||||
</p>
|
||||
<p>
|
||||
Note that:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
Boost library implementers are not required to "<code class="computeroutput"><span class="preprocessor">#include</span>
|
||||
<span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>", and are not required in any
|
||||
way to support compilers that do not comply with the C++ Standard (ISO/IEC
|
||||
14882).
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If a library implementer wishes to support some non-conforming compiler,
|
||||
or to support some platform specific feature, "<code class="computeroutput"><span class="preprocessor">#include</span>
|
||||
<span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>" is the preferred way to obtain
|
||||
configuration information not available from the standard headers such
|
||||
as <code class="computeroutput"><span class="special"><</span><span class="identifier">climits</span><span class="special">></span></code>, etc.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If configuration information can be deduced from standard headers such
|
||||
as <code class="computeroutput"><span class="special"><</span><span class="identifier">climits</span><span class="special">></span></code>, use those standard headers rather
|
||||
than <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Boost files that use macros defined in <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
should have sensible, standard conforming, default behavior if the macro
|
||||
is not defined. This means that the starting point for porting <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code> to a new platform is simply to define
|
||||
nothing at all specific to that platform. In the rare case where there
|
||||
is no sensible default behavior, an #error message should describe the
|
||||
problem.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If a Boost library implementer wants something added to <code class="computeroutput"><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code>,
|
||||
post a request on the Boost mailing list. There is no guarantee such a
|
||||
request will be honored; the intent is to limit the complexity of config.hpp.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The intent is to support only compilers which appear on their way to becoming
|
||||
C++ Standard compliant, and only recent releases of those compilers at
|
||||
that.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The intent is not to disable mainstream features now well-supported by
|
||||
the majority of compilers, such as namespaces, exceptions, RTTI, or templates.
|
||||
</li>
|
||||
</ul></div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.warnings"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings" title="Disabling Compiler Warnings">Disabling
|
||||
Compiler Warnings</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The header <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">warning_disable</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
can be used to disable certain compiler warnings that are hard or impossible
|
||||
to otherwise remove.
|
||||
</p>
|
||||
<p>
|
||||
Note that:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
This header <span class="bold"><strong><span class="emphasis"><em>should never be included
|
||||
by another Boost header</em></span></strong></span>, it should only ever be
|
||||
used by a library source file or a test case.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The header should be included <span class="bold"><strong><span class="emphasis"><em>before
|
||||
you include any other header</em></span></strong></span>.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
This header only disables warnings that are hard or impossible to otherwise
|
||||
deal with, and which are typically emitted by one compiler only, or in
|
||||
one compilers own standard library headers.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Currently it disables the following warnings:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
Compiler
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Warning
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
Visual C++ 8 and later
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
<a href="http://msdn2.microsoft.com/en-us/library/ttcz0bys(VS.80).aspx" target="_top">C4996</a>:
|
||||
Error 'function': was declared deprecated
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
Intel C++
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Warning 1786: relates to the use of "deprecated" standard
|
||||
library functions rather like C4996 in Visual C++.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.adding_new_defect_macros"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros" title="Adding New Defect Macros">Adding
|
||||
New Defect Macros</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
When you need to add a new defect macro - either to fix a problem with an
|
||||
existing library, or when adding a new library - distil the issue down to
|
||||
a simple test case; often, at this point other (possibly better) workarounds
|
||||
may become apparent. Secondly always post the test case code to the boost
|
||||
mailing list and invite comments; remember that C++ is complex and that sometimes
|
||||
what may appear a defect, may in fact turn out to be a problem with the authors
|
||||
understanding of the standard.
|
||||
</p>
|
||||
<p>
|
||||
When you name the macro, follow the <code class="computeroutput"><span class="identifier">BOOST_NO_</span></code><span class="emphasis"><em>SOMETHING</em></span>
|
||||
naming convention, so that it's obvious that this is a macro reporting a
|
||||
defect.
|
||||
</p>
|
||||
<p>
|
||||
Finally, add the test program to the regression tests. You will need to place
|
||||
the test case in a <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code>
|
||||
file with the following comments near the top:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">// MACRO: BOOST_NO_FOO</span>
|
||||
<span class="comment">// TITLE: foo</span>
|
||||
<span class="comment">// DESCRIPTION: If the compiler fails to support foo</span>
|
||||
</pre>
|
||||
<p>
|
||||
These comments are processed by the autoconf script, so make sure the format
|
||||
follows the one given. The file should be named "<code class="computeroutput"><span class="identifier">boost_no_foo</span><span class="special">.</span><span class="identifier">ipp</span></code>",
|
||||
where foo is the defect description - try and keep the file name under the
|
||||
Mac 30 character filename limit though. You will also need to provide a function
|
||||
prototype "<code class="computeroutput"><span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span></code>" that is declared in a namespace with
|
||||
the same name as the macro, but in all lower case, and which returns zero
|
||||
on success:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost_no_foo</span> <span class="special">{</span>
|
||||
<span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// test code goes here:</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Once the test code is in place in libs/config/test, updating the configuration
|
||||
test system proceeds as:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">tools</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span></code>.
|
||||
This generates the <code class="computeroutput"><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
file test cases from the <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code> file, updates the libs/config/test/all/Jamfile.v2,
|
||||
<code class="computeroutput"><span class="identifier">config_test</span><span class="special">.</span><span class="identifier">cpp</span></code> and <code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>.<br>
|
||||
<br>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">all</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span>
|
||||
</code><span class="emphasis"><em>MACRONAME<code class="computeroutput"> <span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>,
|
||||
where <span class="emphasis"><em>MACRONAME</em></span> is the name of the new macro, and
|
||||
<span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span> is a space separated
|
||||
list of compilers to test with.<br> <br> The xxx_pass_test and the
|
||||
xxx_fail_test <span class="bold"><strong>should both report <code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code></strong></span>.<br> <br> If <span class="emphasis"><em>MACRONAME</em></span>
|
||||
is not defined when it should be defined, xxx_pass_test will not report
|
||||
<code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code>. If <span class="emphasis"><em>MACRONAME</em></span>
|
||||
is defined when it should not be defined, xxx_fail_test will not report
|
||||
<code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code>.<br> <br>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">test</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span>
|
||||
<span class="identifier">config_info</span> <span class="identifier">config_test</span>
|
||||
</code><span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>.
|
||||
<code class="computeroutput"><span class="identifier">config_info</span></code> should build
|
||||
and run cleanly for all the compilers in <span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>
|
||||
while <code class="computeroutput"><span class="identifier">config_test</span></code> should
|
||||
fail for those that have the defect, and pass for those that do not.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Then you should:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
Define the defect macro in those config headers that require it.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Document the macro in this documentation (please do not forget this step!!)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Commit everything.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Keep an eye on the regression tests for new failures in Boost.Config
|
||||
caused by the addition.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Start using the macro.
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros" title="Adding New Feature Test Macros">Adding
|
||||
New Feature Test Macros</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
When you need to add a macro that describes a feature that the standard does
|
||||
not require, follow the convention for adding a new defect macro (above),
|
||||
but call the macro <code class="computeroutput"><span class="identifier">BOOST_HAS_FOO</span></code>,
|
||||
and name the test file "<code class="computeroutput"><span class="identifier">boost_has_foo</span><span class="special">.</span><span class="identifier">ipp</span></code>".
|
||||
Try not to add feature test macros unnecessarily, if there is a platform
|
||||
specific macro that can already be used (for example <code class="computeroutput"><span class="identifier">_WIN32</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">__BEOS__</span></code>, or <code class="computeroutput"><span class="identifier">__linux</span></code>) to identify the feature then use
|
||||
that. Try to keep the macro to a feature group, or header name, rather than
|
||||
one specific API (for example <code class="computeroutput"><span class="identifier">BOOST_HAS_NL_TYPES_H</span></code>
|
||||
rather than <code class="computeroutput"><span class="identifier">BOOST_HAS_CATOPEN</span></code>).
|
||||
If the macro describes a POSIX feature group, then add boilerplate code to
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>
|
||||
to auto-detect the feature where possible (if you are wondering why we can't
|
||||
use POSIX feature test macro directly, remember that many of these features
|
||||
can be added by third party libraries, and are not therefore identified inside
|
||||
<code class="computeroutput"><span class="special"><</span><span class="identifier">unistd</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code>).
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers" title="Modifying the Boost Configuration Headers">Modifying
|
||||
the Boost Configuration Headers</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The aim of boost's configuration setup is that the configuration headers
|
||||
should be relatively stable - a boost user should not have to recompile their
|
||||
code just because the configuration for some compiler that they're not interested
|
||||
in has changed. Separating the configuration into separate compiler/standard
|
||||
library/platform sections provides for part of this stability, but boost
|
||||
authors require some amount of restraint as well, in particular:
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
should never change, don't alter this file.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
is included by default, don't add extra code to this file unless you have
|
||||
to. If you do, please remember to update <a href="../../../tools/configure.in" target="_top">libs/config/tools/configure.in</a>
|
||||
as well.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>
|
||||
is always included so be careful about modifying this file as it breaks dependencies
|
||||
for everyone. This file should include only "boilerplate" configuration
|
||||
code, and generally should change only when new macros are added.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/select_compiler_config.hpp" target="_top"><boost/config/select_compiler_config.hpp></a>,
|
||||
<a href="../../../../../boost/config/select_platform_config.hpp" target="_top"><boost/config/select_platform_config.hpp></a>
|
||||
and <a href="../../../../../boost/config/select_stdlib_config.hpp" target="_top"><boost/config/select_stdlib_config.hpp></a>
|
||||
are included by default and should change only if support for a new compiler/standard
|
||||
library/platform is added.
|
||||
</p>
|
||||
<p>
|
||||
The compiler/platform/standard library selection code is set up so that unknown
|
||||
platforms are ignored and assumed to be fully standards compliant - this
|
||||
gives unknown platforms a "sporting chance" of working "as
|
||||
is" even without running the configure script.
|
||||
</p>
|
||||
<p>
|
||||
When adding or modifying the individual mini-configs, assume that future,
|
||||
as yet unreleased versions of compilers, have all the defects of the current
|
||||
version. Although this is perhaps unnecessarily pessimistic, it cuts down
|
||||
on the maintenance of these files, and experience suggests that pessimism
|
||||
is better placed than optimism here!
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
|
||||
Maddock<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="boost_macro_reference.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
124
boost_1_51_0/libs/config/doc/html/boost_config/rationale.html
Normal file
124
boost_1_51_0/libs/config/doc/html/boost_config/rationale.html
Normal file
@@ -0,0 +1,124 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Rationale</title>
|
||||
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Boost.Config">
|
||||
<link rel="prev" href="guidelines_for_boost_authors.html" title="Guidelines for Boost Authors">
|
||||
<link rel="next" href="acknowledgements.html" title="Acknowledgements">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="guidelines_for_boost_authors.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.rationale"></a><a class="link" href="rationale.html" title="Rationale">Rationale</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="rationale.html#boost_config.rationale.the_problem">The problem</a></span></dt>
|
||||
<dt><span class="section"><a href="rationale.html#boost_config.rationale.the_solution">The solution</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
The problem with many traditional "textbook" implementations of configuration
|
||||
headers (where all the configuration options are in a single "monolithic"
|
||||
header) is that they violate certain fundamental software engineering principles
|
||||
which would have the effect of making boost more fragile, more difficult to
|
||||
maintain and more difficult to use safely. You can find a description of the
|
||||
principles from the <a href="http://www.objectmentor.com/resources/articles/Principles_and_Patterns.pdf" target="_top">following
|
||||
article</a>.
|
||||
</p>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.rationale.the_problem"></a><a class="link" href="rationale.html#boost_config.rationale.the_problem" title="The problem">The problem</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Consider a situation in which you are concurrently developing on multiple
|
||||
platforms. Then consider adding a new platform or changing the platform definitions
|
||||
of an existing platform. What happens? Everything, and this does literally
|
||||
mean everything, recompiles. Isn't it quite absurd that adding a new platform,
|
||||
which has absolutely nothing to do with previously existing platforms, means
|
||||
that all code on all existing platforms needs to be recompiled?
|
||||
</p>
|
||||
<p>
|
||||
Effectively, there is an imposed physical dependency between platforms that
|
||||
have nothing to do with each other. Essentially, the traditional solution
|
||||
employed by configuration headers does not conform to the Open-Closed Principle:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<span class="bold"><strong>"A module should be open for extension but closed
|
||||
for modification."</strong></span>
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
Extending a traditional configuration header implies modifying existing code.
|
||||
</p>
|
||||
<p>
|
||||
Furthermore, consider the complexity and fragility of the platform detection
|
||||
code. What if a simple change breaks the detection on some minor platform?
|
||||
What if someone accidentally or on purpose (as a workaround for some other
|
||||
problem) defines some platform dependent macros that are used by the detection
|
||||
code? A traditional configuration header is one of the most volatile headers
|
||||
of the entire library, and more stable elements of Boost would depend on
|
||||
it. This violates the Stable Dependencies Principle:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<span class="bold"><strong>"Depend in the direction of stability."</strong></span>
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
After even a minor change to a traditional configuration header on one minor
|
||||
platform, almost everything on every platform should be tested if we follow
|
||||
sound software engineering practice.
|
||||
</p>
|
||||
<p>
|
||||
Another important issue is that it is not always possible to submit changes
|
||||
to <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>.
|
||||
Some boost users are currently working on platforms using tools and libraries
|
||||
that are under strict Non-Disclosure Agreements. In this situation it is
|
||||
impossible to submit changes to a traditional monolithic configuration header,
|
||||
instead some method by which the user can insert their own configuration
|
||||
code must be provided.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.rationale.the_solution"></a><a class="link" href="rationale.html#boost_config.rationale.the_solution" title="The solution">The solution</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The approach taken by boost's configuration headers is to separate configuration
|
||||
into three orthogonal parts: the compiler, the standard library and the platform.
|
||||
Each compiler/standard library/platform gets its own mini-configuration header,
|
||||
so that changes to one compiler's configuration (for example) does not affect
|
||||
other compilers. In addition there are measures that can be taken both to
|
||||
omit the compiler/standard library/platform detection code (so that adding
|
||||
support to a new platform does not break dependencies), or to freeze the
|
||||
configuration completely; providing almost complete protection against dependency
|
||||
changes.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
|
||||
Maddock<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="guidelines_for_boost_authors.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
960
boost_1_51_0/libs/config/doc/html/index.html
Normal file
960
boost_1_51_0/libs/config/doc/html/index.html
Normal file
@@ -0,0 +1,960 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Boost.Config</title>
|
||||
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="index.html" title="Boost.Config">
|
||||
<link rel="next" href="boost_config/boost_macro_reference.html" title="Boost Macro Reference">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="boost_config/boost_macro_reference.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
|
||||
<div class="article">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div><h2 class="title">
|
||||
<a name="config"></a>Boost.Config</h2></div>
|
||||
<div><div class="authorgroup"><div class="author"><h3 class="author">
|
||||
<span class="firstname">Vesa Karvonen, John Maddock</span> <span class="surname">Beman Dawes</span>
|
||||
</h3></div></div></div>
|
||||
<div><p class="copyright">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
|
||||
Maddock</p></div>
|
||||
<div><div class="legalnotice">
|
||||
<a name="config.legal"></a><p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></div>
|
||||
</div>
|
||||
<hr>
|
||||
</div>
|
||||
<div class="toc">
|
||||
<p><b>Table of Contents</b></p>
|
||||
<dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform">Configuring
|
||||
Boost for Your Platform</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration">Using
|
||||
the default boost configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header">The
|
||||
<boost/config.hpp> header</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script">Using
|
||||
the configure script</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options">User
|
||||
settable options</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage">Advanced
|
||||
configuration usage</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration">Testing
|
||||
the boost configuration</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html">Boost Macro Reference</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_c__03_defects">Macros
|
||||
that describe C++03 defects</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_optional_features">Macros
|
||||
that describe optional features</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_possible_c___future_features">Macros
|
||||
that describe possible C++ future features</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_c__11_features_not_supported">Macros
|
||||
that describe C++11 features not supported</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_allow_use_of_c__11_features_with_c__03_compilers">Macros
|
||||
that allow use of C++11 features with C++03 compilers</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_helper_macros">Boost
|
||||
Helper Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_informational_macros">Boost
|
||||
Informational Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_deprecated_macros">Boost
|
||||
Deprecated Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_for_libraries_with_separate_source_code">Macros
|
||||
for libraries with separate source code</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html">Guidelines for
|
||||
Boost Authors</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings">Disabling
|
||||
Compiler Warnings</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros">Adding
|
||||
New Defect Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros">Adding
|
||||
New Feature Test Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers">Modifying
|
||||
the Boost Configuration Headers</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html">Rationale</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html#boost_config.rationale.the_problem">The problem</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html#boost_config.rationale.the_solution">The solution</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/acknowledgements.html">Acknowledgements</a></span></dt>
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.configuring_boost_for_your_platform"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform" title="Configuring Boost for Your Platform">Configuring
|
||||
Boost for Your Platform</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration">Using
|
||||
the default boost configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header">The
|
||||
<boost/config.hpp> header</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script">Using
|
||||
the configure script</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options">User
|
||||
settable options</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage">Advanced
|
||||
configuration usage</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration">Testing
|
||||
the boost configuration</a></span></dt>
|
||||
</dl></div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration" title="Using the default boost configuration">Using
|
||||
the default boost configuration</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Boost comes already configured for most common compilers and platforms; you
|
||||
should be able to use boost "as is". Since the compiler is configured
|
||||
separately from the standard library, the default configuration should work
|
||||
even if you replace the compiler's standard library with a third-party standard
|
||||
library (like <a href="http://stlport.sourceforge.net" target="_top">STLport</a>).
|
||||
</p>
|
||||
<p>
|
||||
Using boost "as is" without trying to reconfigure is the recommended
|
||||
method for using boost. You can, however, run the configure script if you
|
||||
want to, and there are regression tests provided that allow you to test the
|
||||
current boost configuration with your particular compiler setup.
|
||||
</p>
|
||||
<p>
|
||||
Boost library users can request support for additional compilers or platforms
|
||||
by visiting our <a href="https://svn.boost.org/trac/boost/newticket" target="_top">Trac</a>
|
||||
and submitting a support request.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header" title="The <boost/config.hpp> header">The
|
||||
<boost/config.hpp> header</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Boost library implementations access configuration macros via
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <a href="../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
</pre>
|
||||
<p>
|
||||
While Boost library users are not required to include that file directly,
|
||||
or use those configuration macros, such use is acceptable. The configuration
|
||||
macros are documented as to their purpose, usage, and limitations which makes
|
||||
them usable by both Boost library and user code.
|
||||
</p>
|
||||
<p>
|
||||
Boost <a class="link" href="boost_config/boost_macro_reference.html#config_info_macros">informational</a> or <a class="link" href="boost_config/boost_macro_reference.html#config_helpers">helper</a>
|
||||
macros are designed for use by Boost users as well as for our own internal
|
||||
use. Note however, that the <a class="link" href="boost_config/boost_macro_reference.html#config_features">feature test</a>
|
||||
and <a class="link" href="boost_config/boost_macro_reference.html#config_defects">defect test</a> macros were designed
|
||||
for internal use by Boost libraries, not user code, so they can change at
|
||||
any time (though no gratuitous changes are made to them). Boost library problems
|
||||
resulting from changes to the configuration macros are caught by the Boost
|
||||
regression tests, so the Boost libraries are updated to account for those
|
||||
changes. By contrast, Boost library user code can be adversely affected by
|
||||
changes to the macros without warning. The best way to keep abreast of changes
|
||||
to the macros used in user code is to monitor the discussions on the Boost
|
||||
developers list.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.using_the_configure_script"></a><a name="config_config_script"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script" title="Using the configure script">Using
|
||||
the configure script</a>
|
||||
</h3></div></div></div>
|
||||
<div class="important"><table border="0" summary="Important">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../doc/src/images/important.png"></td>
|
||||
<th align="left">Important</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
This configure script only sets up the Boost headers for use with a particular
|
||||
compiler. It has no effect on Boost.Build, or how the libraries are built.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
If you know that boost is incorrectly configured for your particular setup,
|
||||
and you are on a UNIX like platform, then you may want to try and improve
|
||||
things by running the boost configure script. From a shell command prompt
|
||||
you will need to cd into <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
and type:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<code class="computeroutput"><span class="identifier">sh</span> <span class="special">./</span><span class="identifier">configure</span></code>
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
you will see a list of the items being checked as the script works its way
|
||||
through the regression tests. Note that the configure script only really
|
||||
auto-detects your compiler if it's called g++, c++ or CC. If you are using
|
||||
some other compiler you will need to set one or more of the following environment
|
||||
variables:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
Variable
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
CXX
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The name of the compiler, for example <code class="computeroutput"><span class="identifier">c</span><span class="special">++</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
CXXFLAGS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The compiler flags to use, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">O2</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
LDFLAGS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The linker flags to use, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">L</span><span class="special">/</span><span class="identifier">mypath</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
LIBS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Any libraries to link in, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">lpthread</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
<p>
|
||||
For example to run the configure script with HP aCC, you might use something
|
||||
like:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">export</span> <span class="identifier">CXX</span><span class="special">=</span><span class="string">"aCC"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">CXXFLAGS</span><span class="special">=</span><span class="string">"-Aa -DAportable -D__HPACC_THREAD_SAFE_RB_TREE \
|
||||
-DRWSTD_MULTI_THREAD -DRW_MULTI_THREAD -D_REENTRANT -D_THREAD_SAFE"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">LDFLAGS</span><span class="special">=</span><span class="string">"-DAportable"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">LIBS</span><span class="special">=</span><span class="string">"-lpthread"</span>
|
||||
<span class="identifier">sh</span> <span class="special">./</span><span class="identifier">configure</span>
|
||||
</pre>
|
||||
<p>
|
||||
However you run the configure script, when it finishes you will find a new
|
||||
header -<code class="computeroutput"><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span></code>- located in the <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
directory. <span class="bold"><strong>Note that configure does not install this
|
||||
header into your boost include path by default</strong></span>. This header contains
|
||||
all the options generated by the configure script, plus a header-section
|
||||
that contains the user settable options from the default version of <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
(located under <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>).
|
||||
There are two ways you can use this header:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
<span class="bold"><strong>Option 1:</strong></span> copy the header into <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code> so that it replaces the default user.hpp
|
||||
provided by boost. This option allows only one configure-generated setup;
|
||||
boost developers should avoid this option, as it incurs the danger of
|
||||
accidentally committing a configure-modified <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
to the svn repository (something you will not be thanked for!).
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<span class="bold"><strong>Option 2:</strong></span> give the header a more memorable
|
||||
name, and place it somewhere convenient; then, define the macro <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code> to point to it. For
|
||||
example create a new sub-directory <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code> <code class="computeroutput"><span class="identifier">user</span><span class="special">/</span></code>, and copy the header there; for example
|
||||
as <code class="computeroutput"><span class="identifier">multithread</span><span class="special">-</span><span class="identifier">gcc</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code>. Then, when compiling add the command
|
||||
line option: <code class="computeroutput"><span class="special">-</span><span class="identifier">DBOOST_USER_CONFIG</span><span class="special">=</span><span class="string">"<boost/config/user/multithread-gcc-config.hpp>"</span></code>,
|
||||
and boost will use the new configuration header. This option allows you
|
||||
to generate more than one configuration header, and to keep them separate
|
||||
from the boost source - so that updates to the source do not interfere
|
||||
with your configuration.
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.user_settable_options"></a><a name="config_user_settable"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options" title="User settable options">User
|
||||
settable options</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
There are some configuration-options that represent user choices, rather
|
||||
than compiler defects or platform specific options. These are listed in
|
||||
<code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
and at the start of a configure-generated <code class="computeroutput"><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span></code> header.
|
||||
You can define these on the command line, or by editing <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>, they are listed in the following table:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
Macro
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the user configuration
|
||||
file to include prior to any boost configuration files. When not
|
||||
defined, defaults to <a href="../../../../boost/config/user.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_COMPILER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the compiler configuration
|
||||
file to use. Defining this cuts out the compiler selection logic,
|
||||
and eliminates the dependency on the header containing that logic.
|
||||
For example if you are using gcc, then you could define BOOST_COMPILER_CONFIG
|
||||
to <a href="../../../../boost/config/compiler/gcc.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">compiler</span><span class="special">/</span><span class="identifier">gcc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_STDLIB_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the standard library
|
||||
configuration file to use. Defining this cuts out the standard
|
||||
library selection logic, and eliminates the dependency on the header
|
||||
containing that logic. For example if you are using STLport, then
|
||||
you could define <code class="computeroutput"><span class="identifier">BOOST_STDLIB_CONFIG</span></code>
|
||||
to <a href="../../../../boost/config/stdlib/stlport.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">stdlib</span><span class="special">/</span><span class="identifier">stlport</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_PLATFORM_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the platform configuration
|
||||
file to use. Defining this cuts out the platform selection logic,
|
||||
and eliminates the dependency on the header containing that logic.
|
||||
For example if you are compiling on linux, then you could define
|
||||
<code class="computeroutput"><span class="identifier">BOOST_PLATFORM_CONFIG</span></code>
|
||||
to <a href="../../../../boost/config/platform/linux.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">platform</span><span class="special">/</span><span class="identifier">linux</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no compiler configuration file is selected or included,
|
||||
define when the compiler is fully conformant with the standard,
|
||||
or where the user header (see <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>),
|
||||
has had any options necessary added to it, for example by an autoconf
|
||||
generated configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_STDLIB_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no standard library configuration file is selected
|
||||
or included, define when the standard library is fully conformant
|
||||
with the standard, or where the user header (see <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>), has had any
|
||||
options necessary added to it, for example by an autoconf generated
|
||||
configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_PLATFORM_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no platform configuration file is selected or included,
|
||||
define when the platform is fully conformant with the standard
|
||||
(and has no useful extra features), or where the user header (see
|
||||
<code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>),
|
||||
has had any options necessary added to it, for example by an autoconf
|
||||
generated configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Equivalent to defining all of <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_STDLIB_CONFIG</span></code>
|
||||
and <code class="computeroutput"><span class="identifier">BOOST_NO_PLATFORM_CONFIG</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_STRICT_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The normal behavior for compiler versions that are newer than the
|
||||
last known version, is to assume that they have all the same defects
|
||||
as the last known version. By setting this define, then compiler
|
||||
versions that are newer than the last known version are assumed
|
||||
to be fully conforming with the standard. This is probably most
|
||||
useful for boost developers or testers, and for those who want
|
||||
to use boost to test beta compiler versions.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ASSERT_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When this flag is set, if the config finds anything unknown, then
|
||||
it will stop with a #error rather than continue. Boost regression
|
||||
testers should set this define, as should anyone who wants to quickly
|
||||
check whether boost is supported on their platform.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_THREADS</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, disables threading support, even if the compiler
|
||||
in its current translation mode supports multiple threads.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_WIN32</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, disables the use of Win32 specific API's, even when
|
||||
these are available. Also has the effect of setting <code class="computeroutput"><span class="identifier">BOOST_DISABLE_THREADS</span></code> unless
|
||||
<code class="computeroutput"><span class="identifier">BOOST_HAS_PTHREADS</span></code>
|
||||
is set. This option may be set automatically by the config system
|
||||
when it detects that the compiler is in "strict mode".
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_ABI_HEADERS</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Stops boost headers from including any prefix/suffix headers that
|
||||
normally control things like struct packing and alignment.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ABI_PREFIX</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
A prefix header to include in place of whatever boost.config would
|
||||
normally select, any replacement should set up struct packing and
|
||||
alignment options as required.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ABI_SUFFIX</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
A suffix header to include in place of whatever boost.config would
|
||||
normally select, any replacement should undo the effects of the
|
||||
prefix header.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ALL_DYN_LINK</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Forces all libraries that have separate source, to be linked as
|
||||
dll's rather than static libraries on Microsoft Windows (this macro
|
||||
is used to turn on <code class="computeroutput"><span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllimport</span><span class="special">)</span></code> modifiers, so that the compiler
|
||||
knows which symbols to look for in a dll rather than in a static
|
||||
library). Note that there may be some libraries that can only be
|
||||
statically linked (Boost.Test for example) and others which may
|
||||
only be dynamically linked (Boost.Thread for example), in these
|
||||
cases this macro has no effect.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_</span></code><span class="emphasis"><em>WHATEVER</em></span><code class="computeroutput"><span class="identifier">_DYN_LINK</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Forces library "whatever" to be linked as a dll rather
|
||||
than a static library on Microsoft Windows: replace the <span class="emphasis"><em>WHATEVER</em></span>
|
||||
part of the macro name with the name of the library that you want
|
||||
to dynamically link to, for example use <code class="computeroutput"><span class="identifier">BOOST_DATE_TIME_DYN_LINK</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">BOOST_REGEX_DYN_LINK</span></code>
|
||||
etc (this macro is used to turn on <code class="computeroutput"><span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllimport</span><span class="special">)</span></code> modifiers, so that the compiler
|
||||
knows which symbols to look for in a dll rather than in a static
|
||||
library). Note that there may be some libraries that can only be
|
||||
statically linked (Boost.Test for example) and others which may
|
||||
only be dynamically linked (Boost.Thread for example), in these
|
||||
cases this macro is unsupported.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ALL_NO_LIB</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Tells the config system not to automatically select which libraries
|
||||
to link against. Normally if a compiler supports #pragma lib, then
|
||||
the correct library build variant will be automatically selected
|
||||
and linked against, simply by the act of including one of that
|
||||
library's headers. This macro turns that feature off.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_</span></code><span class="emphasis"><em>WHATEVER</em></span><code class="computeroutput"><span class="identifier">_NO_LIB</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Tells the config system not to automatically select which library
|
||||
to link against for library "whatever", replace <span class="emphasis"><em>WHATEVER</em></span>
|
||||
in the macro name with the name of the library; for example <code class="computeroutput"><span class="identifier">BOOST_DATE_TIME_NO_LIB</span></code> or <code class="computeroutput"><span class="identifier">BOOST_REGEX_NO_LIB</span></code>. Normally
|
||||
if a compiler supports <code class="computeroutput"><span class="preprocessor">#pragma</span>
|
||||
<span class="identifier">lib</span></code>, then the correct
|
||||
library build variant will be automatically selected and linked
|
||||
against, simply by the act of including one of that library's headers.
|
||||
This macro turns that feature off.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_LIB_DIAGNOSTIC</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Causes the auto-linking code to output diagnostic messages indicating
|
||||
the name of the library that is selected for linking.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_LIB_TOOLSET</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Overrides the name of the toolset part of the name of library being
|
||||
linked to; note if defined this must be defined to a quoted string
|
||||
literal, for example "abc".
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage" title="Advanced configuration usage">Advanced
|
||||
configuration usage</a>
|
||||
</h3></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration">Example
|
||||
1: creating our own frozen configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need">Example
|
||||
2: skipping files that you don't need</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration">Example
|
||||
3: using configure script to freeze the boost configuration</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
By setting various macros on the compiler command line or by editing <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>,
|
||||
the boost configuration setup can be optimised in a variety of ways.
|
||||
</p>
|
||||
<p>
|
||||
Boost's configuration is structured so that the user-configuration is included
|
||||
first (defaulting to <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
if <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code> is not
|
||||
defined). This sets up any user-defined policies, and gives the user-configuration
|
||||
a chance to influence what happens next.
|
||||
</p>
|
||||
<p>
|
||||
Next the compiler, standard library, and platform configuration files are
|
||||
included. These are included via macros (<code class="computeroutput"><span class="identifier">BOOST_COMPILER_CONFIG</span></code>
|
||||
etc, <a class="link" href="index.html#config_user_settable">see user settable macros</a>),
|
||||
and if the corresponding macro is undefined then a separate header that detects
|
||||
which compiler/standard library/platform is in use is included in order to
|
||||
set these. The config can be told to ignore these headers altogether if the
|
||||
corresponding <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro is set (for example <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
to disable including any compiler configuration file - <a class="link" href="index.html#config_user_settable">see
|
||||
user settable macros</a>).
|
||||
</p>
|
||||
<p>
|
||||
Finally the boost configuration header, includes <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>;
|
||||
this header contains any boiler plate configuration code - for example where
|
||||
one boost macro being set implies that another must be set also.
|
||||
</p>
|
||||
<p>
|
||||
The following usage examples represent just a few of the possibilities:
|
||||
</p>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration" title="Example 1: creating our own frozen configuration">Example
|
||||
1: creating our own frozen configuration</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
Lets suppose that we're building boost with Visual C++ 6, and STLport 4.0.
|
||||
Lets suppose also that we don't intend to update our compiler or standard
|
||||
library any time soon. In order to avoid breaking dependencies when we
|
||||
update boost, we may want to "freeze" our configuration headers,
|
||||
so that we only have to rebuild our project if the boost code itself has
|
||||
changed, and not because the boost config has been updated for more recent
|
||||
versions of Visual C++ or STLport. We'll start by realising that the configuration
|
||||
files in use are: <a href="../../../../boost/config/compiler/visualc.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">compiler</span><span class="special">/</span><span class="identifier">visualc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the compiler, <a href="../../../../boost/config/stdlib/stlport.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">stdlib</span><span class="special">/</span><span class="identifier">stlport</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the standard library, and
|
||||
<a href="../../../../boost/config/platform/win32.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">platform</span><span class="special">/</span><span class="identifier">win32</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the platform. Next we'll
|
||||
create our own private configuration directory: <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">mysetup</span><span class="special">/</span></code>, and copy the configuration files into
|
||||
there. Finally, open up <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
and edit the following defines:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_COMPILER_CONFIG</span> <span class="string">"boost/config/mysetup/visualc.hpp"</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_STDLIB_CONFIG</span> <span class="string">"boost/config/mysetup/stlport.hpp"</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_USER_CONFIG</span> <span class="string">"boost/config/mysetup/win32.hpp"</span>
|
||||
</pre>
|
||||
<p>
|
||||
Now when you use boost, its configuration header will go straight to our
|
||||
"frozen" versions, and ignore the default versions, you will
|
||||
now be insulated from any configuration changes when you update boost.
|
||||
This technique is also useful if you want to modify some of the boost configuration
|
||||
files; for example if you are working with a beta compiler release not
|
||||
yet supported by boost.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need" title="Example 2: skipping files that you don't need">Example
|
||||
2: skipping files that you don't need</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
Lets suppose that you're using boost with a compiler that is fully conformant
|
||||
with the standard; you're not interested in the fact that older versions
|
||||
of your compiler may have had bugs, because you know that your current
|
||||
version does not need any configuration macros setting. In a case like
|
||||
this, you can define <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
either on the command line, or in <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>,
|
||||
and miss out the compiler configuration header altogether (actually you
|
||||
miss out two headers, one which works out what the compiler is, and one
|
||||
that configures boost for it). This has two consequences: the first is
|
||||
that less code has to be compiled, and the second that you have removed
|
||||
a dependency on two boost headers.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration" title="Example 3: using configure script to freeze the boost configuration">Example
|
||||
3: using configure script to freeze the boost configuration</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
If you are working on a unix-like platform then you can use the configure
|
||||
script to generate a "frozen" configuration based on your current
|
||||
compiler setup - <a class="link" href="index.html#config_config_script">see using the configure
|
||||
script for more details</a>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration" title="Testing the boost configuration">Testing
|
||||
the boost configuration</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The boost configuration library provides a full set of regression test programs
|
||||
under the <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
<code class="computeroutput"><span class="identifier">test</span><span class="special">/</span></code>
|
||||
sub-directory:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
File
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Prints out a detailed description of your compiler/standard library/platform
|
||||
setup, plus your current boost configuration. The information provided
|
||||
by this program useful in setting up the boost configuration files.
|
||||
If you report that boost is incorrectly configured for your compiler/library/platform
|
||||
then please include the output from this program when reporting
|
||||
the changes required.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">config_test</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
A monolithic test program that includes most of the individual
|
||||
test cases. This provides a quick check to see if boost is correctly
|
||||
configured for your compiler/library/platform.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">limits_test</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Tests your standard library's <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code>
|
||||
implementation (or its boost provided replacement if <code class="computeroutput"><span class="identifier">BOOST_NO_LIMITS</span></code> is defined).
|
||||
This test file fails with most versions of numeric_limits, mainly
|
||||
due to the way that some compilers treat NAN's and infinity.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">no_</span><span class="special">*</span><span class="identifier">pass</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual compiler defect test files. Each of these should compile,
|
||||
if one does not then the corresponding <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro needs to be defined - see each test file for specific details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">no_</span><span class="special">*</span><span class="identifier">fail</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual compiler defect test files. Each of these should not
|
||||
compile, if one does then the corresponding <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro is defined when it need not be - see each test file for specific
|
||||
details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">has_</span><span class="special">*</span><span class="identifier">pass</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual feature test files. If one of these does not compile
|
||||
then the corresponding <code class="computeroutput"><span class="identifier">BOOST_HAS_XXX</span></code>
|
||||
macro is defined when it should not be - see each test file for
|
||||
specific details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">has_</span><span class="special">*</span><span class="identifier">fail</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual feature test files. If one of these does compile then
|
||||
the corresponding <code class="computeroutput"><span class="identifier">BOOST_HAS_XXX</span></code>
|
||||
macro can be safely defined - see each test file for specific details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
<p>
|
||||
Although you can run the configuration regression tests as individual test
|
||||
files, there are rather a lot of them, so there are a couple of shortcuts
|
||||
to help you out:
|
||||
</p>
|
||||
<p>
|
||||
If you have built the <a href="../../../../tools/regression/doc/index.html" target="_top">boost
|
||||
regression test driver</a>, then you can use this to produce a nice html
|
||||
formatted report of the results using the supplied test file.
|
||||
</p>
|
||||
<p>
|
||||
Alternatively you can run the configure script like this:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<code class="computeroutput"><span class="special">./</span><span class="identifier">configure</span>
|
||||
<span class="special">--</span><span class="identifier">enable</span><span class="special">-</span><span class="identifier">test</span></code>
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
in which case the script will test the current configuration rather than
|
||||
creating a new one from scratch.
|
||||
</p>
|
||||
<p>
|
||||
If you are reporting the results of these tests for a new platform/library/compiler
|
||||
then please include a log of the full compiler output, the output from <code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>, and the pass/fail test results.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"><p><small>Last revised: November 20, 2012 at 20:32:39 GMT</small></p></td>
|
||||
<td align="right"><div class="copyright-footer"></div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="boost_config/boost_macro_reference.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,62 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Acknowledgements</title>
|
||||
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Boost.Config">
|
||||
<link rel="prev" href="rationale.html" title="Rationale">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.acknowledgements"></a><a class="link" href="acknowledgements.html" title="Acknowledgements">Acknowledgements</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
Beman Dawes provided the original <code class="computeroutput"><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code> and
|
||||
part of this document.
|
||||
</p>
|
||||
<p>
|
||||
Vesa Karvonen provided a description of the principles (see <a class="link" href="rationale.html" title="Rationale">rationale</a>)
|
||||
and put together an early version of the current configuration setup.
|
||||
</p>
|
||||
<p>
|
||||
John Maddock put together the configuration current code, the test programs,
|
||||
the configuration script and the reference section of this document.
|
||||
</p>
|
||||
<p>
|
||||
Matias Capeletto converted the docs to quickbook format.
|
||||
</p>
|
||||
<p>
|
||||
Numerous boost members, past and present, have contributed fixes to boost's
|
||||
configuration.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
|
||||
Maddock<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,377 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Guidelines for Boost Authors</title>
|
||||
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Boost.Config">
|
||||
<link rel="prev" href="boost_macro_reference.html" title="Boost Macro Reference">
|
||||
<link rel="next" href="rationale.html" title="Rationale">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="boost_macro_reference.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.guidelines_for_boost_authors"></a><a class="link" href="guidelines_for_boost_authors.html" title="Guidelines for Boost Authors">Guidelines for
|
||||
Boost Authors</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings">Disabling
|
||||
Compiler Warnings</a></span></dt>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros">Adding
|
||||
New Defect Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros">Adding
|
||||
New Feature Test Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers">Modifying
|
||||
the Boost Configuration Headers</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
The <a href="../../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
header is used to pass configuration information to other boost files, allowing
|
||||
them to cope with platform dependencies such as arithmetic byte ordering, compiler
|
||||
pragmas, or compiler shortcomings. Without such configuration information,
|
||||
many current compilers would not work with the Boost libraries.
|
||||
</p>
|
||||
<p>
|
||||
Centralizing configuration information in this header reduces the number of
|
||||
files that must be modified when porting libraries to new platforms, or when
|
||||
compilers are updated. Ideally, no other files would have to be modified when
|
||||
porting to a new platform.
|
||||
</p>
|
||||
<p>
|
||||
Configuration headers are controversial because some view them as condoning
|
||||
broken compilers and encouraging non-standard subsets. Adding settings for
|
||||
additional platforms and maintaining existing settings can also be a problem.
|
||||
In other words, configuration headers are a necessary evil rather than a desirable
|
||||
feature. The boost config.hpp policy is designed to minimize the problems and
|
||||
maximize the benefits of a configuration header.
|
||||
</p>
|
||||
<p>
|
||||
Note that:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
Boost library implementers are not required to "<code class="computeroutput"><span class="preprocessor">#include</span>
|
||||
<span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>", and are not required in any
|
||||
way to support compilers that do not comply with the C++ Standard (ISO/IEC
|
||||
14882).
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If a library implementer wishes to support some non-conforming compiler,
|
||||
or to support some platform specific feature, "<code class="computeroutput"><span class="preprocessor">#include</span>
|
||||
<span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>" is the preferred way to obtain
|
||||
configuration information not available from the standard headers such
|
||||
as <code class="computeroutput"><span class="special"><</span><span class="identifier">climits</span><span class="special">></span></code>, etc.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If configuration information can be deduced from standard headers such
|
||||
as <code class="computeroutput"><span class="special"><</span><span class="identifier">climits</span><span class="special">></span></code>, use those standard headers rather
|
||||
than <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Boost files that use macros defined in <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
should have sensible, standard conforming, default behavior if the macro
|
||||
is not defined. This means that the starting point for porting <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code> to a new platform is simply to define
|
||||
nothing at all specific to that platform. In the rare case where there
|
||||
is no sensible default behavior, an #error message should describe the
|
||||
problem.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
If a Boost library implementer wants something added to <code class="computeroutput"><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code>,
|
||||
post a request on the Boost mailing list. There is no guarantee such a
|
||||
request will be honored; the intent is to limit the complexity of config.hpp.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The intent is to support only compilers which appear on their way to becoming
|
||||
C++ Standard compliant, and only recent releases of those compilers at
|
||||
that.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The intent is not to disable mainstream features now well-supported by
|
||||
the majority of compilers, such as namespaces, exceptions, RTTI, or templates.
|
||||
</li>
|
||||
</ul></div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.warnings"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings" title="Disabling Compiler Warnings">Disabling
|
||||
Compiler Warnings</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The header <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">warning_disable</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
can be used to disable certain compiler warnings that are hard or impossible
|
||||
to otherwise remove.
|
||||
</p>
|
||||
<p>
|
||||
Note that:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
This header <span class="bold"><strong><span class="emphasis"><em>should never be included
|
||||
by another Boost header</em></span></strong></span>, it should only ever be
|
||||
used by a library source file or a test case.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
The header should be included <span class="bold"><strong><span class="emphasis"><em>before
|
||||
you include any other header</em></span></strong></span>.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
This header only disables warnings that are hard or impossible to otherwise
|
||||
deal with, and which are typically emitted by one compiler only, or in
|
||||
one compilers own standard library headers.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Currently it disables the following warnings:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
Compiler
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Warning
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
Visual C++ 8 and later
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
<a href="http://msdn2.microsoft.com/en-us/library/ttcz0bys(VS.80).aspx" target="_top">C4996</a>:
|
||||
Error 'function': was declared deprecated
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
Intel C++
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Warning 1786: relates to the use of "deprecated" standard
|
||||
library functions rather like C4996 in Visual C++.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.adding_new_defect_macros"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros" title="Adding New Defect Macros">Adding
|
||||
New Defect Macros</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
When you need to add a new defect macro - either to fix a problem with an
|
||||
existing library, or when adding a new library - distil the issue down to
|
||||
a simple test case; often, at this point other (possibly better) workarounds
|
||||
may become apparent. Secondly always post the test case code to the boost
|
||||
mailing list and invite comments; remember that C++ is complex and that sometimes
|
||||
what may appear a defect, may in fact turn out to be a problem with the authors
|
||||
understanding of the standard.
|
||||
</p>
|
||||
<p>
|
||||
When you name the macro, follow the <code class="computeroutput"><span class="identifier">BOOST_NO_</span></code><span class="emphasis"><em>SOMETHING</em></span>
|
||||
naming convention, so that it's obvious that this is a macro reporting a
|
||||
defect.
|
||||
</p>
|
||||
<p>
|
||||
Finally, add the test program to the regression tests. You will need to place
|
||||
the test case in a <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code>
|
||||
file with the following comments near the top:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">// MACRO: BOOST_NO_FOO</span>
|
||||
<span class="comment">// TITLE: foo</span>
|
||||
<span class="comment">// DESCRIPTION: If the compiler fails to support foo</span>
|
||||
</pre>
|
||||
<p>
|
||||
These comments are processed by the autoconf script, so make sure the format
|
||||
follows the one given. The file should be named "<code class="computeroutput"><span class="identifier">boost_no_foo</span><span class="special">.</span><span class="identifier">ipp</span></code>",
|
||||
where foo is the defect description - try and keep the file name under the
|
||||
Mac 30 character filename limit though. You will also need to provide a function
|
||||
prototype "<code class="computeroutput"><span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span></code>" that is declared in a namespace with
|
||||
the same name as the macro, but in all lower case, and which returns zero
|
||||
on success:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost_no_foo</span> <span class="special">{</span>
|
||||
<span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// test code goes here:</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Once the test code is in place in libs/config/test, updating the configuration
|
||||
test system proceeds as:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">tools</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span></code>.
|
||||
This generates the <code class="computeroutput"><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
file test cases from the <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code> file, updates the libs/config/test/all/Jamfile.v2,
|
||||
<code class="computeroutput"><span class="identifier">config_test</span><span class="special">.</span><span class="identifier">cpp</span></code> and <code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>.<br>
|
||||
<br>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">all</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span>
|
||||
</code><span class="emphasis"><em>MACRONAME<code class="computeroutput"> <span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>,
|
||||
where <span class="emphasis"><em>MACRONAME</em></span> is the name of the new macro, and
|
||||
<span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span> is a space separated
|
||||
list of compilers to test with.<br> <br> The xxx_pass_test and the
|
||||
xxx_fail_test <span class="bold"><strong>should both report <code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code></strong></span>.<br> <br> If <span class="emphasis"><em>MACRONAME</em></span>
|
||||
is not defined when it should be defined, xxx_pass_test will not report
|
||||
<code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code>. If <span class="emphasis"><em>MACRONAME</em></span>
|
||||
is defined when it should not be defined, xxx_fail_test will not report
|
||||
<code class="computeroutput"><span class="special">**</span><span class="identifier">passed</span><span class="special">**</span></code>.<br> <br>
|
||||
</li>
|
||||
<li class="listitem">
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">test</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span>
|
||||
<span class="identifier">config_info</span> <span class="identifier">config_test</span>
|
||||
</code><span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>.
|
||||
<code class="computeroutput"><span class="identifier">config_info</span></code> should build
|
||||
and run cleanly for all the compilers in <span class="emphasis"><em><code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code></em></span>
|
||||
while <code class="computeroutput"><span class="identifier">config_test</span></code> should
|
||||
fail for those that have the defect, and pass for those that do not.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Then you should:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
Define the defect macro in those config headers that require it.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Document the macro in this documentation (please do not forget this step!!)
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Commit everything.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Keep an eye on the regression tests for new failures in Boost.Config
|
||||
caused by the addition.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Start using the macro.
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros" title="Adding New Feature Test Macros">Adding
|
||||
New Feature Test Macros</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
When you need to add a macro that describes a feature that the standard does
|
||||
not require, follow the convention for adding a new defect macro (above),
|
||||
but call the macro <code class="computeroutput"><span class="identifier">BOOST_HAS_FOO</span></code>,
|
||||
and name the test file "<code class="computeroutput"><span class="identifier">boost_has_foo</span><span class="special">.</span><span class="identifier">ipp</span></code>".
|
||||
Try not to add feature test macros unnecessarily, if there is a platform
|
||||
specific macro that can already be used (for example <code class="computeroutput"><span class="identifier">_WIN32</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">__BEOS__</span></code>, or <code class="computeroutput"><span class="identifier">__linux</span></code>) to identify the feature then use
|
||||
that. Try to keep the macro to a feature group, or header name, rather than
|
||||
one specific API (for example <code class="computeroutput"><span class="identifier">BOOST_HAS_NL_TYPES_H</span></code>
|
||||
rather than <code class="computeroutput"><span class="identifier">BOOST_HAS_CATOPEN</span></code>).
|
||||
If the macro describes a POSIX feature group, then add boilerplate code to
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>
|
||||
to auto-detect the feature where possible (if you are wondering why we can't
|
||||
use POSIX feature test macro directly, remember that many of these features
|
||||
can be added by third party libraries, and are not therefore identified inside
|
||||
<code class="computeroutput"><span class="special"><</span><span class="identifier">unistd</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code>).
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers" title="Modifying the Boost Configuration Headers">Modifying
|
||||
the Boost Configuration Headers</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The aim of boost's configuration setup is that the configuration headers
|
||||
should be relatively stable - a boost user should not have to recompile their
|
||||
code just because the configuration for some compiler that they're not interested
|
||||
in has changed. Separating the configuration into separate compiler/standard
|
||||
library/platform sections provides for part of this stability, but boost
|
||||
authors require some amount of restraint as well, in particular:
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
should never change, don't alter this file.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
is included by default, don't add extra code to this file unless you have
|
||||
to. If you do, please remember to update <a href="../../../tools/configure.in" target="_top">libs/config/tools/configure.in</a>
|
||||
as well.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>
|
||||
is always included so be careful about modifying this file as it breaks dependencies
|
||||
for everyone. This file should include only "boilerplate" configuration
|
||||
code, and generally should change only when new macros are added.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/select_compiler_config.hpp" target="_top"><boost/config/select_compiler_config.hpp></a>,
|
||||
<a href="../../../../../boost/config/select_platform_config.hpp" target="_top"><boost/config/select_platform_config.hpp></a>
|
||||
and <a href="../../../../../boost/config/select_stdlib_config.hpp" target="_top"><boost/config/select_stdlib_config.hpp></a>
|
||||
are included by default and should change only if support for a new compiler/standard
|
||||
library/platform is added.
|
||||
</p>
|
||||
<p>
|
||||
The compiler/platform/standard library selection code is set up so that unknown
|
||||
platforms are ignored and assumed to be fully standards compliant - this
|
||||
gives unknown platforms a "sporting chance" of working "as
|
||||
is" even without running the configure script.
|
||||
</p>
|
||||
<p>
|
||||
When adding or modifying the individual mini-configs, assume that future,
|
||||
as yet unreleased versions of compilers, have all the defects of the current
|
||||
version. Although this is perhaps unnecessarily pessimistic, it cuts down
|
||||
on the maintenance of these files, and experience suggests that pessimism
|
||||
is better placed than optimism here!
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
|
||||
Maddock<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="boost_macro_reference.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
124
boost_1_52_0/libs/config/doc/html/boost_config/rationale.html
Normal file
124
boost_1_52_0/libs/config/doc/html/boost_config/rationale.html
Normal file
@@ -0,0 +1,124 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Rationale</title>
|
||||
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="../index.html" title="Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Boost.Config">
|
||||
<link rel="prev" href="guidelines_for_boost_authors.html" title="Guidelines for Boost Authors">
|
||||
<link rel="next" href="acknowledgements.html" title="Acknowledgements">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="guidelines_for_boost_authors.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.rationale"></a><a class="link" href="rationale.html" title="Rationale">Rationale</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="rationale.html#boost_config.rationale.the_problem">The problem</a></span></dt>
|
||||
<dt><span class="section"><a href="rationale.html#boost_config.rationale.the_solution">The solution</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
The problem with many traditional "textbook" implementations of configuration
|
||||
headers (where all the configuration options are in a single "monolithic"
|
||||
header) is that they violate certain fundamental software engineering principles
|
||||
which would have the effect of making boost more fragile, more difficult to
|
||||
maintain and more difficult to use safely. You can find a description of the
|
||||
principles from the <a href="http://www.objectmentor.com/resources/articles/Principles_and_Patterns.pdf" target="_top">following
|
||||
article</a>.
|
||||
</p>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.rationale.the_problem"></a><a class="link" href="rationale.html#boost_config.rationale.the_problem" title="The problem">The problem</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Consider a situation in which you are concurrently developing on multiple
|
||||
platforms. Then consider adding a new platform or changing the platform definitions
|
||||
of an existing platform. What happens? Everything, and this does literally
|
||||
mean everything, recompiles. Isn't it quite absurd that adding a new platform,
|
||||
which has absolutely nothing to do with previously existing platforms, means
|
||||
that all code on all existing platforms needs to be recompiled?
|
||||
</p>
|
||||
<p>
|
||||
Effectively, there is an imposed physical dependency between platforms that
|
||||
have nothing to do with each other. Essentially, the traditional solution
|
||||
employed by configuration headers does not conform to the Open-Closed Principle:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<span class="bold"><strong>"A module should be open for extension but closed
|
||||
for modification."</strong></span>
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
Extending a traditional configuration header implies modifying existing code.
|
||||
</p>
|
||||
<p>
|
||||
Furthermore, consider the complexity and fragility of the platform detection
|
||||
code. What if a simple change breaks the detection on some minor platform?
|
||||
What if someone accidentally or on purpose (as a workaround for some other
|
||||
problem) defines some platform dependent macros that are used by the detection
|
||||
code? A traditional configuration header is one of the most volatile headers
|
||||
of the entire library, and more stable elements of Boost would depend on
|
||||
it. This violates the Stable Dependencies Principle:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<span class="bold"><strong>"Depend in the direction of stability."</strong></span>
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
After even a minor change to a traditional configuration header on one minor
|
||||
platform, almost everything on every platform should be tested if we follow
|
||||
sound software engineering practice.
|
||||
</p>
|
||||
<p>
|
||||
Another important issue is that it is not always possible to submit changes
|
||||
to <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>.
|
||||
Some boost users are currently working on platforms using tools and libraries
|
||||
that are under strict Non-Disclosure Agreements. In this situation it is
|
||||
impossible to submit changes to a traditional monolithic configuration header,
|
||||
instead some method by which the user can insert their own configuration
|
||||
code must be provided.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.rationale.the_solution"></a><a class="link" href="rationale.html#boost_config.rationale.the_solution" title="The solution">The solution</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The approach taken by boost's configuration headers is to separate configuration
|
||||
into three orthogonal parts: the compiler, the standard library and the platform.
|
||||
Each compiler/standard library/platform gets its own mini-configuration header,
|
||||
so that changes to one compiler's configuration (for example) does not affect
|
||||
other compilers. In addition there are measures that can be taken both to
|
||||
omit the compiler/standard library/platform detection code (so that adding
|
||||
support to a new platform does not break dependencies), or to freeze the
|
||||
configuration completely; providing almost complete protection against dependency
|
||||
changes.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
|
||||
Maddock<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="guidelines_for_boost_authors.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
960
boost_1_52_0/libs/config/doc/html/index.html
Normal file
960
boost_1_52_0/libs/config/doc/html/index.html
Normal file
@@ -0,0 +1,960 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Boost.Config</title>
|
||||
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||||
<link rel="home" href="index.html" title="Boost.Config">
|
||||
<link rel="next" href="boost_config/boost_macro_reference.html" title="Boost Macro Reference">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="boost_config/boost_macro_reference.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
|
||||
<div class="article">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div><h2 class="title">
|
||||
<a name="config"></a>Boost.Config</h2></div>
|
||||
<div><div class="authorgroup"><div class="author"><h3 class="author">
|
||||
<span class="firstname">Vesa Karvonen, John Maddock</span> <span class="surname">Beman Dawes</span>
|
||||
</h3></div></div></div>
|
||||
<div><p class="copyright">Copyright © 2001-2007 Beman Dawes, Vesa Karvonen, John
|
||||
Maddock</p></div>
|
||||
<div><div class="legalnotice">
|
||||
<a name="config.legal"></a><p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></div>
|
||||
</div>
|
||||
<hr>
|
||||
</div>
|
||||
<div class="toc">
|
||||
<p><b>Table of Contents</b></p>
|
||||
<dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform">Configuring
|
||||
Boost for Your Platform</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration">Using
|
||||
the default boost configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header">The
|
||||
<boost/config.hpp> header</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script">Using
|
||||
the configure script</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options">User
|
||||
settable options</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage">Advanced
|
||||
configuration usage</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration">Testing
|
||||
the boost configuration</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html">Boost Macro Reference</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_c__03_defects">Macros
|
||||
that describe C++03 defects</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_optional_features">Macros
|
||||
that describe optional features</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_possible_c___future_features">Macros
|
||||
that describe possible C++ future features</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_c__11_features_not_supported">Macros
|
||||
that describe C++11 features not supported</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_allow_use_of_c__11_features_with_c__03_compilers">Macros
|
||||
that allow use of C++11 features with C++03 compilers</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_helper_macros">Boost
|
||||
Helper Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_informational_macros">Boost
|
||||
Informational Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_deprecated_macros">Boost
|
||||
Deprecated Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_for_libraries_with_separate_source_code">Macros
|
||||
for libraries with separate source code</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html">Guidelines for
|
||||
Boost Authors</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings">Disabling
|
||||
Compiler Warnings</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros">Adding
|
||||
New Defect Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros">Adding
|
||||
New Feature Test Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers">Modifying
|
||||
the Boost Configuration Headers</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html">Rationale</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html#boost_config.rationale.the_problem">The problem</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html#boost_config.rationale.the_solution">The solution</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/acknowledgements.html">Acknowledgements</a></span></dt>
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.configuring_boost_for_your_platform"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform" title="Configuring Boost for Your Platform">Configuring
|
||||
Boost for Your Platform</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration">Using
|
||||
the default boost configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header">The
|
||||
<boost/config.hpp> header</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script">Using
|
||||
the configure script</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options">User
|
||||
settable options</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage">Advanced
|
||||
configuration usage</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration">Testing
|
||||
the boost configuration</a></span></dt>
|
||||
</dl></div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration" title="Using the default boost configuration">Using
|
||||
the default boost configuration</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Boost comes already configured for most common compilers and platforms; you
|
||||
should be able to use boost "as is". Since the compiler is configured
|
||||
separately from the standard library, the default configuration should work
|
||||
even if you replace the compiler's standard library with a third-party standard
|
||||
library (like <a href="http://stlport.sourceforge.net" target="_top">STLport</a>).
|
||||
</p>
|
||||
<p>
|
||||
Using boost "as is" without trying to reconfigure is the recommended
|
||||
method for using boost. You can, however, run the configure script if you
|
||||
want to, and there are regression tests provided that allow you to test the
|
||||
current boost configuration with your particular compiler setup.
|
||||
</p>
|
||||
<p>
|
||||
Boost library users can request support for additional compilers or platforms
|
||||
by visiting our <a href="https://svn.boost.org/trac/boost/newticket" target="_top">Trac</a>
|
||||
and submitting a support request.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header" title="The <boost/config.hpp> header">The
|
||||
<boost/config.hpp> header</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Boost library implementations access configuration macros via
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <a href="../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
</pre>
|
||||
<p>
|
||||
While Boost library users are not required to include that file directly,
|
||||
or use those configuration macros, such use is acceptable. The configuration
|
||||
macros are documented as to their purpose, usage, and limitations which makes
|
||||
them usable by both Boost library and user code.
|
||||
</p>
|
||||
<p>
|
||||
Boost <a class="link" href="boost_config/boost_macro_reference.html#config_info_macros">informational</a> or <a class="link" href="boost_config/boost_macro_reference.html#config_helpers">helper</a>
|
||||
macros are designed for use by Boost users as well as for our own internal
|
||||
use. Note however, that the <a class="link" href="boost_config/boost_macro_reference.html#config_features">feature test</a>
|
||||
and <a class="link" href="boost_config/boost_macro_reference.html#config_defects">defect test</a> macros were designed
|
||||
for internal use by Boost libraries, not user code, so they can change at
|
||||
any time (though no gratuitous changes are made to them). Boost library problems
|
||||
resulting from changes to the configuration macros are caught by the Boost
|
||||
regression tests, so the Boost libraries are updated to account for those
|
||||
changes. By contrast, Boost library user code can be adversely affected by
|
||||
changes to the macros without warning. The best way to keep abreast of changes
|
||||
to the macros used in user code is to monitor the discussions on the Boost
|
||||
developers list.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.using_the_configure_script"></a><a name="config_config_script"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script" title="Using the configure script">Using
|
||||
the configure script</a>
|
||||
</h3></div></div></div>
|
||||
<div class="important"><table border="0" summary="Important">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../doc/src/images/important.png"></td>
|
||||
<th align="left">Important</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
This configure script only sets up the Boost headers for use with a particular
|
||||
compiler. It has no effect on Boost.Build, or how the libraries are built.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
If you know that boost is incorrectly configured for your particular setup,
|
||||
and you are on a UNIX like platform, then you may want to try and improve
|
||||
things by running the boost configure script. From a shell command prompt
|
||||
you will need to cd into <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
and type:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<code class="computeroutput"><span class="identifier">sh</span> <span class="special">./</span><span class="identifier">configure</span></code>
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
you will see a list of the items being checked as the script works its way
|
||||
through the regression tests. Note that the configure script only really
|
||||
auto-detects your compiler if it's called g++, c++ or CC. If you are using
|
||||
some other compiler you will need to set one or more of the following environment
|
||||
variables:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
Variable
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
CXX
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The name of the compiler, for example <code class="computeroutput"><span class="identifier">c</span><span class="special">++</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
CXXFLAGS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The compiler flags to use, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">O2</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
LDFLAGS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The linker flags to use, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">L</span><span class="special">/</span><span class="identifier">mypath</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
LIBS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Any libraries to link in, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">lpthread</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
<p>
|
||||
For example to run the configure script with HP aCC, you might use something
|
||||
like:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">export</span> <span class="identifier">CXX</span><span class="special">=</span><span class="string">"aCC"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">CXXFLAGS</span><span class="special">=</span><span class="string">"-Aa -DAportable -D__HPACC_THREAD_SAFE_RB_TREE \
|
||||
-DRWSTD_MULTI_THREAD -DRW_MULTI_THREAD -D_REENTRANT -D_THREAD_SAFE"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">LDFLAGS</span><span class="special">=</span><span class="string">"-DAportable"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">LIBS</span><span class="special">=</span><span class="string">"-lpthread"</span>
|
||||
<span class="identifier">sh</span> <span class="special">./</span><span class="identifier">configure</span>
|
||||
</pre>
|
||||
<p>
|
||||
However you run the configure script, when it finishes you will find a new
|
||||
header -<code class="computeroutput"><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span></code>- located in the <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
directory. <span class="bold"><strong>Note that configure does not install this
|
||||
header into your boost include path by default</strong></span>. This header contains
|
||||
all the options generated by the configure script, plus a header-section
|
||||
that contains the user settable options from the default version of <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
(located under <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>).
|
||||
There are two ways you can use this header:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||||
<li class="listitem">
|
||||
<span class="bold"><strong>Option 1:</strong></span> copy the header into <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code> so that it replaces the default user.hpp
|
||||
provided by boost. This option allows only one configure-generated setup;
|
||||
boost developers should avoid this option, as it incurs the danger of
|
||||
accidentally committing a configure-modified <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
to the svn repository (something you will not be thanked for!).
|
||||
</li>
|
||||
<li class="listitem">
|
||||
<span class="bold"><strong>Option 2:</strong></span> give the header a more memorable
|
||||
name, and place it somewhere convenient; then, define the macro <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code> to point to it. For
|
||||
example create a new sub-directory <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code> <code class="computeroutput"><span class="identifier">user</span><span class="special">/</span></code>, and copy the header there; for example
|
||||
as <code class="computeroutput"><span class="identifier">multithread</span><span class="special">-</span><span class="identifier">gcc</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code>. Then, when compiling add the command
|
||||
line option: <code class="computeroutput"><span class="special">-</span><span class="identifier">DBOOST_USER_CONFIG</span><span class="special">=</span><span class="string">"<boost/config/user/multithread-gcc-config.hpp>"</span></code>,
|
||||
and boost will use the new configuration header. This option allows you
|
||||
to generate more than one configuration header, and to keep them separate
|
||||
from the boost source - so that updates to the source do not interfere
|
||||
with your configuration.
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.user_settable_options"></a><a name="config_user_settable"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options" title="User settable options">User
|
||||
settable options</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
There are some configuration-options that represent user choices, rather
|
||||
than compiler defects or platform specific options. These are listed in
|
||||
<code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
and at the start of a configure-generated <code class="computeroutput"><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span></code> header.
|
||||
You can define these on the command line, or by editing <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>, they are listed in the following table:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
Macro
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the user configuration
|
||||
file to include prior to any boost configuration files. When not
|
||||
defined, defaults to <a href="../../../../boost/config/user.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_COMPILER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the compiler configuration
|
||||
file to use. Defining this cuts out the compiler selection logic,
|
||||
and eliminates the dependency on the header containing that logic.
|
||||
For example if you are using gcc, then you could define BOOST_COMPILER_CONFIG
|
||||
to <a href="../../../../boost/config/compiler/gcc.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">compiler</span><span class="special">/</span><span class="identifier">gcc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_STDLIB_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the standard library
|
||||
configuration file to use. Defining this cuts out the standard
|
||||
library selection logic, and eliminates the dependency on the header
|
||||
containing that logic. For example if you are using STLport, then
|
||||
you could define <code class="computeroutput"><span class="identifier">BOOST_STDLIB_CONFIG</span></code>
|
||||
to <a href="../../../../boost/config/stdlib/stlport.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">stdlib</span><span class="special">/</span><span class="identifier">stlport</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_PLATFORM_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the platform configuration
|
||||
file to use. Defining this cuts out the platform selection logic,
|
||||
and eliminates the dependency on the header containing that logic.
|
||||
For example if you are compiling on linux, then you could define
|
||||
<code class="computeroutput"><span class="identifier">BOOST_PLATFORM_CONFIG</span></code>
|
||||
to <a href="../../../../boost/config/platform/linux.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">platform</span><span class="special">/</span><span class="identifier">linux</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no compiler configuration file is selected or included,
|
||||
define when the compiler is fully conformant with the standard,
|
||||
or where the user header (see <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>),
|
||||
has had any options necessary added to it, for example by an autoconf
|
||||
generated configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_STDLIB_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no standard library configuration file is selected
|
||||
or included, define when the standard library is fully conformant
|
||||
with the standard, or where the user header (see <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>), has had any
|
||||
options necessary added to it, for example by an autoconf generated
|
||||
configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_PLATFORM_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no platform configuration file is selected or included,
|
||||
define when the platform is fully conformant with the standard
|
||||
(and has no useful extra features), or where the user header (see
|
||||
<code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>),
|
||||
has had any options necessary added to it, for example by an autoconf
|
||||
generated configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Equivalent to defining all of <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_STDLIB_CONFIG</span></code>
|
||||
and <code class="computeroutput"><span class="identifier">BOOST_NO_PLATFORM_CONFIG</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_STRICT_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The normal behavior for compiler versions that are newer than the
|
||||
last known version, is to assume that they have all the same defects
|
||||
as the last known version. By setting this define, then compiler
|
||||
versions that are newer than the last known version are assumed
|
||||
to be fully conforming with the standard. This is probably most
|
||||
useful for boost developers or testers, and for those who want
|
||||
to use boost to test beta compiler versions.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ASSERT_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When this flag is set, if the config finds anything unknown, then
|
||||
it will stop with a #error rather than continue. Boost regression
|
||||
testers should set this define, as should anyone who wants to quickly
|
||||
check whether boost is supported on their platform.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_THREADS</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, disables threading support, even if the compiler
|
||||
in its current translation mode supports multiple threads.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_WIN32</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, disables the use of Win32 specific API's, even when
|
||||
these are available. Also has the effect of setting <code class="computeroutput"><span class="identifier">BOOST_DISABLE_THREADS</span></code> unless
|
||||
<code class="computeroutput"><span class="identifier">BOOST_HAS_PTHREADS</span></code>
|
||||
is set. This option may be set automatically by the config system
|
||||
when it detects that the compiler is in "strict mode".
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_ABI_HEADERS</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Stops boost headers from including any prefix/suffix headers that
|
||||
normally control things like struct packing and alignment.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ABI_PREFIX</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
A prefix header to include in place of whatever boost.config would
|
||||
normally select, any replacement should set up struct packing and
|
||||
alignment options as required.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ABI_SUFFIX</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
A suffix header to include in place of whatever boost.config would
|
||||
normally select, any replacement should undo the effects of the
|
||||
prefix header.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ALL_DYN_LINK</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Forces all libraries that have separate source, to be linked as
|
||||
dll's rather than static libraries on Microsoft Windows (this macro
|
||||
is used to turn on <code class="computeroutput"><span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllimport</span><span class="special">)</span></code> modifiers, so that the compiler
|
||||
knows which symbols to look for in a dll rather than in a static
|
||||
library). Note that there may be some libraries that can only be
|
||||
statically linked (Boost.Test for example) and others which may
|
||||
only be dynamically linked (Boost.Thread for example), in these
|
||||
cases this macro has no effect.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_</span></code><span class="emphasis"><em>WHATEVER</em></span><code class="computeroutput"><span class="identifier">_DYN_LINK</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Forces library "whatever" to be linked as a dll rather
|
||||
than a static library on Microsoft Windows: replace the <span class="emphasis"><em>WHATEVER</em></span>
|
||||
part of the macro name with the name of the library that you want
|
||||
to dynamically link to, for example use <code class="computeroutput"><span class="identifier">BOOST_DATE_TIME_DYN_LINK</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">BOOST_REGEX_DYN_LINK</span></code>
|
||||
etc (this macro is used to turn on <code class="computeroutput"><span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllimport</span><span class="special">)</span></code> modifiers, so that the compiler
|
||||
knows which symbols to look for in a dll rather than in a static
|
||||
library). Note that there may be some libraries that can only be
|
||||
statically linked (Boost.Test for example) and others which may
|
||||
only be dynamically linked (Boost.Thread for example), in these
|
||||
cases this macro is unsupported.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ALL_NO_LIB</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Tells the config system not to automatically select which libraries
|
||||
to link against. Normally if a compiler supports #pragma lib, then
|
||||
the correct library build variant will be automatically selected
|
||||
and linked against, simply by the act of including one of that
|
||||
library's headers. This macro turns that feature off.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_</span></code><span class="emphasis"><em>WHATEVER</em></span><code class="computeroutput"><span class="identifier">_NO_LIB</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Tells the config system not to automatically select which library
|
||||
to link against for library "whatever", replace <span class="emphasis"><em>WHATEVER</em></span>
|
||||
in the macro name with the name of the library; for example <code class="computeroutput"><span class="identifier">BOOST_DATE_TIME_NO_LIB</span></code> or <code class="computeroutput"><span class="identifier">BOOST_REGEX_NO_LIB</span></code>. Normally
|
||||
if a compiler supports <code class="computeroutput"><span class="preprocessor">#pragma</span>
|
||||
<span class="identifier">lib</span></code>, then the correct
|
||||
library build variant will be automatically selected and linked
|
||||
against, simply by the act of including one of that library's headers.
|
||||
This macro turns that feature off.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_LIB_DIAGNOSTIC</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Causes the auto-linking code to output diagnostic messages indicating
|
||||
the name of the library that is selected for linking.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_LIB_TOOLSET</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Overrides the name of the toolset part of the name of library being
|
||||
linked to; note if defined this must be defined to a quoted string
|
||||
literal, for example "abc".
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage" title="Advanced configuration usage">Advanced
|
||||
configuration usage</a>
|
||||
</h3></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration">Example
|
||||
1: creating our own frozen configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need">Example
|
||||
2: skipping files that you don't need</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration">Example
|
||||
3: using configure script to freeze the boost configuration</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
By setting various macros on the compiler command line or by editing <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>,
|
||||
the boost configuration setup can be optimised in a variety of ways.
|
||||
</p>
|
||||
<p>
|
||||
Boost's configuration is structured so that the user-configuration is included
|
||||
first (defaulting to <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
if <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code> is not
|
||||
defined). This sets up any user-defined policies, and gives the user-configuration
|
||||
a chance to influence what happens next.
|
||||
</p>
|
||||
<p>
|
||||
Next the compiler, standard library, and platform configuration files are
|
||||
included. These are included via macros (<code class="computeroutput"><span class="identifier">BOOST_COMPILER_CONFIG</span></code>
|
||||
etc, <a class="link" href="index.html#config_user_settable">see user settable macros</a>),
|
||||
and if the corresponding macro is undefined then a separate header that detects
|
||||
which compiler/standard library/platform is in use is included in order to
|
||||
set these. The config can be told to ignore these headers altogether if the
|
||||
corresponding <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro is set (for example <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
to disable including any compiler configuration file - <a class="link" href="index.html#config_user_settable">see
|
||||
user settable macros</a>).
|
||||
</p>
|
||||
<p>
|
||||
Finally the boost configuration header, includes <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>;
|
||||
this header contains any boiler plate configuration code - for example where
|
||||
one boost macro being set implies that another must be set also.
|
||||
</p>
|
||||
<p>
|
||||
The following usage examples represent just a few of the possibilities:
|
||||
</p>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration" title="Example 1: creating our own frozen configuration">Example
|
||||
1: creating our own frozen configuration</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
Lets suppose that we're building boost with Visual C++ 6, and STLport 4.0.
|
||||
Lets suppose also that we don't intend to update our compiler or standard
|
||||
library any time soon. In order to avoid breaking dependencies when we
|
||||
update boost, we may want to "freeze" our configuration headers,
|
||||
so that we only have to rebuild our project if the boost code itself has
|
||||
changed, and not because the boost config has been updated for more recent
|
||||
versions of Visual C++ or STLport. We'll start by realising that the configuration
|
||||
files in use are: <a href="../../../../boost/config/compiler/visualc.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">compiler</span><span class="special">/</span><span class="identifier">visualc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the compiler, <a href="../../../../boost/config/stdlib/stlport.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">stdlib</span><span class="special">/</span><span class="identifier">stlport</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the standard library, and
|
||||
<a href="../../../../boost/config/platform/win32.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">platform</span><span class="special">/</span><span class="identifier">win32</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the platform. Next we'll
|
||||
create our own private configuration directory: <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">mysetup</span><span class="special">/</span></code>, and copy the configuration files into
|
||||
there. Finally, open up <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
and edit the following defines:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_COMPILER_CONFIG</span> <span class="string">"boost/config/mysetup/visualc.hpp"</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_STDLIB_CONFIG</span> <span class="string">"boost/config/mysetup/stlport.hpp"</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_USER_CONFIG</span> <span class="string">"boost/config/mysetup/win32.hpp"</span>
|
||||
</pre>
|
||||
<p>
|
||||
Now when you use boost, its configuration header will go straight to our
|
||||
"frozen" versions, and ignore the default versions, you will
|
||||
now be insulated from any configuration changes when you update boost.
|
||||
This technique is also useful if you want to modify some of the boost configuration
|
||||
files; for example if you are working with a beta compiler release not
|
||||
yet supported by boost.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need" title="Example 2: skipping files that you don't need">Example
|
||||
2: skipping files that you don't need</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
Lets suppose that you're using boost with a compiler that is fully conformant
|
||||
with the standard; you're not interested in the fact that older versions
|
||||
of your compiler may have had bugs, because you know that your current
|
||||
version does not need any configuration macros setting. In a case like
|
||||
this, you can define <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
either on the command line, or in <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>,
|
||||
and miss out the compiler configuration header altogether (actually you
|
||||
miss out two headers, one which works out what the compiler is, and one
|
||||
that configures boost for it). This has two consequences: the first is
|
||||
that less code has to be compiled, and the second that you have removed
|
||||
a dependency on two boost headers.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration" title="Example 3: using configure script to freeze the boost configuration">Example
|
||||
3: using configure script to freeze the boost configuration</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
If you are working on a unix-like platform then you can use the configure
|
||||
script to generate a "frozen" configuration based on your current
|
||||
compiler setup - <a class="link" href="index.html#config_config_script">see using the configure
|
||||
script for more details</a>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration"></a><a class="link" href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration" title="Testing the boost configuration">Testing
|
||||
the boost configuration</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The boost configuration library provides a full set of regression test programs
|
||||
under the <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
<code class="computeroutput"><span class="identifier">test</span><span class="special">/</span></code>
|
||||
sub-directory:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
File
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Prints out a detailed description of your compiler/standard library/platform
|
||||
setup, plus your current boost configuration. The information provided
|
||||
by this program useful in setting up the boost configuration files.
|
||||
If you report that boost is incorrectly configured for your compiler/library/platform
|
||||
then please include the output from this program when reporting
|
||||
the changes required.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">config_test</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
A monolithic test program that includes most of the individual
|
||||
test cases. This provides a quick check to see if boost is correctly
|
||||
configured for your compiler/library/platform.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">limits_test</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Tests your standard library's <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code>
|
||||
implementation (or its boost provided replacement if <code class="computeroutput"><span class="identifier">BOOST_NO_LIMITS</span></code> is defined).
|
||||
This test file fails with most versions of numeric_limits, mainly
|
||||
due to the way that some compilers treat NAN's and infinity.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">no_</span><span class="special">*</span><span class="identifier">pass</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual compiler defect test files. Each of these should compile,
|
||||
if one does not then the corresponding <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro needs to be defined - see each test file for specific details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">no_</span><span class="special">*</span><span class="identifier">fail</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual compiler defect test files. Each of these should not
|
||||
compile, if one does then the corresponding <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro is defined when it need not be - see each test file for specific
|
||||
details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">has_</span><span class="special">*</span><span class="identifier">pass</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual feature test files. If one of these does not compile
|
||||
then the corresponding <code class="computeroutput"><span class="identifier">BOOST_HAS_XXX</span></code>
|
||||
macro is defined when it should not be - see each test file for
|
||||
specific details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">has_</span><span class="special">*</span><span class="identifier">fail</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual feature test files. If one of these does compile then
|
||||
the corresponding <code class="computeroutput"><span class="identifier">BOOST_HAS_XXX</span></code>
|
||||
macro can be safely defined - see each test file for specific details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
<p>
|
||||
Although you can run the configuration regression tests as individual test
|
||||
files, there are rather a lot of them, so there are a couple of shortcuts
|
||||
to help you out:
|
||||
</p>
|
||||
<p>
|
||||
If you have built the <a href="../../../../tools/regression/doc/index.html" target="_top">boost
|
||||
regression test driver</a>, then you can use this to produce a nice html
|
||||
formatted report of the results using the supplied test file.
|
||||
</p>
|
||||
<p>
|
||||
Alternatively you can run the configure script like this:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote"><p>
|
||||
<code class="computeroutput"><span class="special">./</span><span class="identifier">configure</span>
|
||||
<span class="special">--</span><span class="identifier">enable</span><span class="special">-</span><span class="identifier">test</span></code>
|
||||
</p></blockquote></div>
|
||||
<p>
|
||||
in which case the script will test the current configuration rather than
|
||||
creating a new one from scratch.
|
||||
</p>
|
||||
<p>
|
||||
If you are reporting the results of these tests for a new platform/library/compiler
|
||||
then please include a log of the full compiler output, the output from <code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>, and the pass/fail test results.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"><p><small>Last revised: November 20, 2012 at 20:33:30 GMT</small></p></td>
|
||||
<td align="right"><div class="copyright-footer"></div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="boost_config/boost_macro_reference.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user