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