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