1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix B. Porting and Maintenance</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix.html" title="Part IV. Appendices" /><link rel="prev" href="source_design_notes.html" title="Design Notes" /><link rel="next" href="documentation_hacking.html" title="Writing and Generating Documentation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix B. 3 Porting and Maintenance 4 5</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="source_design_notes.html">Prev</a> </td><th width="60%" align="center">Part IV. 6 Appendices 7</th><td width="20%" align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr></table><hr /></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.porting"></a> 8 Porting and Maintenance 9 <a id="id-1.3.6.3.1.1.1" class="indexterm"></a> 10</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></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">Test</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">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><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_50"><code class="constant">5</code></a></span></dt></dl></dd><dt><span class="section"><a href="backwards.html">Backwards Compatibility</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.first">First</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.first.ios_base">No <code class="code">ios_base</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.first.cout_cin">No <code class="code">cout</code> in <code class="filename"><ostream.h></code>, no <code class="code">cin</code> in <code class="filename"><istream.h></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"><cctype></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<char>::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 moved to backwards or 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 <code class="code">autoreconf</code> 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 AC_TRY_LINK with a 70 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 crossconfig.m4. 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 crossconfig.m4 out and place them in their appropriate 79 config/{cpu,os} 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 "dnl". Nearly all comments in 93 configure.ac should. Comments inside macros written in ancillary 94 .m4 files should. About the only comments which should 95 <span class="emphasis"><em>not</em></span> use #, but use dnl instead, are comments 96 <span class="emphasis"><em>outside</em></span> our own macros in the ancillary 97 files. The difference is that # comments show up in 98 <code class="code">configure</code> (which is most helpful for debugging), 99 while dnl'd lines just vanish. Since the macros in ancillary 100 files generate code which appears in odd places, their "outside" 101 comments tend to not be useful while reading 102 <code class="code">configure</code>. 103 </p><p> 104 Do not use any <code class="code">$target*</code> variables, such as 105 <code class="code">$target_alias</code>. The single exception is in 106 configure.ac, for automake+dejagnu's sake. 107 </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> 108 The nice thing about acinclude.m4/aclocal.m4 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 acinclude.m4 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. CXX, multilibs, 118 etc. 119 </p><pre class="programlisting"> 120 fragments included from elsewhere 121 </pre><p> 122 Right now, "fragments" == "the math/linkage bits". 123 </p><pre class="programlisting"> 124 GLIBCXX_CHECK_COMPILER_FEATURES 125 GLIBCXX_CHECK_LINKER_FEATURES 126 GLIBCXX_CHECK_WCHAR_T_SUPPORT 127</pre><p> 128 Next come extra compiler/linker feature tests. Wide character 129 support was placed here because I couldn't think of another place 130 for it. It will probably get broken apart like the math tests, 131 because we're still disabling wchars on systems which could actually 132 support them. 133</p><pre class="programlisting"> 134 GLIBCXX_CHECK_SETRLIMIT_ancilliary 135 GLIBCXX_CHECK_SETRLIMIT 136 GLIBCXX_CHECK_S_ISREG_OR_S_IFREG 137 GLIBCXX_CHECK_POLL 138 GLIBCXX_CHECK_WRITEV 139 140 GLIBCXX_CONFIGURE_TESTSUITE 141</pre><p> 142 Feature tests which only get used in one place. Here, things used 143 only in the testsuite, plus a couple bits used in the guts of I/O. 144</p><pre class="programlisting"> 145 GLIBCXX_EXPORT_INCLUDES 146 GLIBCXX_EXPORT_FLAGS 147 GLIBCXX_EXPORT_INSTALL_INFO 148</pre><p> 149 Installation variables, multilibs, working with the rest of the 150 compiler. Many of the critical variables used in the makefiles are 151 set here. 152</p><pre class="programlisting"> 153 GLIBGCC_ENABLE 154 GLIBCXX_ENABLE_C99 155 GLIBCXX_ENABLE_CHEADERS 156 GLIBCXX_ENABLE_CLOCALE 157 GLIBCXX_ENABLE_CONCEPT_CHECKS 158 GLIBCXX_ENABLE_CSTDIO 159 GLIBCXX_ENABLE_CXX_FLAGS 160 GLIBCXX_ENABLE_C_MBCHAR 161 GLIBCXX_ENABLE_DEBUG 162 GLIBCXX_ENABLE_DEBUG_FLAGS 163 GLIBCXX_ENABLE_LONG_LONG 164 GLIBCXX_ENABLE_PCH 165 GLIBCXX_ENABLE_SJLJ_EXCEPTIONS 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 --help text 184 properly quoted and aligned. (Death to changequote!) 185 </p></li><li class="listitem"><p> 186 Checks the result against a list of allowed possibilities, and 187 signals a fatal error if there's no match. This means that the 188 rest of the <code class="literal">GLIBCXX_ENABLE_FOO</code> macro doesn't need to test for 189 strange arguments, nor do we need to protect against 190 empty/whitespace strings with the <code class="code">"x$foo" = "xbar"</code> 191 idiom. 192 </p></li></ol></div><p>Doing these things correctly takes some extra autoconf/autom4te code, 193 which made our macros nearly illegible. So all the ugliness is factored 194 out into this one helper macro. 195</p><p>Many of the macros take an argument, passed from when they are expanded 196 in configure.ac. The argument controls the default value of the 197 enable/disable switch. Previously, the arguments themselves had defaults. 198 Now they don't, because that's extra complexity with zero gain for us. 199</p><p>There are three "overloaded signatures". When reading the descriptions 200 below, keep in mind that the brackets are autoconf's quotation characters, 201 and that they will be stripped. Examples of just about everything occur 202 in acinclude.m4, if you want to look. 203</p><pre class="programlisting"> 204 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) 205 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) 206 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) 207</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 208 FEATURE is the string that follows --enable. The results of the 209 test (such as it is) will be in the variable $enable_FEATURE, 210 where FEATURE has been squashed. Example: 211 <code class="code">[extra-foo]</code>, controlled by the --enable-extra-foo 212 option and stored in $enable_extra_foo. 213 </p></li><li class="listitem"><p> 214 DEFAULT is the value to store in $enable_FEATURE if the user does 215 not pass --enable/--disable. It should be one of the permitted 216 values passed later. Examples: <code class="code">[yes]</code>, or 217 <code class="code">[bar]</code>, or <code class="code">[$1]</code> (which passes the 218 argument given to the <code class="literal">GLIBCXX_ENABLE_FOO</code> macro 219 as the default). 220 </p><p> 221 For cases where we need to probe for particular models of things, 222 it is useful to have an undocumented "auto" value here (see 223 <code class="literal">GLIBCXX_ENABLE_CLOCALE</code> for an example). 224 </p></li><li class="listitem"><p> 225 HELP-ARG is any text to append to the option string itself in the 226 --help output. Examples: <code class="code">[]</code> (i.e., an empty string, 227 which appends nothing), <code class="code">[=BAR]</code>, which produces 228 <code class="code">--enable-extra-foo=BAR</code>, and 229 <code class="code">[@<:@=BAR@:>@]</code>, which produces 230 <code class="code">--enable-extra-foo[=BAR]</code>. See the difference? See 231 what it implies to the user? 232 </p><p> 233 If you're wondering what that line noise in the last example was, 234 that's how you embed autoconf special characters in output text. 235 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> 236 and you should use them whenever necessary. 237 </p></li><li class="listitem"><p>HELP-STRING is what you think it is. Do not include the 238 "default" text like we used to do; it will be done for you by 239 GLIBCXX_ENABLE. By convention, these are not full English 240 sentences. Example: [turn on extra foo] 241 </p></li></ul></div><p> 242 With no other arguments, only the standard autoconf patterns are 243 allowed: "<code class="code">--{enable,disable}-foo[={yes,no}]</code>" The 244 $enable_FEATURE variable is guaranteed to equal either "yes" or "no" 245 after the macro. If the user tries to pass something else, an 246 explanatory error message will be given, and configure will halt. 247</p><p> 248 The second signature takes a fifth argument, "<code class="code">[permit 249 a | b | c | ...]</code>" 250 This allows <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> or 251 ... after the equals sign in the option, and $enable_FEATURE is 252 guaranteed to equal one of them after the macro. Note that if you 253 want to allow plain --enable/--disable with no "=whatever", you must 254 include "yes" and "no" in the list of permitted values. Also note 255 that whatever you passed as DEFAULT must be in the list. If the 256 user tries to pass something not on the list, a semi-explanatory 257 error message will be given, and configure will halt. Example: 258 <code class="code">[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> 259</p><p> 260 The third signature takes a fifth argument. It is arbitrary shell 261 code to execute if the user actually passes the enable/disable 262 option. (If the user does not, the default is used. Duh.) No 263 argument checking at all is done in this signature. See 264 GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error 265 message. 266</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> 267 The build process has to make all of object files needed for 268 static or shared libraries, but first it has to generate some 269 include files. The general order is as follows: 270 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> 271 make include files, make pre-compiled headers 272 </p></li><li class="listitem"><p> 273 make libsupc++ 274 </p><p> 275 Generates a libtool convenience library, 276 <code class="filename">libsupc++convenience</code> with language-support 277 routines. Also generates a freestanding static library, 278 <code class="filename">libsupc++.a</code>. 279 </p></li><li class="listitem"><p> 280 make src 281 </p><p> 282 Generates two convenience libraries, one for C++98 and one for 283 C++11, various compatibility files for shared and static 284 libraries, and then collects all the generated bits and creates 285 the final libstdc++ libraries. 286 </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p> 287 make src/c++98 288 </p><p> 289 Generates a libtool convenience library, 290 <code class="filename">libc++98convenience</code> with language-support 291 routines. Uses the <code class="literal">-std=gnu++98</code> dialect. 292 </p></li><li class="listitem"><p> 293 make src/c++11 294 </p><p> 295 Generates a libtool convenience library, 296 <code class="filename">libc++11convenience</code> with language-support 297 routines. Uses the <code class="literal">-std=gnu++11</code> dialect. 298 </p></li><li class="listitem"><p> 299 make src 300 </p><p> 301 Generates needed compatibility objects for shared and static 302 libraries. Shared-only code is seggregated at compile-time via 303 the macro <code class="literal">_GLIBCXX_SHARED</code>. 304 </p><p> 305 Then, collects all the generated convenience libraries, adds in 306 any required compatibility objects, and creates the final shared 307 and static libraries: <code class="filename">libstdc++.so</code> and 308 <code class="filename">libstdc++.a</code>. 309 </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>
