OSDN Git Service

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