| <?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><dt><span class="section"><a href="appendix_porting.html#build_hacking.generated">Generated files</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><dt><span class="section"><a href="api.html#api.rel_123"><code class="constant">12.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_131"><code class="constant">13</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_133"><code class="constant">13.3</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_141"><code class="constant">14</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_151"><code class="constant">15</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_16"><code class="constant">16</code></a></span></dt><dt><span class="section"><a href="api.html#api.rel_17"><code class="constant">17</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="https://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 have 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">[@<:@=BAR@:>@]</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="https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/" 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 compatibility 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<C, T, A>::_Alloc_hider::_Alloc_hider(C*, A&&) | |
| _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 the 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 several convenience libraries, | |
| 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 the library components | |
| defined by C++98. 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 the library components | |
| that were added or changed in C++11. | |
| Uses the <code class="option">-std=gnu++11</code> dialect. | |
| </p></li><li class="listitem"><p> | |
| make src/c++17 | |
| </p><p> | |
| Generates a libtool convenience library, | |
| <code class="filename">libc++17convenience</code> with the library components | |
| that were added or changed in C++17. | |
| Uses the <code class="option">-std=gnu++17</code> dialect. | |
| </p></li><li class="listitem"><p> | |
| make src/c++20 | |
| </p><p> | |
| Generates a libtool convenience library, | |
| <code class="filename">libc++20convenience</code> with the library components | |
| that were added or changed in C++20. | |
| Uses the <code class="option">-std=gnu++20</code> dialect. | |
| </p></li><li class="listitem"><p> | |
| make src/c++23 | |
| </p><p> | |
| Generates a libtool convenience library, | |
| <code class="filename">libc++23convenience</code> with the library components | |
| that were added or changed in C++23. | |
| At the time of writing (GCC 14) this convenience library is included | |
| in <code class="filename">libstdc++exp.a</code> and not in the final | |
| <code class="filename">libstdc++</code> libraries. | |
| Uses the <code class="option">-std=gnu++23</code> dialect. | |
| </p></li><li class="listitem"><p> | |
| make src/filesystem | |
| </p><p> | |
| Generates a libtool convenience library, | |
| <code class="filename">libstdc++fsconvenience</code>, | |
| and a standalone static library, | |
| <code class="filename">libstdc++fs.a</code>. | |
| These contain definitions of the Filesystem TS extensions. | |
| Uses the <code class="option">-std=gnu++17</code> dialect. | |
| </p></li><li class="listitem"><p> | |
| make src/libbacktrace | |
| </p><p> | |
| Generates a libtool convenience library, | |
| <code class="filename">libstdc++_libbacktrace</code>, | |
| containing the libbacktrace definitions used by the C++23 | |
| <code class="classname">std::stacktrace</code> feature. | |
| </p></li><li class="listitem"><p> | |
| make src/experimental | |
| </p><p> | |
| Generates a standalone static library, | |
| <code class="filename">libstdc++exp.a</code>, containing the symbol definitions | |
| for experimental features and extensions. This collects the convenience | |
| libraries <code class="filename">libstdc++fsconvenience</code>, | |
| <code class="filename">libstdc++_libbacktrace</code>, and | |
| (at the time of writing) <code class="filename">libc++23convenience</code> | |
| and combines them into one. | |
| Uses the <code class="option">-std=gnu++17</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 segregated at compile-time via | |
| the macro <code class="literal">_GLIBCXX_SHARED</code>. | |
| </p><p> | |
| Then, collects all the generated convenience libraries that weren't | |
| added to <code class="filename">libstdc++exp.a</code>, | |
| 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 class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.generated"></a>Generated files</h3></div></div></div><p> | |
| Some files in the libstdc++ source tree are auto-generated from other files. | |
| In general, these are not regenerated automatically, so it must be done | |
| manually when the files they depend on are updated. | |
| </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> | |
| The header file | |
| <code class="filename">include/bits/version.h</code> | |
| is generated from <code class="filename">version.def</code> and | |
| <code class="filename">version.tpl</code> in the same directory. | |
| After editing those files, either run <span class="command"><strong>autogen version.def</strong></span> | |
| in the <code class="filename">include</code> directory of the | |
| source tree, or run <span class="command"><strong>make update-version</strong></span> in the | |
| <code class="filename">include</code> directory of the build tree. | |
| </p></li><li class="listitem"><p> | |
| The header file | |
| <code class="filename">include/bits/unicode-data.h</code> | |
| is generated by the Python script | |
| <code class="filename">../contrib/unicode/gen_libstdcxx_unicode_data.py</code> | |
| using data files in the same directory. The script contains information | |
| on which data files it uses and how to update them. | |
| </p></li><li class="listitem"><p> | |
| The header file | |
| <code class="filename">include/bits/text_encoding-data.h</code> | |
| is generated by the Python script | |
| <code class="filename">scripts/gen_text_encoding_data.py</code> | |
| using the CSV file <a class="link" href="https://www.iana.org/assignments/character-sets/character-sets-1.csv" target="_top">https://www.iana.org/assignments/character-sets/character-sets-1.csv</a> | |
| from the <a class="link" href="https://www.iana.org/time-zones" target="_top">IANA Character Sets</a> | |
| registry. | |
| </p></li><li class="listitem"><p> | |
| The data file <code class="filename">src/c++20/tzdata.zi</code> is copied verbatim | |
| from the | |
| <a class="link" href="https://www.iana.org/time-zones" target="_top">IANA Time Zone Database</a> | |
| (the latest version can be downloaded from | |
| <a class="link" href="https://data.iana.org/time-zones/tzdb/tzdata.zi" target="_top">https://data.iana.org/time-zones/tzdb/tzdata.zi</a>). | |
| Libstdc++ uses this data file to populate a | |
| <code class="classname">std::chrono::tzdb</code> object in case the system does not | |
| provide a copy of the file. | |
| See <a class="xref" href="configure.html" title="Configure">Configuring</a> for the | |
| <code class="code">--with-libstdcxx-zoneinfo</code> option that determines whether | |
| this file is used. | |
| </p></li><li class="listitem"><p> | |
| The header file | |
| <code class="filename">src/c++20/windows_zones-map.h</code> | |
| is generated by the Python script | |
| <code class="filename">scripts/gen_windows_zones_map.py</code> | |
| using the XML file <a class="link" href="https://github.com/unicode-org/cldr/blob/main/common/supplemental/windowsZones.xml" target="_top">https://github.com/unicode-org/cldr/blob/main/common/supplemental/windowsZones.xml</a> | |
| from the Unicode CLDR Project. | |
| </p></li></ul></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> |