xref: /netbsd-src/external/gpl3/gcc.old/dist/libstdc++-v3/doc/html/manual/appendix_porting.html (revision 8feb0f0b7eaff0608f8350bbfa3098827b4bb91b) 
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></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">
23No <code class="code">stream::attach(int fd)</code>
24</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx98">
25Support for C++98 dialect.
26</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_tr1">
27Support for C++TR1 dialect.
28</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx11">
29Support 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">
48configure
49</code>
50</pre><p>
51The <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">
58make all
59</code>
60</pre><p>
61in 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>
280The <code class="filename">libstdc++.so</code> shared library must
281be carefully managed to maintain binary compatible with older versions
282of the library. This ensures a new version of the library is still usable by
283programs that were linked against an older version.
284</p><p>
285Dependent on the target supporting it, the library uses <a class="link" href="https://www.akkadia.org/drepper/symbol-versioning" target="_top">ELF
286symbol versioning</a> for all exported symbols. The symbol versions
287are defined by a <a class="link" href="https://sourceware.org/binutils/docs/ld/VERSION.html" target="_top">linker
288script</a> that assigns a version to every symbol.
289The set of symbols in each version is fixed when a GCC
290release is made, and must not change after that.
291</p><p> When new symbols are added to the library they must be added
292to a new symbol version, which must be created the first time new symbols
293are added after a release. Adding a new symbol version involves the
294following steps:
295</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
296Edit <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>
298to <code class="literal">6:23:0</code>, which will cause the shared library to be
299built as <code class="filename">libstdc++.so.6.0.23</code>.
300</p></li><li class="listitem"><p>
301Regenerate 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
303package (as dictated by the <a class="link" href="https://gcc.gnu.org/install/prerequisites.html" target="_top">GCC
304prerequisites</a>).
305</p></li><li class="listitem"><p>
306Edit the file <code class="filename">config/abi/pre/gnu.ver</code> to
307add 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
309revision set in <code class="filename">acinclude.m4</code>, and the node should
310depend 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>
316For 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
318monotonically with each new version. Again, the new node must depend on the
319previous 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>
326In order for the <a class="link" href="test.html#test.run.variations" title="Variations">check-abi</a> test
327target to pass the testsuite must be updated to know about the new symbol
328version(s). Edit the file <code class="filename">testsuite/util/testsuite_abi.cc</code>
329file to add the new versions to the <code class="varname">known_versions</code> list,
330and update the checks for the latest versions that set the
331<code class="varname">latestp</code> variable).
332</p></li><li class="listitem"><p>
333Add the library (<code class="filename">libstdc++.so.6.0.X</code>)
334and symbols versions
335(<code class="literal">GLIBCXX_3.4.X</code> and <code class="literal">CXXABI_1.3.Y</code>)
336to 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>
339Once the new symbol version has been added you can add the names of your new
340symbols 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>
349You 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
351matches 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
353existing pattern must be adjusted to be more specific so that it doesn't
354match the new symbol.
355</p><p>
356For an example of these steps, including adjusting old patterns to be less
357greedy, 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>
358and the attached patch.
359</p><p>
360If it wasn't done for the last release, you might also need to regenerate
361the <code class="filename">baseline_symbols.txt</code> file that defines the set
362of expected symbols for old symbol versions. A new baseline file can be
363generated 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>
365directory. Be sure to generate the baseline from a clean build using
366unmodified sources, or you will incorporate your local changes into the
367baseline 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>