libstdc++-v3/doc/html/manual/appendix_porting.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!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-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="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.
   3   Porting and Maintenance
   4
   5 </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.
   6   Appendices
   7 </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>
   8   Porting and Maintenance
   9   <a id="id-1.3.6.3.1.1.1" class="indexterm"></a>
  10 </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">
  11   Qualifying Exception Safety Guarantees
  12
  13 </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">
  14     Existing tests
  15 </a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.containers">
  16 C++11 Requirements Test Sequence Descriptions
  17 </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_50"><code class="constant">5</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><dd><dl><dt><span class="section"><a href="backwards.html#backwards.first.ios_base">No <code class="code">ios_base</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.first.cout_cin">No <code class="code">cout</code> in <code class="filename">&lt;ostream.h&gt;</code>, no <code class="code">cin</code> in <code class="filename">&lt;istream.h&gt;</code></a></span></dt></dl></dd><dt><span class="section"><a href="backwards.html#backwards.second">Second</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.second.std">Namespace <code class="code">std::</code> not supported</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.iterators">Illegal iterator usage</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.isspace"><code class="code">isspace</code> from <code class="filename">&lt;cctype&gt;</code> is a macro
  18   </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.at">No <code class="code">vector::at</code>, <code class="code">deque::at</code>, <code class="code">string::at</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.eof">No <code class="code">std::char_traits&lt;char&gt;::eof</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.stringclear">No <code class="code">string::clear</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.ostreamform_istreamscan">
  19   Removal of <code class="code">ostream::form</code> and <code class="code">istream::scan</code>
  20   extensions
  21 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.stringstreams">No <code class="code">basic_stringbuf</code>, <code class="code">basic_stringstream</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.wchar">Little or no wide character support</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.iostream_templates">No templatized iostreams</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.thread_safety">Thread safety issues</a></span></dt></dl></dd><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>.
  22 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.streamattach">
  23 No <code class="code">stream::attach(int fd)</code>
  24 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx98">
  25 Support for C++98 dialect.
  26 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_tr1">
  27 Support for C++TR1 dialect.
  28 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx11">
  29 Support for C++11 dialect.
  30 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.iterator_type">
  31   <code class="code">Container::iterator_type</code> is not necessarily <code class="code">Container::value_type*</code>
  32 </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>
  33     As noted <a class="link" href="http://gcc.gnu.org/install/prerequisites.html" target="_top">previously</a>,
  34     certain other tools are necessary for hacking on files that
  35     control configure (<code class="code">configure.ac</code>,
  36     <code class="code">acinclude.m4</code>) and make
  37     (<code class="code">Makefile.am</code>). These additional tools
  38     (<code class="code">automake</code>, and <code class="code">autoconf</code>) are further
  39     described in detail in their respective manuals. All the libraries
  40     in GCC try to stay in sync with each other in terms of versions of
  41     the auto-tools used, so please try to play nicely with the
  42     neighbors.
  43   </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>
  44   The configure process begins the act of building libstdc++, and is
  45   started via:
  46 </p><pre class="screen">
  47 <code class="computeroutput">
  48 configure
  49 </code>
  50 </pre><p>
  51 The <code class="filename">configure</code> file is a script generated (via
  52 <span class="command"><strong>autoconf</strong></span>) from the file
  53 <code class="filename">configure.ac</code>.
  54 </p><p>
  55   After the configure process is complete,
  56 </p><pre class="screen">
  57 <code class="computeroutput">
  58 make all
  59 </code>
  60 </pre><p>
  61 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
  62 <span class="command"><strong>automake</strong></span>) from the file
  63 <code class="filename">Makefile.am</code>.
  64 </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>
  65     Regenerate all generated files by using the command
  66     <span class="command"><strong>autoreconf</strong></span> at the top level of the libstdc++ source
  67     directory.
  68   </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>
  69     Until that glorious day when we can use <code class="literal">AC_TRY_LINK</code>
  70     with a cross-compiler, we have to hardcode the results of what the tests
  71     would have shown if they could be run.  So we have an inflexible
  72     mess like <code class="filename">crossconfig.m4</code>.
  73   </p><p>
  74     Wouldn't it be nice if we could store that information in files
  75     like configure.host, which can be modified without needing to
  76     regenerate anything, and can even be tweaked without really
  77     knowing how the configury all works?  Perhaps break the pieces of
  78     <code class="filename">crossconfig.m4</code> out and place them in their appropriate
  79     <code class="filename">config/{cpu,os}</code> directory.
  80   </p><p>
  81     Alas, writing macros like
  82     "<code class="code">AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside
  83     files which are passed through autoconf.  Files which are pure
  84     shell script can be source'd at configure time.  Files which
  85     contain autoconf macros must be processed with autoconf.  We could
  86     still try breaking the pieces out into "config/*/cross.m4" bits,
  87     for instance, but then we would need arguments to aclocal/autoconf
  88     to properly find them all when generating configure.  I would
  89     discourage that.
  90 </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>
  91     Most comments should use {octothorpes, shibboleths, hash marks,
  92     pound signs, whatever} rather than "<code class="literal">dnl</code>".
  93     Nearly all comments in <code class="filename">configure.ac</code> should.
  94     Comments inside macros written in ancillary
  95     <code class="filename">.m4</code> files should.
  96     About the only comments which should <span class="emphasis"><em>not</em></span>
  97     use <code class="literal">#</code>, but use <code class="literal">dnl</code> instead,
  98     are comments <span class="emphasis"><em>outside</em></span> our own macros in the ancillary
  99     files.  The difference is that <code class="literal">#</code> comments show up in
 100     <code class="filename">configure</code> (which is most helpful for debugging),
 101     while <code class="literal">dnl</code>'d lines just vanish.  Since the macros
 102     in ancillary files generate code which appears in odd places,
 103     their "outside" comments tend to not be useful while reading
 104     <code class="filename">configure</code>.
 105   </p><p>
 106     Do not use any <code class="code">$target*</code> variables, such as
 107     <code class="varname">$target_alias</code>.  The single exception is in
 108     <code class="filename">configure.ac</code>, for automake+dejagnu's sake.
 109   </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>
 110     The nice thing about
 111     <code class="filename">acinclude.m4</code>/<code class="filename">aclocal.m4</code>
 112     is that macros aren't
 113     actually performed/called/expanded/whatever here, just loaded.  So
 114     we can arrange the contents however we like.  As of this writing,
 115     <code class="filename">acinclude.m4</code> is arranged as follows:
 116   </p><pre class="programlisting">
 117     GLIBCXX_CHECK_HOST
 118     GLIBCXX_TOPREL_CONFIGURE
 119     GLIBCXX_CONFIGURE
 120   </pre><p>
 121     All the major variable "discovery" is done here.
 122     <code class="varname">CXX</code>, multilibs,
 123     etc.
 124   </p><pre class="programlisting">
 125     fragments included from elsewhere
 126   </pre><p>
 127     Right now, "fragments" == "the math/linkage bits".
 128   </p><pre class="programlisting">
 129     GLIBCXX_CHECK_COMPILER_FEATURES
 130     GLIBCXX_CHECK_LINKER_FEATURES
 131     GLIBCXX_CHECK_WCHAR_T_SUPPORT
 132 </pre><p>
 133   Next come extra compiler/linker feature tests.  Wide character
 134   support was placed here because I couldn't think of another place
 135   for it.  It will probably get broken apart like the math tests,
 136   because we're still disabling wchars on systems which could actually
 137   support them.
 138 </p><pre class="programlisting">
 139     GLIBCXX_CHECK_SETRLIMIT_ancilliary
 140     GLIBCXX_CHECK_SETRLIMIT
 141     GLIBCXX_CHECK_S_ISREG_OR_S_IFREG
 142     GLIBCXX_CHECK_POLL
 143     GLIBCXX_CHECK_WRITEV
 144
 145     GLIBCXX_CONFIGURE_TESTSUITE
 146 </pre><p>
 147   Feature tests which only get used in one place.  Here, things used
 148   only in the testsuite, plus a couple bits used in the guts of I/O.
 149 </p><pre class="programlisting">
 150     GLIBCXX_EXPORT_INCLUDES
 151     GLIBCXX_EXPORT_FLAGS
 152     GLIBCXX_EXPORT_INSTALL_INFO
 153 </pre><p>
 154   Installation variables, multilibs, working with the rest of the
 155   compiler.  Many of the critical variables used in the makefiles are
 156   set here.
 157 </p><pre class="programlisting">
 158     GLIBGCC_ENABLE
 159     GLIBCXX_ENABLE_C99
 160     GLIBCXX_ENABLE_CHEADERS
 161     GLIBCXX_ENABLE_CLOCALE
 162     GLIBCXX_ENABLE_CONCEPT_CHECKS
 163     GLIBCXX_ENABLE_CSTDIO
 164     GLIBCXX_ENABLE_CXX_FLAGS
 165     GLIBCXX_ENABLE_C_MBCHAR
 166     GLIBCXX_ENABLE_DEBUG
 167     GLIBCXX_ENABLE_DEBUG_FLAGS
 168     GLIBCXX_ENABLE_LONG_LONG
 169     GLIBCXX_ENABLE_PCH
 170     GLIBCXX_ENABLE_SYMVERS
 171     GLIBCXX_ENABLE_THREADS
 172 </pre><p>
 173   All the features which can be controlled with enable/disable
 174   configure options.  Note how they're alphabetized now?  Keep them
 175   like that.  :-)
 176 </p><pre class="programlisting">
 177     AC_LC_MESSAGES
 178     libtool bits
 179 </pre><p>
 180   Things which we don't seem to use directly, but just has to be
 181   present otherwise stuff magically goes wonky.
 182 </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>
 183     All the <code class="literal">GLIBCXX_ENABLE_FOO</code> macros use a common
 184     helper, <code class="literal">GLIBCXX_ENABLE</code>.  (You don't have to use
 185     it, but it's easy.)  The helper does two things for us:
 186   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
 187      Builds the call to the <code class="literal">AC_ARG_ENABLE</code> macro, with
 188      <code class="option">--help</code> text
 189      properly quoted and aligned.  (Death to changequote!)
 190    </p></li><li class="listitem"><p>
 191      Checks the result against a list of allowed possibilities, and
 192      signals a fatal error if there's no match.  This means that the
 193      rest of the <code class="literal">GLIBCXX_ENABLE_FOO</code> macro doesn't need to test for
 194      strange arguments, nor do we need to protect against
 195      empty/whitespace strings with the <code class="code">"x$foo" = "xbar"</code>
 196      idiom.
 197    </p></li></ol></div><p>Doing these things correctly takes some extra autoconf/autom4te code,
 198    which made our macros nearly illegible.  So all the ugliness is factored
 199    out into this one helper macro.
 200 </p><p>Many of the macros take an argument, passed from when they are expanded
 201    in configure.ac.  The argument controls the default value of the
 202    enable/disable switch.  Previously, the arguments themselves had defaults.
 203    Now they don't, because that's extra complexity with zero gain for us.
 204 </p><p>There are three "overloaded signatures".  When reading the descriptions
 205    below, keep in mind that the brackets are autoconf's quotation characters,
 206    and that they will be stripped.  Examples of just about everything occur
 207    in acinclude.m4, if you want to look.
 208 </p><pre class="programlisting">
 209     GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING)
 210     GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c)
 211     GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER)
 212 </pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 213      <code class="literal">FEATURE</code> is the string that follows
 214      <code class="option">--enable</code>.  The results of the
 215      test (such as it is) will be in the variable
 216      <code class="varname">$enable_FEATURE</code>,
 217      where <code class="literal">FEATURE</code> has been squashed.  Example:
 218      <code class="code">[extra-foo]</code>, controlled by the
 219      <code class="option">--enable-extra-foo</code>
 220      option and stored in <code class="varname">$enable_extra_foo</code>.
 221    </p></li><li class="listitem"><p>
 222      <code class="literal">DEFAULT</code> is the value to store in
 223      <code class="varname">$enable_FEATURE</code> if the user does
 224      not pass <code class="option">--enable</code>/<code class="option">--disable</code>.
 225      It should be one of the permitted values passed later.
 226      Examples: <code class="code">[yes]</code>, or <code class="code">[bar]</code>, or
 227      <code class="code">[$1]</code> (which passes the argument given to the
 228      <code class="literal">GLIBCXX_ENABLE_FOO</code> macro as the default).
 229    </p><p>
 230      For cases where we need to probe for particular models of things,
 231      it is useful to have an undocumented "auto" value here (see
 232      <code class="literal">GLIBCXX_ENABLE_CLOCALE</code> for an example).
 233    </p></li><li class="listitem"><p>
 234      <code class="literal">HELP-ARG</code> is any text to append to the option string
 235      itself in the <code class="option">--help</code> output.  Examples:
 236      <code class="code">[]</code> (i.e., an empty string, which appends nothing),
 237      <code class="code">[=BAR]</code>, which produces <code class="code">--enable-extra-foo=BAR</code>,
 238      and <code class="code">[@&lt;:@=BAR@:&gt;@]</code>, which produces
 239      <code class="code">--enable-extra-foo[=BAR]</code>.  See the difference?  See
 240      what it implies to the user?
 241    </p><p>
 242      If you're wondering what that line noise in the last example was,
 243      that's how you embed autoconf special characters in output text.
 244      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>
 245      and you should use them whenever necessary.
 246  </p></li><li class="listitem"><p><code class="literal">HELP-STRING</code> is what you think it is.  Do not include the
 247    "default" text like we used to do; it will be done for you by
 248    <code class="literal">GLIBCXX_ENABLE</code>.  By convention, these are not full English
 249    sentences.  Example: <code class="literal">[turn on extra foo]</code>
 250    </p></li></ul></div><p>
 251   With no other arguments, only the standard autoconf patterns are
 252   allowed: "<code class="option">--{enable,disable}-foo[={yes,no}]</code>" The
 253   <code class="varname">$enable_FEATURE</code> variable is guaranteed to equal
 254   either "<code class="literal">yes</code>" or "<code class="literal">no</code>"
 255   after the macro.  If the user tries to pass something else, an
 256   explanatory error message will be given, and configure will halt.
 257 </p><p>
 258   The second signature takes a fifth argument, "<code class="code">[permit
 259   a | b | c | ...]</code>"
 260   This allows <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> or
 261   ... after the equals sign in the option, and
 262   <code class="varname">$enable_FEATURE</code> is
 263   guaranteed to equal one of them after the macro.  Note that if you
 264   want to allow plain <code class="option">--enable</code>/<code class="option">--disable</code>
 265   with no "<code class="literal">=whatever</code>", you must
 266   include "<code class="literal">yes</code>" and "<code class="literal">no</code>" in the
 267   list of permitted values.  Also note that whatever you passed as
 268   <code class="literal">DEFAULT</code> must be in the list.  If the
 269   user tries to pass something not on the list, a semi-explanatory
 270   error message will be given, and configure will halt.  Example:
 271   <code class="code">[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code>
 272 </p><p>
 273   The third signature takes a fifth argument.  It is arbitrary shell
 274   code to execute if the user actually passes the enable/disable
 275   option.  (If the user does not, the default is used.  Duh.)  No
 276   argument checking at all is done in this signature.  See
 277   <code class="literal">GLIBCXX_ENABLE_CXX_FLAGS</code> for an example of handling,
 278   and an error message.
 279 </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>
 280 The <code class="filename">libstdc++.so</code> shared library must
 281 be carefully managed to maintain binary compatible with older versions
 282 of the library. This ensures a new version of the library is still usable by
 283 programs that were linked against an older version.
 284 </p><p>
 285 Dependent on the target supporting it, the library uses <a class="link" href="https://www.akkadia.org/drepper/symbol-versioning" target="_top">ELF
 286 symbol versioning</a> for all exported symbols. The symbol versions
 287 are defined by a <a class="link" href="https://sourceware.org/binutils/docs/ld/VERSION.html" target="_top">linker
 288 script</a> that assigns a version to every symbol.
 289 The set of symbols in each version is fixed when a GCC
 290 release is made, and must not change after that.
 291 </p><p> When new symbols are added to the library they must be added
 292 to a new symbol version, which must be created the first time new symbols
 293 are added after a release. Adding a new symbol version involves the
 294 following steps:
 295 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 296 Edit <code class="filename">acinclude.m4</code> to update the "revision" value of
 297 <code class="varname">libtool_VERSION</code>, e.g. from <code class="literal">6:22:0</code>
 298 to <code class="literal">6:23:0</code>, which will cause the shared library to be
 299 built as <code class="filename">libstdc++.so.6.0.23</code>.
 300 </p></li><li class="listitem"><p>
 301 Regenerate the <code class="filename">configure</code> script by running the
 302 <span class="command"><strong>autoreconf</strong></span> tool from the correct version of the Autoconf
 303 package (as dictated by the <a class="link" href="https://gcc.gnu.org/install/prerequisites.html" target="_top">GCC
 304 prerequisites</a>).
 305 </p></li><li class="listitem"><p>
 306 Edit the file <code class="filename">config/abi/pre/gnu.ver</code> to
 307 add a new version node after the last new node. The node name should be
 308 <code class="literal">GLIBCXX_3.4.X</code> where <code class="literal">X</code> is the new
 309 revision set in <code class="filename">acinclude.m4</code>, and the node should
 310 depend on the previous version e.g.
 311 </p><pre class="programlisting">
 312     GLIBCXX_3.4.23 {
 313
 314     } GLIBCXX_3.4.22;
 315 </pre><p>
 316 For symbols in the ABI runtime, libsupc++, the symbol version naming uses
 317 <code class="literal">CXXABI_1.3.Y</code> where <code class="literal">Y</code> increases
 318 monotonically with each new version. Again, the new node must depend on the
 319 previous version node e.g.
 320 </p><pre class="programlisting">
 321     CXXABI_1.3.11 {
 322
 323     } CXXABI_1.3.10;
 324 </pre><p>
 325 </p></li><li class="listitem"><p>
 326 In order for the <a class="link" href="test.html#test.run.variations" title="Variations">check-abi</a> test
 327 target to pass the testsuite must be updated to know about the new symbol
 328 version(s). Edit the file <code class="filename">testsuite/util/testsuite_abi.cc</code>
 329 file to add the new versions to the <code class="varname">known_versions</code> list,
 330 and update the checks for the latest versions that set the
 331 <code class="varname">latestp</code> variable).
 332 </p></li><li class="listitem"><p>
 333 Add the library (<code class="filename">libstdc++.so.6.0.X</code>)
 334 and symbols versions
 335 (<code class="literal">GLIBCXX_3.4.X</code> and <code class="literal">CXXABI_1.3.Y</code>)
 336 to the <a class="link" href="abi.html#abi.versioning.history" title="History">History</a> section in
 337 <code class="filename">doc/xml/manual/abi.xml</code> at the relevant places.
 338 </p></li></ul></div><p>
 339 Once the new symbol version has been added you can add the names of your new
 340 symbols in the new version node:
 341 </p><pre class="programlisting">
 342     GLIBCXX_3.4.23 {
 343
 344       # basic_string&lt;C, T, A&gt;::_Alloc_hider::_Alloc_hider(C*, A&amp;&amp;)
 345       _ZNSt7__cxx1112basic_stringI[cw]St11char_traitsI[cw]ESaI[cw]EE12_Alloc_hiderC[12]EP[cw]OS3_;
 346
 347     } GLIBCXX_3.4.22;
 348 </pre><p>
 349 You can either use mangled names, or demangled names inside an
 350 <code class="literal">extern "C++"</code> block. You might find that the new symbol
 351 matches an existing pattern in an old symbol version (causing the
 352 <code class="literal">check-abi</code> test target to fail). If that happens then the
 353 existing pattern must be adjusted to be more specific so that it doesn't
 354 match the new symbol.
 355 </p><p>
 356 For an example of these steps, including adjusting old patterns to be less
 357 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>
 358 and the attached patch.
 359 </p><p>
 360 If it wasn't done for the last release, you might also need to regenerate
 361 the <code class="filename">baseline_symbols.txt</code> file that defines the set
 362 of expected symbols for old symbol versions. A new baseline file can be
 363 generated by running <strong class="userinput"><code>make new-abi-baseline</code></strong> in the
 364 <code class="filename"><em class="replaceable"><code>libbuilddir</code></em>/testsuite</code>
 365 directory. Be sure to generate the baseline from a clean build using
 366 unmodified sources, or you will incorporate your local changes into the
 367 baseline file.
 368 </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>
 369     The build process has to make all of object files needed for
 370     static or shared libraries, but first it has to generate some
 371     include files. The general order is as follows:
 372   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
 373      make include files, make pre-compiled headers
 374    </p></li><li class="listitem"><p>
 375      make libsupc++
 376    </p><p>
 377      Generates a libtool convenience library,
 378      <code class="filename">libsupc++convenience</code> with language-support
 379      routines. Also generates a freestanding static library,
 380      <code class="filename">libsupc++.a</code>.
 381    </p></li><li class="listitem"><p>
 382      make src
 383    </p><p>
 384      Generates two convenience libraries, one for C++98 and one for
 385      C++11, various compatibility files for shared and static
 386      libraries, and then collects all the generated bits and creates
 387      the final libstdc++ libraries.
 388   </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
 389      make src/c++98
 390    </p><p>
 391      Generates a libtool convenience library,
 392      <code class="filename">libc++98convenience</code> with language-support
 393      routines. Uses the <code class="option">-std=gnu++98</code> dialect.
 394    </p></li><li class="listitem"><p>
 395      make src/c++11
 396    </p><p>
 397      Generates a libtool convenience library,
 398      <code class="filename">libc++11convenience</code> with language-support
 399      routines. Uses the <code class="option">-std=gnu++11</code> dialect.
 400    </p></li><li class="listitem"><p>
 401      make src
 402    </p><p>
 403      Generates needed compatibility objects for shared and static
 404      libraries. Shared-only code is seggregated at compile-time via
 405      the macro <code class="literal">_GLIBCXX_SHARED</code>.
 406    </p><p>
 407      Then, collects all the generated convenience libraries, adds in
 408      any required compatibility objects, and creates the final shared
 409      and static libraries: <code class="filename">libstdc++.so</code> and
 410      <code class="filename">libstdc++.a</code>.
 411    </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>