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"> 3<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 V1.75.2" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="/spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="source_design_notes.html" title="Design Notes" /><link rel="next" href="internals.html" title="Porting to New Hardware or Operating Systems" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix B. 4 Porting and Maintenance 5 6</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="source_design_notes.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix B. Porting and Maintenance"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting"></a>Appendix B. 7 Porting and Maintenance 8 <a id="id631944" class="indexterm"></a> 9</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.map">Overview: What Comes from Where</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="sect1"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="sect2"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="sect1"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="sect2"><a href="test.html#test.organization">Organization</a></span></dt><dt><span class="sect2"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dt><span class="sect2"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="sect2"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dt><span class="sect2"><a href="test.html#test.special">Special Topics</a></span></dt></dl></dd><dt><span class="sect1"><a href="abi.html">ABI Policy and Guidelines</a></span></dt><dd><dl><dt><span class="sect2"><a href="abi.html#abi.cxx_interface">The C++ Interface</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.versioning">Versioning</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.changes_allowed">Allowed Changes</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.changes_no">Prohibited Changes</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.testing">Testing</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.issues">Outstanding Issues</a></span></dt></dl></dd><dt><span class="sect1"><a href="api.html">API Evolution and Deprecation History</a></span></dt><dd><dl><dt><span class="sect2"><a href="api.html#api.rel_300"><code class="constant">3.0</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_310"><code class="constant">3.1</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_320"><code class="constant">3.2</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_330"><code class="constant">3.3</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_340"><code class="constant">3.4</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_400"><code class="constant">4.0</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_410"><code class="constant">4.1</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_420"><code class="constant">4.2</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_430"><code class="constant">4.3</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_440"><code class="constant">4.4</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_450"><code class="constant">4.5</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="backwards.html">Backwards Compatibility</a></span></dt><dd><dl><dt><span class="sect2"><a href="backwards.html#backwards.first">First</a></span></dt><dt><span class="sect2"><a href="backwards.html#backwards.second">Second</a></span></dt><dt><span class="sect2"><a href="backwards.html#backwards.third">Third</a></span></dt></dl></dd></dl></div><div class="sect1" title="Configure and Build Hacking"><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="sect2" title="Prerequisites"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.prereq"></a>Prerequisites</h3></div></div></div><p> 10 As noted <a class="ulink" href="http://gcc.gnu.org/install/prerequisites.html" target="_top">previously</a>, 11 certain other tools are necessary for hacking on files that 12 control configure (<code class="code">configure.ac</code>, 13 <code class="code">acinclude.m4</code>) and make 14 (<code class="code">Makefile.am</code>). These additional tools 15 (<code class="code">automake</code>, and <code class="code">autoconf</code>) are further 16 described in detail in their respective manuals. All the libraries 17 in GCC try to stay in sync with each other in terms of versions of 18 the auto-tools used, so please try to play nicely with the 19 neighbors. 20 </p></div><div class="sect2" title="Overview: What Comes from Where"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.map"></a>Overview: What Comes from Where</h3></div></div></div><pre class="screen"> 21 <img src="/images/confdeps.png" alt="Dependency Graph Configure to Build Files" /> 22 </pre><p> 23 Regenerate all generated files by using the command sequence 24 <code class="code">"autoreconf"</code> at the top level of the libstdc++ source 25 directory. The following will also work, but is much more complex: 26 <code class="code">"aclocal-1.11 && autoconf-2.64 && 27 autoheader-2.64 && automake-1.11"</code> The version 28 numbers may be absent entirely or otherwise vary depending on 29 <a class="ulink" href="http://gcc.gnu.org/install/prerequisites.html" target="_top">the 30 current requirements</a> and your vendor's choice of 31 installation names. 32 </p></div><div class="sect2" title="Storing Information in non-AC files (like configure.host)"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.scripts"></a>Storing Information in non-AC files (like configure.host)</h3></div></div></div><p> 33 Until that glorious day when we can use AC_TRY_LINK with a 34 cross-compiler, we have to hardcode the results of what the tests 35 would have shown if they could be run. So we have an inflexible 36 mess like crossconfig.m4. 37 </p><p> 38 Wouldn't it be nice if we could store that information in files 39 like configure.host, which can be modified without needing to 40 regenerate anything, and can even be tweaked without really 41 knowing how the configury all works? Perhaps break the pieces of 42 crossconfig.m4 out and place them in their appropriate 43 config/{cpu,os} directory. 44 </p><p> 45 Alas, writing macros like 46 "<code class="code">AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside 47 files which are passed through autoconf. Files which are pure 48 shell script can be source'd at configure time. Files which 49 contain autoconf macros must be processed with autoconf. We could 50 still try breaking the pieces out into "config/*/cross.m4" bits, 51 for instance, but then we would need arguments to aclocal/autoconf 52 to properly find them all when generating configure. I would 53 discourage that. 54</p></div><div class="sect2" title="Coding and Commenting Conventions"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.conventions"></a>Coding and Commenting Conventions</h3></div></div></div><p> 55 Most comments should use {octothorpes, shibboleths, hash marks, 56 pound signs, whatever} rather than "dnl". Nearly all comments in 57 configure.ac should. Comments inside macros written in ancilliary 58 .m4 files should. About the only comments which should 59 <span class="emphasis"><em>not</em></span> use #, but use dnl instead, are comments 60 <span class="emphasis"><em>outside</em></span> our own macros in the ancilliary 61 files. The difference is that # comments show up in 62 <code class="code">configure</code> (which is most helpful for debugging), 63 while dnl'd lines just vanish. Since the macros in ancilliary 64 files generate code which appears in odd places, their "outside" 65 comments tend to not be useful while reading 66 <code class="code">configure</code>. 67 </p><p> 68 Do not use any <code class="code">$target*</code> variables, such as 69 <code class="code">$target_alias</code>. The single exception is in 70 configure.ac, for automake+dejagnu's sake. 71 </p></div><div class="sect2" title="The acinclude.m4 layout"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.acinclude"></a>The acinclude.m4 layout</h3></div></div></div><p> 72 The nice thing about acinclude.m4/aclocal.m4 is that macros aren't 73 actually performed/called/expanded/whatever here, just loaded. So 74 we can arrange the contents however we like. As of this writing, 75 acinclude.m4 is arranged as follows: 76 </p><pre class="programlisting"> 77 GLIBCXX_CHECK_HOST 78 GLIBCXX_TOPREL_CONFIGURE 79 GLIBCXX_CONFIGURE 80 </pre><p> 81 All the major variable "discovery" is done here. CXX, multilibs, 82 etc. 83 </p><pre class="programlisting"> 84 fragments included from elsewhere 85 </pre><p> 86 Right now, "fragments" == "the math/linkage bits". 87 </p><pre class="programlisting"> 88 GLIBCXX_CHECK_COMPILER_FEATURES 89 GLIBCXX_CHECK_LINKER_FEATURES 90 GLIBCXX_CHECK_WCHAR_T_SUPPORT 91</pre><p> 92 Next come extra compiler/linker feature tests. Wide character 93 support was placed here because I couldn't think of another place 94 for it. It will probably get broken apart like the math tests, 95 because we're still disabling wchars on systems which could actually 96 support them. 97</p><pre class="programlisting"> 98 GLIBCXX_CHECK_SETRLIMIT_ancilliary 99 GLIBCXX_CHECK_SETRLIMIT 100 GLIBCXX_CHECK_S_ISREG_OR_S_IFREG 101 GLIBCXX_CHECK_POLL 102 GLIBCXX_CHECK_WRITEV 103 104 GLIBCXX_CONFIGURE_TESTSUITE 105</pre><p> 106 Feature tests which only get used in one place. Here, things used 107 only in the testsuite, plus a couple bits used in the guts of I/O. 108</p><pre class="programlisting"> 109 GLIBCXX_EXPORT_INCLUDES 110 GLIBCXX_EXPORT_FLAGS 111 GLIBCXX_EXPORT_INSTALL_INFO 112</pre><p> 113 Installation variables, multilibs, working with the rest of the 114 compiler. Many of the critical variables used in the makefiles are 115 set here. 116</p><pre class="programlisting"> 117 GLIBGCC_ENABLE 118 GLIBCXX_ENABLE_C99 119 GLIBCXX_ENABLE_CHEADERS 120 GLIBCXX_ENABLE_CLOCALE 121 GLIBCXX_ENABLE_CONCEPT_CHECKS 122 GLIBCXX_ENABLE_CSTDIO 123 GLIBCXX_ENABLE_CXX_FLAGS 124 GLIBCXX_ENABLE_C_MBCHAR 125 GLIBCXX_ENABLE_DEBUG 126 GLIBCXX_ENABLE_DEBUG_FLAGS 127 GLIBCXX_ENABLE_LONG_LONG 128 GLIBCXX_ENABLE_PCH 129 GLIBCXX_ENABLE_SJLJ_EXCEPTIONS 130 GLIBCXX_ENABLE_SYMVERS 131 GLIBCXX_ENABLE_THREADS 132</pre><p> 133 All the features which can be controlled with enable/disable 134 configure options. Note how they're alphabetized now? Keep them 135 like that. :-) 136</p><pre class="programlisting"> 137 AC_LC_MESSAGES 138 libtool bits 139</pre><p> 140 Things which we don't seem to use directly, but just has to be 141 present otherwise stuff magically goes wonky. 142</p></div><div class="sect2" title="GLIBCXX_ENABLE, the --enable maker"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.enable"></a><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</h3></div></div></div><p> 143 All the GLIBCXX_ENABLE_FOO macros use a common helper, 144 GLIBCXX_ENABLE. (You don't have to use it, but it's easy.) The 145 helper does two things for us: 146 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> 147 Builds the call to the AC_ARG_ENABLE macro, with --help text 148 properly quoted and aligned. (Death to changequote!) 149 </p></li><li class="listitem"><p> 150 Checks the result against a list of allowed possibilities, and 151 signals a fatal error if there's no match. This means that the 152 rest of the GLIBCXX_ENABLE_FOO macro doesn't need to test for 153 strange arguments, nor do we need to protect against 154 empty/whitespace strings with the <code class="code">"x$foo" = "xbar"</code> 155 idiom. 156 </p></li></ol></div><p>Doing these things correctly takes some extra autoconf/autom4te code, 157 which made our macros nearly illegible. So all the ugliness is factored 158 out into this one helper macro. 159</p><p>Many of the macros take an argument, passed from when they are expanded 160 in configure.ac. The argument controls the default value of the 161 enable/disable switch. Previously, the arguments themselves had defaults. 162 Now they don't, because that's extra complexity with zero gain for us. 163</p><p>There are three "overloaded signatures". When reading the descriptions 164 below, keep in mind that the brackets are autoconf's quotation characters, 165 and that they will be stripped. Examples of just about everything occur 166 in acinclude.m4, if you want to look. 167</p><pre class="programlisting"> 168 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) 169 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) 170 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) 171</pre><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 172 FEATURE is the string that follows --enable. The results of the 173 test (such as it is) will be in the variable $enable_FEATURE, 174 where FEATURE has been squashed. Example: 175 <code class="code">[extra-foo]</code>, controlled by the --enable-extra-foo 176 option and stored in $enable_extra_foo. 177 </p></li><li class="listitem"><p> 178 DEFAULT is the value to store in $enable_FEATURE if the user does 179 not pass --enable/--disable. It should be one of the permitted 180 values passed later. Examples: <code class="code">[yes]</code>, or 181 <code class="code">[bar]</code>, or <code class="code">[$1]</code> (which passes the 182 argument given to the GLIBCXX_ENABLE_FOO macro as the 183 default). 184 </p><p> 185 For cases where we need to probe for particular models of things, 186 it is useful to have an undocumented "auto" value here (see 187 GLIBCXX_ENABLE_CLOCALE for an example). 188 </p></li><li class="listitem"><p> 189 HELP-ARG is any text to append to the option string itself in the 190 --help output. Examples: <code class="code">[]</code> (i.e., an empty string, 191 which appends nothing), <code class="code">[=BAR]</code>, which produces 192 <code class="code">--enable-extra-foo=BAR</code>, and 193 <code class="code">[@<:@=BAR@:>@]</code>, which produces 194 <code class="code">--enable-extra-foo[=BAR]</code>. See the difference? See 195 what it implies to the user? 196 </p><p> 197 If you're wondering what that line noise in the last example was, 198 that's how you embed autoconf special characters in output text. 199 They're called <a class="ulink" href="http://www.gnu.org/software/autoconf/manual/autoconf.html#Quadrigraphs" target="_top"><span class="emphasis"><em>quadrigraphs</em></span></a> 200 and you should use them whenever necessary. 201 </p></li><li class="listitem"><p>HELP-STRING is what you think it is. Do not include the 202 "default" text like we used to do; it will be done for you by 203 GLIBCXX_ENABLE. By convention, these are not full English 204 sentences. Example: [turn on extra foo] 205 </p></li></ul></div><p> 206 With no other arguments, only the standard autoconf patterns are 207 allowed: "<code class="code">--{enable,disable}-foo[={yes,no}]</code>" The 208 $enable_FEATURE variable is guaranteed to equal either "yes" or "no" 209 after the macro. If the user tries to pass something else, an 210 explanatory error message will be given, and configure will halt. 211</p><p> 212 The second signature takes a fifth argument, "<code class="code">[permit 213 a | b | c | ...]</code>" 214 This allows <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> or 215 ... after the equals sign in the option, and $enable_FEATURE is 216 guaranteed to equal one of them after the macro. Note that if you 217 want to allow plain --enable/--disable with no "=whatever", you must 218 include "yes" and "no" in the list of permitted values. Also note 219 that whatever you passed as DEFAULT must be in the list. If the 220 user tries to pass something not on the list, a semi-explanatory 221 error message will be given, and configure will halt. Example: 222 <code class="code">[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> 223</p><p> 224 The third signature takes a fifth argument. It is arbitrary shell 225 code to execute if the user actually passes the enable/disable 226 option. (If the user does not, the default is used. Duh.) No 227 argument checking at all is done in this signature. See 228 GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error 229 message. 230</p></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="spine.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="internals.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="/spine.html">Home</a></td><td width="40%" align="right" valign="top"> Porting to New Hardware or Operating Systems</td></tr></table></div></body></html> 231
