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"><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">
  16 C++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">&lt;ostream.h&gt;</code>, no <code class="code">cin</code> in <code class="filename">&lt;istream.h&gt;</code></a></span></dt></dl></dd><dt><span class="section"><a href="backwards.html#backwards.second">Second</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.second.std">Namespace <code class="code">std::</code> not supported</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.iterators">Illegal iterator usage</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.isspace"><code class="code">isspace</code> from <code class="filename">&lt;cctype&gt;</code> is a macro
  18   </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.at">No <code class="code">vector::at</code>, <code class="code">deque::at</code>, <code class="code">string::at</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.eof">No <code class="code">std::char_traits&lt;char&gt;::eof</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.stringclear">No <code class="code">string::clear</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.ostreamform_istreamscan">
  19   Removal of <code class="code">ostream::form</code> and <code class="code">istream::scan</code>
  20   extensions
  21 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.stringstreams">No <code class="code">basic_stringbuf</code>, <code class="code">basic_stringstream</code></a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.wchar">Little or no wide character support</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.iostream_templates">No templatized iostreams</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.second.thread_safety">Thread safety issues</a></span></dt></dl></dd><dt><span class="section"><a href="backwards.html#backwards.third">Third</a></span></dt><dd><dl><dt><span class="section"><a href="backwards.html#backwards.third.headers">Pre-ISO headers 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">
  23 No <code class="code">stream::attach(int fd)</code>
  24 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx98">
  25 Support for C++98 dialect.
  26 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_tr1">
  27 Support for C++TR1 dialect.
  28 </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx11">
  29 Support 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">
  48 configure
  49 </code>
  50 </pre><p>
  51 The <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">
  58 make all
  59 </code>
  60 </pre><p>
  61 in 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">[@&lt;:@=BAR@:&gt;@]</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>