Google Git
Sign in
gnu / gcc / 4a0fed0c0c7241562eaa5f1a4c916b689429ad86 / . / libstdc++-v3 / doc / html / manual / appendix_porting.html
blob: 3d7fb564f4b8a50819234c8022adcc89e54071d3 [file] [log] [blame]
<?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>Appendix B.  Porting and Maintenance</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><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="appendix.html" title="Part IV.  Appendices" /><link rel="prev" href="source_design_notes.html" title="Design Notes" /><link rel="next" href="documentation_hacking.html" title="Writing and Generating Documentation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix B. 
Porting and Maintenance
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="source_design_notes.html">Prev</a> </td><th width="60%" align="center">Part IV. 
Appendices
</th><td width="20%" align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr></table><hr /></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.porting"></a>
Porting and Maintenance
<a id="id-1.3.6.3.1.1.1" class="indexterm"></a>
</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.version">Shared Library Versioning</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Testing</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Test Organization</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#tests.dg.examples">Examples of Test Directives</a></span></dt><dt><span class="section"><a href="test.html#tests.dg.directives">Directives Specific to Libstdc++ Tests</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.harness.dejagnu">DejaGnu Harness Details</a></span></dt><dt><span class="section"><a href="test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety">
Qualifying Exception Safety Guarantees
</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.status">
Existing tests
</a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.containers">
C++11 Requirements Test Sequence Descriptions
</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="section"><a href="abi.html">ABI Policy and Guidelines</a></span></dt><dd><dl><dt><span class="section"><a href="abi.html#abi.cxx_interface">The C++ Interface</a></span></dt><dt><span class="section"><a href="abi.html#abi.versioning">Versioning</a></span></dt><dd><dl><dt><span class="section"><a href="abi.html#abi.versioning.goals">Goals</a></span></dt><dt><span class="section"><a href="abi.html#abi.versioning.history">History</a></span></dt><dt><span class="section"><a href="abi.html#abi.versioning.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="abi.html#abi.versioning.config">Configuring</a></span></dt><dt><span class="section"><a href="abi.html#abi.versioning.active">Checking Active</a></span></dt></dl></dd><dt><span class="section"><a href="abi.html#abi.changes_allowed">Allowed Changes</a></span></dt><dt><span class="section"><a href="abi.html#abi.changes_no">Prohibited Changes</a></span></dt><dt><span class="section"><a href="abi.html#abi.impl">Implementation</a></span></dt><dt><span class="section"><a href="abi.html#abi.testing">Testing</a></span></dt><dd><dl><dt><span class="section"><a href="abi.html#abi.testing.single">Single ABI Testing</a></span></dt><dt><span class="section"><a href="abi.html#abi.testing.multi">Multiple ABI Testing</a></span></dt></dl></dd><dt><span class="section"><a href="abi.html#abi.issues">Outstanding Issues</a></span></dt></dl></dd><dt><span class="section"><a href="api.html">API Evolution and Deprecation History</a></span></dt><dd><dl><dt><span class="section"><a href="api.html#api.rel_300"><code class="constant">3.0</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_310"><code class="constant">3.1</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_320"><code class="constant">3.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_330"><code class="constant">3.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_340"><code class="constant">3.4</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_400"><code class="constant">4.0</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_410"><code class="constant">4.1</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_420"><code class="constant">4.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_430"><code class="constant">4.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_440"><code class="constant">4.4</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_450"><code class="constant">4.5</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_460"><code class="constant">4.6</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_470"><code class="constant">4.7</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_480"><code class="constant">4.8</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_490"><code class="constant">4.9</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_51"><code class="constant">5</code></a></span></dt><dd><dl><dt><span class="section"><a href="api.html#api.rel_53"><code class="constant">5.3</code></a></span></dt></dl></dd><dt><span class="section"><a href="api.html#api.rel_61"><code class="constant">6</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_71"><code class="constant">7</code></a></span></dt><dd><dl><dt><span class="section"><a href="api.html#api.rel_72"><code class="constant">7.2</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_73"><code class="constant">7.3</code></a></span></dt></dl></dd><dt><span class="section"><a href="api.html#api.rel_81"><code class="constant">8</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_91"><code class="constant">9</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_101"><code class="constant">10</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_111"><code class="constant">11</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_121"><code class="constant">12</code></a></span></dt></dl></dd><dt><span class="section"><a href="backwards.html">Backwards Compatibility</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.first">First</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second">Second</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third">Third</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.third.headers">Pre-ISO headers removed</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.hash">Extension headers hash_map, hash_set moved to ext or backwards</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.nocreate_noreplace">No <code class="code">ios::nocreate/ios::noreplace</code>.
</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.streamattach">
No <code class="code">stream::attach(int fd)</code>
</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx98">
Support for C++98 dialect.
</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_tr1">
Support for C++TR1 dialect.
</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx11">
Support for C++11 dialect.
</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.iterator_type">
<code class="code">Container::iterator_type</code> is not necessarily <code class="code">Container::value_type*</code>
</a></span></dt></dl></dd></dl></dd></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.build_hacking"></a>Configure and Build Hacking</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.prereq"></a>Prerequisites</h3></div></div></div><p>
As noted <a class="link" href="http://gcc.gnu.org/install/prerequisites.html" target="_top">previously</a>,
certain other tools are necessary for hacking on files that
control configure (<code class="code">configure.ac</code>,
<code class="code">acinclude.m4</code>) and make
(<code class="code">Makefile.am</code>). These additional tools
(<code class="code">automake</code>, and <code class="code">autoconf</code>) are further
described in detail in their respective manuals. All the libraries
in GCC try to stay in sync with each other in terms of versions of
the auto-tools used, so please try to play nicely with the
neighbors.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.overview"></a>Overview</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.overview.basic"></a>General Process</h4></div></div></div><p>
The configure process begins the act of building libstdc++, and is
started via:
</p><pre class="screen">
<code class="computeroutput">
configure
</code>
</pre><p>
The <code class="filename">configure</code> file is a script generated (via
<span class="command"><strong>autoconf</strong></span>) from the file
<code class="filename">configure.ac</code>.
</p><p>
After the configure process is complete,
</p><pre class="screen">
<code class="computeroutput">
make all
</code>
</pre><p>
in the build directory starts the build process. The <code class="literal">all</code> target comes from the <code class="filename">Makefile</code> file, which is generated via <span class="command"><strong>configure</strong></span> from the <code class="filename">Makefile.in</code> file, which is in turn generated (via
<span class="command"><strong>automake</strong></span>) from the file
<code class="filename">Makefile.am</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.overview.map"></a>What Comes from Where</h4></div></div></div><div class="figure"><a id="fig.build_hacking.deps"></a><p class="title"><strong>Figure B.1. Configure and Build File Dependencies</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="../images/confdeps.png" align="middle" alt="Dependency Graph for Configure and Build Files" /></div></div></div><br class="figure-break" /><p>
Regenerate all generated files by using the command
<span class="command"><strong>autoreconf</strong></span> at the top level of the libstdc++ source
directory.
</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.configure"></a>Configure</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.scripts"></a>Storing Information in non-AC files (like configure.host)</h4></div></div></div><p>
Until that glorious day when we can use <code class="literal">AC_TRY_LINK</code>
with a cross-compiler, we have to hardcode the results of what the tests
would have shown if they could be run. So we have an inflexible
mess like <code class="filename">crossconfig.m4</code>.
</p><p>
Wouldn't it be nice if we could store that information in files
like configure.host, which can be modified without needing to
regenerate anything, and can even be tweaked without really
knowing how the configury all works? Perhaps break the pieces of
<code class="filename">crossconfig.m4</code> out and place them in their appropriate
<code class="filename">config/{cpu,os}</code> directory.
</p><p>
Alas, writing macros like
"<code class="code">AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside
files which are passed through autoconf. Files which are pure
shell script can be source'd at configure time. Files which
contain autoconf macros must be processed with autoconf. We could
still try breaking the pieces out into "config/*/cross.m4" bits,
for instance, but then we would need arguments to aclocal/autoconf
to properly find them all when generating configure. I would
discourage that.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.conventions"></a>Coding and Commenting Conventions</h4></div></div></div><p>
Most comments should use {octothorpes, shibboleths, hash marks,
pound signs, whatever} rather than "<code class="literal">dnl</code>".
Nearly all comments in <code class="filename">configure.ac</code> should.
Comments inside macros written in ancillary
<code class="filename">.m4</code> files should.
About the only comments which should <span class="emphasis"><em>not</em></span>
use <code class="literal">#</code>, but use <code class="literal">dnl</code> instead,
are comments <span class="emphasis"><em>outside</em></span> our own macros in the ancillary
files. The difference is that <code class="literal">#</code> comments show up in
<code class="filename">configure</code> (which is most helpful for debugging),
while <code class="literal">dnl</code>'d lines just vanish. Since the macros
in ancillary files generate code which appears in odd places,
their "outside" comments tend to not be useful while reading
<code class="filename">configure</code>.
</p><p>
Do not use any <code class="code">$target*</code> variables, such as
<code class="varname">$target_alias</code>. The single exception is in
<code class="filename">configure.ac</code>, for automake+dejagnu's sake.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.acinclude"></a>The acinclude.m4 layout</h4></div></div></div><p>
The nice thing about
<code class="filename">acinclude.m4</code>/<code class="filename">aclocal.m4</code>
is that macros aren't
actually performed/called/expanded/whatever here, just loaded. So
we can arrange the contents however we like. As of this writing,
<code class="filename">acinclude.m4</code> is arranged as follows:
</p><pre class="programlisting">
GLIBCXX_CHECK_HOST
GLIBCXX_TOPREL_CONFIGURE
GLIBCXX_CONFIGURE
</pre><p>
All the major variable "discovery" is done here.
<code class="varname">CXX</code>, multilibs,
etc.
</p><pre class="programlisting">
fragments included from elsewhere
</pre><p>
Right now, "fragments" == "the math/linkage bits".
</p><pre class="programlisting">
GLIBCXX_CHECK_COMPILER_FEATURES
GLIBCXX_CHECK_LINKER_FEATURES
GLIBCXX_CHECK_WCHAR_T_SUPPORT
</pre><p>
Next come extra compiler/linker feature tests. Wide character
support was placed here because I couldn't think of another place
for it. It will probably get broken apart like the math tests,
because we're still disabling wchars on systems which could actually
support them.
</p><pre class="programlisting">
GLIBCXX_CHECK_SETRLIMIT_ancilliary
GLIBCXX_CHECK_SETRLIMIT
GLIBCXX_CHECK_S_ISREG_OR_S_IFREG
GLIBCXX_CHECK_POLL
GLIBCXX_CHECK_WRITEV
GLIBCXX_CONFIGURE_TESTSUITE
</pre><p>
Feature tests which only get used in one place. Here, things used
only in the testsuite, plus a couple bits used in the guts of I/O.
</p><pre class="programlisting">
GLIBCXX_EXPORT_INCLUDES
GLIBCXX_EXPORT_FLAGS
GLIBCXX_EXPORT_INSTALL_INFO
</pre><p>
Installation variables, multilibs, working with the rest of the
compiler. Many of the critical variables used in the makefiles are
set here.
</p><pre class="programlisting">
GLIBGCC_ENABLE
GLIBCXX_ENABLE_C99
GLIBCXX_ENABLE_CHEADERS
GLIBCXX_ENABLE_CLOCALE
GLIBCXX_ENABLE_CONCEPT_CHECKS
GLIBCXX_ENABLE_CSTDIO
GLIBCXX_ENABLE_CXX_FLAGS
GLIBCXX_ENABLE_C_MBCHAR
GLIBCXX_ENABLE_DEBUG
GLIBCXX_ENABLE_DEBUG_FLAGS
GLIBCXX_ENABLE_LONG_LONG
GLIBCXX_ENABLE_PCH
GLIBCXX_ENABLE_SYMVERS
GLIBCXX_ENABLE_THREADS
</pre><p>
All the features which can be controlled with enable/disable
configure options. Note how they're alphabetized now? Keep them
like that. :-)
</p><pre class="programlisting">
AC_LC_MESSAGES
libtool bits
</pre><p>
Things which we don't seem to use directly, but just has to be
present otherwise stuff magically goes wonky.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.enable"></a><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</h4></div></div></div><p>
All the <code class="literal">GLIBCXX_ENABLE_FOO</code> macros use a common
helper, <code class="literal">GLIBCXX_ENABLE</code>. (You don't have to use
it, but it's easy.) The helper does two things for us:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Builds the call to the <code class="literal">AC_ARG_ENABLE</code> macro, with
<code class="option">--help</code> text
properly quoted and aligned. (Death to changequote!)
</p></li><li class="listitem"><p>
Checks the result against a list of allowed possibilities, and
signals a fatal error if there's no match. This means that the
rest of the <code class="literal">GLIBCXX_ENABLE_FOO</code> macro doesn't need to test for
strange arguments, nor do we need to protect against
empty/whitespace strings with the <code class="code">"x$foo" = "xbar"</code>
idiom.
</p></li></ol></div><p>Doing these things correctly takes some extra autoconf/autom4te code,
which made our macros nearly illegible. So all the ugliness is factored
out into this one helper macro.
</p><p>Many of the macros take an argument, passed from when they are expanded
in configure.ac. The argument controls the default value of the
enable/disable switch. Previously, the arguments themselves had defaults.
Now they don't, because that's extra complexity with zero gain for us.
</p><p>There are three "overloaded signatures". When reading the descriptions
below, keep in mind that the brackets are autoconf's quotation characters,
and that they will be stripped. Examples of just about everything occur
in acinclude.m4, if you want to look.
</p><pre class="programlisting">
GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING)
GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c)
GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER)
</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">FEATURE</code> is the string that follows
<code class="option">--enable</code>. The results of the
test (such as it is) will be in the variable
<code class="varname">$enable_FEATURE</code>,
where <code class="literal">FEATURE</code> has been squashed. Example:
<code class="code">[extra-foo]</code>, controlled by the
<code class="option">--enable-extra-foo</code>
option and stored in <code class="varname">$enable_extra_foo</code>.
</p></li><li class="listitem"><p>
<code class="literal">DEFAULT</code> is the value to store in
<code class="varname">$enable_FEATURE</code> if the user does
not pass <code class="option">--enable</code>/<code class="option">--disable</code>.
It should be one of the permitted values passed later.
Examples: <code class="code">[yes]</code>, or <code class="code">[bar]</code>, or
<code class="code">[$1]</code> (which passes the argument given to the
<code class="literal">GLIBCXX_ENABLE_FOO</code> macro as the default).
</p><p>
For cases where we need to probe for particular models of things,
it is useful to have an undocumented "auto" value here (see
<code class="literal">GLIBCXX_ENABLE_CLOCALE</code> for an example).
</p></li><li class="listitem"><p>
<code class="literal">HELP-ARG</code> is any text to append to the option string
itself in the <code class="option">--help</code> output. Examples:
<code class="code">[]</code> (i.e., an empty string, which appends nothing),
<code class="code">[=BAR]</code>, which produces <code class="code">--enable-extra-foo=BAR</code>,
and <code class="code">[@&lt;:@=BAR@:&gt;@]</code>, which produces
<code class="code">--enable-extra-foo[=BAR]</code>. See the difference? See
what it implies to the user?
</p><p>
If you're wondering what that line noise in the last example was,
that's how you embed autoconf special characters in output text.
They're called <a class="link" href="http://www.gnu.org/software/autoconf/manual/autoconf.html#Quadrigraphs" target="_top"><span class="emphasis"><em>quadrigraphs</em></span></a>
and you should use them whenever necessary.
</p></li><li class="listitem"><p><code class="literal">HELP-STRING</code> is what you think it is. Do not include the
"default" text like we used to do; it will be done for you by
<code class="literal">GLIBCXX_ENABLE</code>. By convention, these are not full English
sentences. Example: <code class="literal">[turn on extra foo]</code>
</p></li></ul></div><p>
With no other arguments, only the standard autoconf patterns are
allowed: "<code class="option">--{enable,disable}-foo[={yes,no}]</code>" The
<code class="varname">$enable_FEATURE</code> variable is guaranteed to equal
either "<code class="literal">yes</code>" or "<code class="literal">no</code>"
after the macro. If the user tries to pass something else, an
explanatory error message will be given, and configure will halt.
</p><p>
The second signature takes a fifth argument, "<code class="code">[permit
a | b | c | ...]</code>"
This allows <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> or
... after the equals sign in the option, and
<code class="varname">$enable_FEATURE</code> is
guaranteed to equal one of them after the macro. Note that if you
want to allow plain <code class="option">--enable</code>/<code class="option">--disable</code>
with no "<code class="literal">=whatever</code>", you must
include "<code class="literal">yes</code>" and "<code class="literal">no</code>" in the
list of permitted values. Also note that whatever you passed as
<code class="literal">DEFAULT</code> must be in the list. If the
user tries to pass something not on the list, a semi-explanatory
error message will be given, and configure will halt. Example:
<code class="code">[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code>
</p><p>
The third signature takes a fifth argument. It is arbitrary shell
code to execute if the user actually passes the enable/disable
option. (If the user does not, the default is used. Duh.) No
argument checking at all is done in this signature. See
<code class="literal">GLIBCXX_ENABLE_CXX_FLAGS</code> for an example of handling,
and an error message.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.version"></a>Shared Library Versioning</h4></div></div></div><p>
The <code class="filename">libstdc++.so</code> shared library must
be carefully managed to maintain binary compatible with older versions
of the library. This ensures a new version of the library is still usable by
programs that were linked against an older version.
</p><p>
Dependent on the target supporting it, the library uses <a class="link" href="https://www.akkadia.org/drepper/symbol-versioning" target="_top">ELF
symbol versioning</a> for all exported symbols. The symbol versions
are defined by a <a class="link" href="https://sourceware.org/binutils/docs/ld/VERSION.html" target="_top">linker
script</a> that assigns a version to every symbol.
The set of symbols in each version is fixed when a GCC
release is made, and must not change after that.
</p><p> When new symbols are added to the library they must be added
to a new symbol version, which must be created the first time new symbols
are added after a release. Adding a new symbol version involves the
following steps:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Edit <code class="filename">acinclude.m4</code> to update the "revision" value of
<code class="varname">libtool_VERSION</code>, e.g. from <code class="literal">6:22:0</code>
to <code class="literal">6:23:0</code>, which will cause the shared library to be
built as <code class="filename">libstdc++.so.6.0.23</code>.
</p></li><li class="listitem"><p>
Regenerate the <code class="filename">configure</code> script by running the
<span class="command"><strong>autoreconf</strong></span> tool from the correct version of the Autoconf
package (as dictated by the <a class="link" href="https://gcc.gnu.org/install/prerequisites.html" target="_top">GCC
prerequisites</a>).
</p></li><li class="listitem"><p>
Edit the file <code class="filename">config/abi/pre/gnu.ver</code> to
add a new version node after the last new node. The node name should be
<code class="literal">GLIBCXX_3.4.X</code> where <code class="literal">X</code> is the new
revision set in <code class="filename">acinclude.m4</code>, and the node should
depend on the previous version e.g.
</p><pre class="programlisting">
GLIBCXX_3.4.23 {
} GLIBCXX_3.4.22;
</pre><p>
For symbols in the ABI runtime, libsupc++, the symbol version naming uses
<code class="literal">CXXABI_1.3.Y</code> where <code class="literal">Y</code> increases
monotonically with each new version. Again, the new node must depend on the
previous version node e.g.
</p><pre class="programlisting">
CXXABI_1.3.11 {
} CXXABI_1.3.10;
</pre><p>
</p></li><li class="listitem"><p>
In order for the <a class="link" href="test.html#test.run.variations" title="Variations">check-abi</a> test
target to pass the testsuite must be updated to know about the new symbol
version(s). Edit the file <code class="filename">testsuite/util/testsuite_abi.cc</code>
file to add the new versions to the <code class="varname">known_versions</code> list,
and update the checks for the latest versions that set the
<code class="varname">latestp</code> variable).
</p></li><li class="listitem"><p>
Add the library (<code class="filename">libstdc++.so.6.0.X</code>)
and symbols versions
(<code class="literal">GLIBCXX_3.4.X</code> and <code class="literal">CXXABI_1.3.Y</code>)
to the <a class="link" href="abi.html#abi.versioning.history" title="History">History</a> section in
<code class="filename">doc/xml/manual/abi.xml</code> at the relevant places.
</p></li></ul></div><p>
Once the new symbol version has been added you can add the names of your new
symbols in the new version node:
</p><pre class="programlisting">
GLIBCXX_3.4.23 {
# basic_string&lt;C, T, A&gt;::_Alloc_hider::_Alloc_hider(C*, A&amp;&amp;)
_ZNSt7__cxx1112basic_stringI[cw]St11char_traitsI[cw]ESaI[cw]EE12_Alloc_hiderC[12]EP[cw]OS3_;
} GLIBCXX_3.4.22;
</pre><p>
You can either use mangled names, or demangled names inside an
<code class="literal">extern "C++"</code> block. You might find that the new symbol
matches an existing pattern in an old symbol version (causing the
<code class="literal">check-abi</code> test target to fail). If that happens then the
existing pattern must be adjusted to be more specific so that it doesn't
match the new symbol.
</p><p>
For an example of these steps, including adjusting old patterns to be less
greedy, see <a class="link" href="https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html" target="_top">https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html</a>
and the attached patch.
</p><p>
If it wasn't done for the last release, you might also need to regenerate
the <code class="filename">baseline_symbols.txt</code> file that defines the set
of expected symbols for old symbol versions. A new baseline file can be
generated by running <strong class="userinput"><code>make new-abi-baseline</code></strong> in the
<code class="filename"><em class="replaceable"><code>libbuilddir</code></em>/testsuite</code>
directory. Be sure to generate the baseline from a clean build using
unmodified sources, or you will incorporate your local changes into the
baseline file.
</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.make"></a>Make</h3></div></div></div><p>
The build process has to make all of object files needed for
static or shared libraries, but first it has to generate some
include files. The general order is as follows:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
make include files, make pre-compiled headers
</p></li><li class="listitem"><p>
make libsupc++
</p><p>
Generates a libtool convenience library,
<code class="filename">libsupc++convenience</code> with language-support
routines. Also generates a freestanding static library,
<code class="filename">libsupc++.a</code>.
</p></li><li class="listitem"><p>
make src
</p><p>
Generates two convenience libraries, one for C++98 and one for
C++11, various compatibility files for shared and static
libraries, and then collects all the generated bits and creates
the final libstdc++ libraries.
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
make src/c++98
</p><p>
Generates a libtool convenience library,
<code class="filename">libc++98convenience</code> with language-support
routines. Uses the <code class="option">-std=gnu++98</code> dialect.
</p></li><li class="listitem"><p>
make src/c++11
</p><p>
Generates a libtool convenience library,
<code class="filename">libc++11convenience</code> with language-support
routines. Uses the <code class="option">-std=gnu++11</code> dialect.
</p></li><li class="listitem"><p>
make src
</p><p>
Generates needed compatibility objects for shared and static
libraries. Shared-only code is seggregated at compile-time via
the macro <code class="literal">_GLIBCXX_SHARED</code>.
</p><p>
Then, collects all the generated convenience libraries, adds in
any required compatibility objects, and creates the final shared
and static libraries: <code class="filename">libstdc++.so</code> and
<code class="filename">libstdc++.a</code>.
</p></li></ol></div></li></ol></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source_design_notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Design Notes </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Writing and Generating Documentation</td></tr></table></div></body></html>