configure.xml: Update descriptions of options affecting dual ABI and add cross-references.
* doc/xml/manual/configure.xml: Update descriptions of options affecting dual ABI and add cross-references. * doc/xml/manual/strings.xml: Clarify that string isn't COW now. * doc/xml/manual/using.xml: Document ABI transition. * doc/html/*: Regenerate. From-SVN: r222262
This commit is contained in:
Jonathan Wakely
Jonathan Wakely
parent
0ee59f1f05
commit
8a29fdfd23
15 changed files with 245 additions and 38 deletions
|
|
@ -1,5 +1,11 @@
|
|||
2015-04-21 Jonathan Wakely <jwakely@redhat.com>
|
||||
|
||||
* doc/xml/manual/configure.xml: Update descriptions of options
|
||||
affecting dual ABI and add cross-references.
|
||||
* doc/xml/manual/strings.xml: Clarify that string isn't COW now.
|
||||
* doc/xml/manual/using.xml: Document ABI transition.
|
||||
* doc/html/*: Regenerate.
|
||||
|
||||
* doc/xml/manual/abi.xml: Use uppercase for C++ Standard Library.
|
||||
* doc/xml/manual/using.xml: Document newer -std options. Use better
|
||||
examples of nested namespaces.
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -38,7 +38,7 @@
|
|||
documented
|
||||
<a class="link" href="configure.html" title="Configure">here</a>.
|
||||
</p><p> Putting all of these ideas together results in the C++ Standard
|
||||
library ABI, which is the compilation of a given library API by a
|
||||
Library ABI, which is the compilation of a given library API by a
|
||||
given compiler ABI. In a nutshell:
|
||||
</p><p>
|
||||
<span class="quote">“<span class="quote">
|
||||
|
|
|
|||
|
|
@ -228,13 +228,17 @@
|
|||
when standard error is not available. This option disables those
|
||||
messages. This option does not change the library ABI.
|
||||
</p></dd><dt><span class="term"><code class="code">--disable-libstdcxx-dual-abi</code></span></dt><dd><p>
|
||||
Disable support for the new, C++11-conforming <code class="code">std::string</code>
|
||||
implementation. This option changes the library ABI.
|
||||
</p></dd><dt><span class="term"><code class="code">--with-default-libstdcxx-abi</code></span></dt><dd><p>
|
||||
By default, the new <code class="code">std::string</code> implementation will be
|
||||
declared and a macro must be defined to declare the old implementation
|
||||
instead. That default can be reversed by configuring the library with
|
||||
<code class="code">--with-default-libstdcxx-abi=c++98</code>.
|
||||
Disable support for the new, C++11-conforming implementations of
|
||||
<code class="code">std::string</code>, <code class="code">std::list</code> etc. so that the
|
||||
library only provides definitions of types using the old ABI
|
||||
(see <a class="xref" href="using_dual_abi.html" title="Dual ABI">Dual ABI</a>).
|
||||
This option changes the library ABI.
|
||||
</p></dd><dt><span class="term"><code class="code">--with-default-libstdcxx-abi=</code><em class="replaceable"><code>OPTION</code></em></span></dt><dd><p>
|
||||
Set the default value for the <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span>
|
||||
macro (see <a class="xref" href="using_macros.html" title="Macros">Macros</a>).
|
||||
The default is <code class="option">OPTION=c++11</code> which sets the macro to
|
||||
<code class="literal">1</code>,
|
||||
use <code class="option">OPTION=c++98</code> to set it to <code class="literal">0</code>.
|
||||
This option does not change the library ABI.
|
||||
</p></dd><dt><span class="term"><code class="code">--enable-vtable-verify</code>[default]</span></dt><dd><p>Use <code class="code">-fvtable-verify=std</code> to compile the C++
|
||||
runtime with instrumentation for vtable verification. All virtual
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
|
|
@ -267,7 +267,7 @@ stringtok(Container &container, string const &in,
|
|||
a <code class="code">vector</code>'s memory usage
|
||||
(see <a class="link" href="../faq.html#faq.size_equals_capacity" title="7.8.">this FAQ
|
||||
entry</a>) but the regular copy constructor cannot be used
|
||||
because libstdc++'s <code class="code">string</code> is Copy-On-Write.
|
||||
because libstdc++'s <code class="code">string</code> is Copy-On-Write in GCC 3.
|
||||
</p><p>In <a class="link" href="status.html#status.iso.2011" title="C++ 2011">C++11</a> mode you can call
|
||||
<code class="code">s.shrink_to_fit()</code> to achieve the same effect as
|
||||
<code class="code">s.reserve(s.size())</code>.
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
65
libstdc++-v3/doc/html/manual/using_dual_abi.html
Normal file
65
libstdc++-v3/doc/html/manual/using_dual_abi.html
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Dual ABI</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_macros.html" title="Macros" /><link rel="next" href="using_namespaces.html" title="Namespaces" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Dual ABI</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_namespaces.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.abi"></a>Dual ABI</h2></div></div></div><p> In the GCC 5.1 release libstdc++ introduced a new library ABI that
|
||||
includes new implementations of <code class="classname">std::string</code> and
|
||||
<code class="classname">std::list</code>. These changes were necessary to conform
|
||||
to the 2011 C++ standard which forbids Copy-On-Write strings and requires
|
||||
lists to keep track of their size.
|
||||
</p><p> In order to maintain backwards compatibility for existing code linked
|
||||
to libstdc++ the library's soname has not changed and the old
|
||||
implementations are still supported in parallel with the new ones.
|
||||
This is achieved by defining the new implementations in an inline namespace
|
||||
so they have different names for linkage purposes, e.g. the new version of
|
||||
<code class="classname">std::list<int></code> is actually defined as
|
||||
<code class="classname">std::__cxx11::list<int></code>. Because the symbols
|
||||
for the new implementations have different names the definitions for both
|
||||
versions can be present in the same library.
|
||||
</p><p> The <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro (see
|
||||
<a class="xref" href="using_macros.html" title="Macros">Macros</a>) controls whether
|
||||
the declarations in the library headers use the old or new ABI.
|
||||
So the decision of which ABI to use can be made separately for each
|
||||
source file being compiled.
|
||||
Using the default configuration options for GCC the default value
|
||||
of the macro is <code class="literal">1</code> which causes the new ABI to be active,
|
||||
so to use the old ABI you must explicitly define the macro to
|
||||
<code class="literal">0</code> before including any library headers.
|
||||
(Be aware that some GNU/Linux distributions configure GCC 5 differently so
|
||||
that the default value of the macro is <code class="literal">0</code> and users must
|
||||
define it to <code class="literal">1</code> to enable the new ABI.)
|
||||
</p><p> Although the changes were made for C++11 conformance, the choice of ABI
|
||||
to use is independent of the <code class="option">-std</code> option used to compile
|
||||
your code, i.e. for a given GCC build the default value of the
|
||||
<span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro is the same for all dialects.
|
||||
This ensures that the <code class="option">-std</code> does not change the ABI, so
|
||||
that it is straightforward to link C++03 and C++11 code together.
|
||||
</p><p> Because <code class="classname">std::string</code> is used extensively
|
||||
throughout the library a number of other types are also defined twice,
|
||||
including the stringstream classes and several facets used by
|
||||
<code class="classname">std::locale</code>. The standard facets which are always
|
||||
installed in a locale may be present twice, with both ABIs, to ensure that
|
||||
code like
|
||||
<code class="code">std::use_facet<std::time_get<char>>(locale);</code>
|
||||
will work correctly for both <code class="classname">std::time_get</code> and
|
||||
<code class="classname">std::__cxx11::time_get</code> (even if a user-defined
|
||||
facet that derives from one or other version of
|
||||
<code class="classname">time_get</code> is installed in the locale).
|
||||
</p><p> Although the standard exception types defined in
|
||||
<code class="filename"><stdexcept></code> use strings, they
|
||||
are not defined twice, so that a <code class="classname">std::out_of_range</code>
|
||||
exception thrown in one file can always be caught by a suitable handler in
|
||||
another file, even if the two files are compiled with different ABIs.
|
||||
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.abi.trouble"></a>Troubleshooting</h3></div></div></div><p> If you get linker errors about undefined references to symbols
|
||||
that involve types in the <code class="code">std::__cxx11</code> namespace or the tag
|
||||
<code class="code">[abi:cxx11]</code> then it probably indicates that you are trying to
|
||||
link together object files that were compiled with different values for the
|
||||
<span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro. This commonly happens when
|
||||
linking to a third-party library that was compiled with an older version
|
||||
of GCC. If the third-party library cannot be rebuilt with the new ABI then
|
||||
you will need to recompile your code with the old ABI.
|
||||
</p><p> Not all uses of the new ABI will cause changes in symbol names, for
|
||||
example a class with a <code class="classname">std::string</code> member variable
|
||||
will have the same mangled name whether compiled with the old or new ABI.
|
||||
In order to detect such problems the new types and functions are
|
||||
annotated with the <span class="property">abi_tag</span> attribute, allowing the
|
||||
compiler to warn about potential ABI incompatibilities in code using them.
|
||||
Those warnings can be enabled with the <code class="option">-Wabi-tag</code> option.
|
||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_namespaces.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Namespaces</td></tr></table></div></body></html>
|
||||
|
|
@ -265,7 +265,7 @@ is called.
|
|||
}
|
||||
catch(...)
|
||||
{ this->_M_setstate(ios_base::badbit); }
|
||||
</pre></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="using.exceptions.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id-1.3.3.4.8.9.2"></a><p><span class="title"><em>
|
||||
</pre></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="using.exceptions.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.2"></a><p><span class="title"><em>
|
||||
<a class="link" href="http://www.opengroup.org/austin/" target="_top">
|
||||
System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
|
||||
</a>
|
||||
|
|
@ -274,39 +274,39 @@ is called.
|
|||
. </span><span class="copyright">Copyright © 2008
|
||||
The Open Group/The Institute of Electrical and Electronics
|
||||
Engineers, Inc.
|
||||
. </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.8.9.3"></a><p><span class="title"><em>
|
||||
. </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.3"></a><p><span class="title"><em>
|
||||
<a class="link" href="http://www.boost.org/community/error_handling.html" target="_top">
|
||||
Error and Exception Handling
|
||||
</a>
|
||||
</em>. </span><span class="author"><span class="firstname">David</span> <span class="surname">Abrahams </span>. </span><span class="publisher"><span class="publishername">
|
||||
Boost
|
||||
. </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.8.9.4"></a><p><span class="title"><em>
|
||||
. </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.4"></a><p><span class="title"><em>
|
||||
<a class="link" href="http://www.boost.org/community/exception_safety.html" target="_top">
|
||||
Exception-Safety in Generic Components
|
||||
</a>
|
||||
</em>. </span><span class="author"><span class="firstname">David</span> <span class="surname">Abrahams</span>. </span><span class="publisher"><span class="publishername">
|
||||
Boost
|
||||
. </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.8.9.5"></a><p><span class="title"><em>
|
||||
. </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.5"></a><p><span class="title"><em>
|
||||
<a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/1997/N1077.pdf" target="_top">
|
||||
Standard Library Exception Policy
|
||||
</a>
|
||||
</em>. </span><span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername">
|
||||
WG21 N1077
|
||||
. </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.8.9.6"></a><p><span class="title"><em>
|
||||
. </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.6"></a><p><span class="title"><em>
|
||||
<a class="link" href="http://gcc.gnu.org/ml/gcc-patches/2001-03/msg00661.html" target="_top">
|
||||
ia64 c++ abi exception handling
|
||||
</a>
|
||||
</em>. </span><span class="author"><span class="firstname">Richard</span> <span class="surname">Henderson</span>. </span><span class="publisher"><span class="publishername">
|
||||
GNU
|
||||
. </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.8.9.7"></a><p><span class="title"><em>
|
||||
. </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.7"></a><p><span class="title"><em>
|
||||
<a class="link" href="http://www.research.att.com/~bs/3rd_safe.pdf" target="_top">
|
||||
Appendix E: Standard-Library Exception Safety
|
||||
</a>
|
||||
</em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.8.9.8"></a><p><span class="citetitle"><em class="citetitle">
|
||||
</em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.8"></a><p><span class="citetitle"><em class="citetitle">
|
||||
Exceptional C++
|
||||
</em>. </span><span class="pagenums">
|
||||
Exception-Safety Issues and Techniques
|
||||
. </span><span class="author"><span class="firstname">Herb</span> <span class="surname">Sutter</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.8.9.9"></a><p><span class="title"><em>
|
||||
. </span><span class="author"><span class="firstname">Herb</span> <span class="surname">Sutter</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.9"></a><p><span class="title"><em>
|
||||
<a class="link" href="http://gcc.gnu.org/PR25191" target="_top">
|
||||
GCC Bug 25191: exception_defines.h #defines try/catch
|
||||
</a>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Macros</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_headers.html" title="Headers" /><link rel="next" href="using_namespaces.html" title="Namespaces" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Macros</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_namespaces.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.macros"></a>Macros</h2></div></div></div><p>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Macros</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_headers.html" title="Headers" /><link rel="next" href="using_dual_abi.html" title="Dual ABI" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Macros</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_dual_abi.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.macros"></a>Macros</h2></div></div></div><p>
|
||||
All library macros begin with <code class="code">_GLIBCXX_</code>.
|
||||
</p><p>
|
||||
Furthermore, all pre-processor macros, switches, and
|
||||
|
|
@ -50,6 +50,17 @@
|
|||
be useful in updating old C++ code which no longer meet the
|
||||
requirements of the language, or for checking current code
|
||||
against new language standards.
|
||||
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_USE_CXX11_ABI</code></span></dt><dd><p>
|
||||
Defined to the value <code class="literal">1</code> by default.
|
||||
Configurable via <code class="code">--disable-libstdcxx-dual-abi</code>
|
||||
and/or <code class="code">--with-default-libstdcxx-abi</code>.
|
||||
ABI-changing.
|
||||
When defined to a non-zero value the library headers will use the
|
||||
new C++11-conforming ABI introduced in GCC 5, rather than the older
|
||||
ABI introduced in GCC 3.4. This changes the definition of several
|
||||
class templates, including <code class="classname">std:string</code>,
|
||||
<code class="classname">std::list</code> and some locale facets.
|
||||
For more details see <a class="xref" href="using_dual_abi.html" title="Dual ABI">Dual ABI</a>.
|
||||
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_CONCEPT_CHECKS</code></span></dt><dd><p>
|
||||
Undefined by default. Configurable via
|
||||
<code class="code">--enable-concept-checks</code>. When defined, performs
|
||||
|
|
@ -71,4 +82,4 @@
|
|||
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_PROFILE</code></span></dt><dd><p>Undefined by default. When defined, compiles user code
|
||||
using the <a class="link" href="profile_mode.html" title="Chapter 19. Profile Mode">profile
|
||||
mode</a>.
|
||||
</p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_namespaces.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Headers </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Namespaces</td></tr></table></div></body></html>
|
||||
</p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_dual_abi.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Headers </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Dual ABI</td></tr></table></div></body></html>
|
||||
|
|
@ -1,16 +1,19 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Namespaces</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_macros.html" title="Macros" /><link rel="next" href="using_dynamic_or_shared.html" title="Linking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Namespaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.namespaces"></a>Namespaces</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Namespaces</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_dual_abi.html" title="Dual ABI" /><link rel="next" href="using_dynamic_or_shared.html" title="Linking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Namespaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_dual_abi.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.namespaces"></a>Namespaces</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
|
||||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>std</p><p>The ISO C++ standards specify that "all library entities are defined
|
||||
within namespace std." This includes namespaces nested
|
||||
within <code class="code">namespace std</code>, such as <code class="code">namespace
|
||||
std::tr1</code>.
|
||||
within namespace <code class="code">std</code>, such as namespace
|
||||
<code class="code">std::chrono</code>.
|
||||
</p></li><li class="listitem"><p>abi</p><p>Specified by the C++ ABI. This ABI specifies a number of type and
|
||||
function APIs supplemental to those required by the ISO C++ Standard,
|
||||
but necessary for interoperability.
|
||||
</p></li><li class="listitem"><p>__gnu_</p><p>Indicating one of several GNU extensions. Choices
|
||||
include <code class="code">__gnu_cxx</code>, <code class="code">__gnu_debug</code>, <code class="code">__gnu_parallel</code>,
|
||||
and <code class="code">__gnu_pbds</code>.
|
||||
</p></li></ul></div><p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html" target="_top">documentation</a>.
|
||||
</p></li></ul></div><p> The library uses a number of inline namespaces as implementation
|
||||
details that are not intended for users to refer to directly, these include
|
||||
<code class="code">std::__detail</code>, <code class="code">std::__cxx11</code> and <code class="code">std::_V2</code>.
|
||||
</p><p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html" target="_top">documentation</a>.
|
||||
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.std"></a>namespace std</h3></div></div></div><p>
|
||||
One standard requirement is that the library components are defined
|
||||
in <code class="code">namespace std::</code>. Thus, in order to use these types or
|
||||
|
|
@ -57,4 +60,4 @@ namespace gtk
|
|||
std::string;</code> (depending on whether the system has
|
||||
libstdc++ in <code class="code">std::</code> or not). (ideas from
|
||||
Llewelly and Karl Nelson)
|
||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Linking</td></tr></table></div></body></html>
|
||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_dual_abi.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Dual ABI </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Linking</td></tr></table></div></body></html>
|
||||
|
|
@ -385,18 +385,22 @@
|
|||
<varlistentry><term><code>--disable-libstdcxx-dual-abi</code></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Disable support for the new, C++11-conforming <code>std::string</code>
|
||||
implementation. This option changes the library ABI.
|
||||
Disable support for the new, C++11-conforming implementations of
|
||||
<code>std::string</code>, <code>std::list</code> etc. so that the
|
||||
library only provides definitions of types using the old ABI
|
||||
(see <xref linkend="manual.intro.using.abi"/>).
|
||||
This option changes the library ABI.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><code>--with-default-libstdcxx-abi</code></term>
|
||||
<varlistentry><term><code>--with-default-libstdcxx-abi=</code><replaceable>OPTION</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
By default, the new <code>std::string</code> implementation will be
|
||||
declared and a macro must be defined to declare the old implementation
|
||||
instead. That default can be reversed by configuring the library with
|
||||
<code>--with-default-libstdcxx-abi=c++98</code>.
|
||||
Set the default value for the <symbol>_GLIBCXX_USE_CXX11_ABI</symbol>
|
||||
macro (see <xref linkend="manual.intro.using.macros"/>).
|
||||
The default is <option>OPTION=c++11</option> which sets the macro to
|
||||
<literal>1</literal>,
|
||||
use <option>OPTION=c++98</option> to set it to <literal>0</literal>.
|
||||
This option does not change the library ABI.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
|
|
|
|||
|
|
@ -353,7 +353,7 @@ stringtok(Container &container, string const &in,
|
|||
a <code>vector</code>'s memory usage
|
||||
(see <link linkend="faq.size_equals_capacity">this FAQ
|
||||
entry</link>) but the regular copy constructor cannot be used
|
||||
because libstdc++'s <code>string</code> is Copy-On-Write.
|
||||
because libstdc++'s <code>string</code> is Copy-On-Write in GCC 3.
|
||||
</para>
|
||||
<para>In <link linkend="status.iso.2011">C++11</link> mode you can call
|
||||
<code>s.shrink_to_fit()</code> to achieve the same effect as
|
||||
|
|
|
|||
|
|
@ -875,6 +875,22 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
|
|||
</para>
|
||||
</listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><code>_GLIBCXX_USE_CXX11_ABI</code></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Defined to the value <literal>1</literal> by default.
|
||||
Configurable via <code>--disable-libstdcxx-dual-abi</code>
|
||||
and/or <code>--with-default-libstdcxx-abi</code>.
|
||||
ABI-changing.
|
||||
When defined to a non-zero value the library headers will use the
|
||||
new C++11-conforming ABI introduced in GCC 5, rather than the older
|
||||
ABI introduced in GCC 3.4. This changes the definition of several
|
||||
class templates, including <classname>std:string</classname>,
|
||||
<classname>std::list</classname> and some locale facets.
|
||||
For more details see <xref linkend="manual.intro.using.abi"/>.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
|
@ -922,6 +938,94 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
|
|||
|
||||
</section>
|
||||
|
||||
<section xml:id="manual.intro.using.abi" xreflabel="Dual ABI">
|
||||
<info><title>Dual ABI</title></info>
|
||||
<?dbhtml filename="using_dual_abi.html"?>
|
||||
|
||||
<para> In the GCC 5.1 release libstdc++ introduced a new library ABI that
|
||||
includes new implementations of <classname>std::string</classname> and
|
||||
<classname>std::list</classname>. These changes were necessary to conform
|
||||
to the 2011 C++ standard which forbids Copy-On-Write strings and requires
|
||||
lists to keep track of their size.
|
||||
</para>
|
||||
|
||||
<para> In order to maintain backwards compatibility for existing code linked
|
||||
to libstdc++ the library's soname has not changed and the old
|
||||
implementations are still supported in parallel with the new ones.
|
||||
This is achieved by defining the new implementations in an inline namespace
|
||||
so they have different names for linkage purposes, e.g. the new version of
|
||||
<classname>std::list<int></classname> is actually defined as
|
||||
<classname>std::__cxx11::list<int></classname>. Because the symbols
|
||||
for the new implementations have different names the definitions for both
|
||||
versions can be present in the same library.
|
||||
</para>
|
||||
|
||||
<para> The <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro (see
|
||||
<xref linkend="manual.intro.using.macros"/>) controls whether
|
||||
the declarations in the library headers use the old or new ABI.
|
||||
So the decision of which ABI to use can be made separately for each
|
||||
source file being compiled.
|
||||
Using the default configuration options for GCC the default value
|
||||
of the macro is <literal>1</literal> which causes the new ABI to be active,
|
||||
so to use the old ABI you must explicitly define the macro to
|
||||
<literal>0</literal> before including any library headers.
|
||||
(Be aware that some GNU/Linux distributions configure GCC 5 differently so
|
||||
that the default value of the macro is <literal>0</literal> and users must
|
||||
define it to <literal>1</literal> to enable the new ABI.)
|
||||
</para>
|
||||
|
||||
<para> Although the changes were made for C++11 conformance, the choice of ABI
|
||||
to use is independent of the <option>-std</option> option used to compile
|
||||
your code, i.e. for a given GCC build the default value of the
|
||||
<symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro is the same for all dialects.
|
||||
This ensures that the <option>-std</option> does not change the ABI, so
|
||||
that it is straightforward to link C++03 and C++11 code together.
|
||||
</para>
|
||||
|
||||
<para> Because <classname>std::string</classname> is used extensively
|
||||
throughout the library a number of other types are also defined twice,
|
||||
including the stringstream classes and several facets used by
|
||||
<classname>std::locale</classname>. The standard facets which are always
|
||||
installed in a locale may be present twice, with both ABIs, to ensure that
|
||||
code like
|
||||
<code>std::use_facet<std::time_get<char>>(locale);</code>
|
||||
will work correctly for both <classname>std::time_get</classname> and
|
||||
<classname>std::__cxx11::time_get</classname> (even if a user-defined
|
||||
facet that derives from one or other version of
|
||||
<classname>time_get</classname> is installed in the locale).
|
||||
</para>
|
||||
|
||||
<para> Although the standard exception types defined in
|
||||
<filename clas="headerfile"><stdexcept></filename> use strings, they
|
||||
are not defined twice, so that a <classname>std::out_of_range</classname>
|
||||
exception thrown in one file can always be caught by a suitable handler in
|
||||
another file, even if the two files are compiled with different ABIs.
|
||||
</para>
|
||||
|
||||
<section xml:id="manual.intro.using.abi.trouble" xreflabel="Dual ABI Troubleshooting"><info><title>Troubleshooting</title></info>
|
||||
|
||||
<para> If you get linker errors about undefined references to symbols
|
||||
that involve types in the <code>std::__cxx11</code> namespace or the tag
|
||||
<code>[abi:cxx11]</code> then it probably indicates that you are trying to
|
||||
link together object files that were compiled with different values for the
|
||||
<symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro. This commonly happens when
|
||||
linking to a third-party library that was compiled with an older version
|
||||
of GCC. If the third-party library cannot be rebuilt with the new ABI then
|
||||
you will need to recompile your code with the old ABI.
|
||||
</para>
|
||||
|
||||
<para> Not all uses of the new ABI will cause changes in symbol names, for
|
||||
example a class with a <classname>std::string</classname> member variable
|
||||
will have the same mangled name whether compiled with the old or new ABI.
|
||||
In order to detect such problems the new types and functions are
|
||||
annotated with the <property>abi_tag</property> attribute, allowing the
|
||||
compiler to warn about potential ABI incompatibilities in code using them.
|
||||
Those warnings can be enabled with the <option>-Wabi-tag</option> option.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info>
|
||||
<?dbhtml filename="using_namespaces.html"?>
|
||||
|
||||
|
|
@ -956,6 +1060,11 @@ and <code>__gnu_pbds</code>.
|
|||
</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para> The library uses a number of inline namespaces as implementation
|
||||
details that are not intended for users to refer to directly, these include
|
||||
<code>std::__detail</code>, <code>std::__cxx11</code> and <code>std::_V2</code>.
|
||||
</para>
|
||||
|
||||
<para> A complete list of implementation namespaces (including namespace contents) is available in the generated source <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</link>.
|
||||
</para>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue