| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!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.77.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. |
| Porting and Maintenance |
| |
| </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. |
| Appendices |
| </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> |
| Porting and Maintenance |
| <a id="idp22008864" class="indexterm"></a> |
| </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.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"> |
| Qualifying Exception Safety Guarantees |
| |
| </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"> |
| Existing tests |
| </a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.containers"> |
| C++11 Requirements Test Sequence Descriptions |
| </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"><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 |
| </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"> |
| Removal of <code class="code">ostream::form</code> and <code class="code">istream::scan</code> |
| extensions |
| </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>. |
| </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.streamattach"> |
| No <code class="code">stream::attach(int fd)</code> |
| </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx98"> |
| Support for C++98 dialect. |
| </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_tr1"> |
| Support for C++TR1 dialect. |
| </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.support_cxx11"> |
| Support for C++11 dialect. |
| </a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third.iterator_type"> |
| <code class="code">Container::iterator_type</code> is not necessarily <code class="code">Container::value_type*</code> |
| </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> |
| As noted <a class="link" href="http://gcc.gnu.org/install/prerequisites.html" target="_top">previously</a>, |
| certain other tools are necessary for hacking on files that |
| control configure (<code class="code">configure.ac</code>, |
| <code class="code">acinclude.m4</code>) and make |
| (<code class="code">Makefile.am</code>). These additional tools |
| (<code class="code">automake</code>, and <code class="code">autoconf</code>) are further |
| described in detail in their respective manuals. All the libraries |
| in GCC try to stay in sync with each other in terms of versions of |
| the auto-tools used, so please try to play nicely with the |
| neighbors. |
| </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> |
| The configure process begins the act of building libstdc++, and is |
| started via: |
| </p><pre class="screen"> |
| <code class="computeroutput"> |
| configure |
| </code> |
| </pre><p> |
| The <code class="filename">configure</code> file is a script generated (via |
| <span class="command"><strong>autoconf</strong></span>) from the file |
| <code class="filename">configure.ac</code>. |
| </p><p> |
| After the configure process is complete, |
| </p><pre class="screen"> |
| <code class="computeroutput"> |
| make all |
| </code> |
| </pre><p> |
| 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 |
| <span class="command"><strong>automake</strong></span>) from the file |
| <code class="filename">Makefile.am</code>. |
| </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="idp22035648"></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> |
| Regenerate all generated files by using the command |
| <code class="code">autoreconf</code> at the top level of the libstdc++ source |
| directory. |
| </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> |
| Until that glorious day when we can use AC_TRY_LINK with a |
| cross-compiler, we have to hardcode the results of what the tests |
| would have shown if they could be run. So we have an inflexible |
| mess like crossconfig.m4. |
| </p><p> |
| Wouldn't it be nice if we could store that information in files |
| like configure.host, which can be modified without needing to |
| regenerate anything, and can even be tweaked without really |
| knowing how the configury all works? Perhaps break the pieces of |
| crossconfig.m4 out and place them in their appropriate |
| config/{cpu,os} directory. |
| </p><p> |
| Alas, writing macros like |
| "<code class="code">AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside |
| files which are passed through autoconf. Files which are pure |
| shell script can be source'd at configure time. Files which |
| contain autoconf macros must be processed with autoconf. We could |
| still try breaking the pieces out into "config/*/cross.m4" bits, |
| for instance, but then we would need arguments to aclocal/autoconf |
| to properly find them all when generating configure. I would |
| discourage that. |
| </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> |
| Most comments should use {octothorpes, shibboleths, hash marks, |
| pound signs, whatever} rather than "dnl". Nearly all comments in |
| configure.ac should. Comments inside macros written in ancilliary |
| .m4 files should. About the only comments which should |
| <span class="emphasis"><em>not</em></span> use #, but use dnl instead, are comments |
| <span class="emphasis"><em>outside</em></span> our own macros in the ancilliary |
| files. The difference is that # comments show up in |
| <code class="code">configure</code> (which is most helpful for debugging), |
| while dnl'd lines just vanish. Since the macros in ancilliary |
| files generate code which appears in odd places, their "outside" |
| comments tend to not be useful while reading |
| <code class="code">configure</code>. |
| </p><p> |
| Do not use any <code class="code">$target*</code> variables, such as |
| <code class="code">$target_alias</code>. The single exception is in |
| configure.ac, for automake+dejagnu's sake. |
| </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> |
| The nice thing about acinclude.m4/aclocal.m4 is that macros aren't |
| actually performed/called/expanded/whatever here, just loaded. So |
| we can arrange the contents however we like. As of this writing, |
| acinclude.m4 is arranged as follows: |
| </p><pre class="programlisting"> |
| GLIBCXX_CHECK_HOST |
| GLIBCXX_TOPREL_CONFIGURE |
| GLIBCXX_CONFIGURE |
| </pre><p> |
| All the major variable "discovery" is done here. CXX, multilibs, |
| etc. |
| </p><pre class="programlisting"> |
| fragments included from elsewhere |
| </pre><p> |
| Right now, "fragments" == "the math/linkage bits". |
| </p><pre class="programlisting"> |
| GLIBCXX_CHECK_COMPILER_FEATURES |
| GLIBCXX_CHECK_LINKER_FEATURES |
| GLIBCXX_CHECK_WCHAR_T_SUPPORT |
| </pre><p> |
| Next come extra compiler/linker feature tests. Wide character |
| support was placed here because I couldn't think of another place |
| for it. It will probably get broken apart like the math tests, |
| because we're still disabling wchars on systems which could actually |
| support them. |
| </p><pre class="programlisting"> |
| GLIBCXX_CHECK_SETRLIMIT_ancilliary |
| GLIBCXX_CHECK_SETRLIMIT |
| GLIBCXX_CHECK_S_ISREG_OR_S_IFREG |
| GLIBCXX_CHECK_POLL |
| GLIBCXX_CHECK_WRITEV |
| |
| GLIBCXX_CONFIGURE_TESTSUITE |
| </pre><p> |
| Feature tests which only get used in one place. Here, things used |
| only in the testsuite, plus a couple bits used in the guts of I/O. |
| </p><pre class="programlisting"> |
| GLIBCXX_EXPORT_INCLUDES |
| GLIBCXX_EXPORT_FLAGS |
| GLIBCXX_EXPORT_INSTALL_INFO |
| </pre><p> |
| Installation variables, multilibs, working with the rest of the |
| compiler. Many of the critical variables used in the makefiles are |
| set here. |
| </p><pre class="programlisting"> |
| GLIBGCC_ENABLE |
| GLIBCXX_ENABLE_C99 |
| GLIBCXX_ENABLE_CHEADERS |
| GLIBCXX_ENABLE_CLOCALE |
| GLIBCXX_ENABLE_CONCEPT_CHECKS |
| GLIBCXX_ENABLE_CSTDIO |
| GLIBCXX_ENABLE_CXX_FLAGS |
| GLIBCXX_ENABLE_C_MBCHAR |
| GLIBCXX_ENABLE_DEBUG |
| GLIBCXX_ENABLE_DEBUG_FLAGS |
| GLIBCXX_ENABLE_LONG_LONG |
| GLIBCXX_ENABLE_PCH |
| GLIBCXX_ENABLE_SJLJ_EXCEPTIONS |
| GLIBCXX_ENABLE_SYMVERS |
| GLIBCXX_ENABLE_THREADS |
| </pre><p> |
| All the features which can be controlled with enable/disable |
| configure options. Note how they're alphabetized now? Keep them |
| like that. :-) |
| </p><pre class="programlisting"> |
| AC_LC_MESSAGES |
| libtool bits |
| </pre><p> |
| Things which we don't seem to use directly, but just has to be |
| present otherwise stuff magically goes wonky. |
| </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> |
| All the <code class="literal">GLIBCXX_ENABLE_FOO</code> macros use a common |
| helper, <code class="literal">GLIBCXX_ENABLE</code>. (You don't have to use |
| it, but it's easy.) The helper does two things for us: |
| </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> |
| Builds the call to the <code class="literal">AC_ARG_ENABLE</code> macro, with --help text |
| properly quoted and aligned. (Death to changequote!) |
| </p></li><li class="listitem"><p> |
| Checks the result against a list of allowed possibilities, and |
| signals a fatal error if there's no match. This means that the |
| rest of the <code class="literal">GLIBCXX_ENABLE_FOO</code> macro doesn't need to test for |
| strange arguments, nor do we need to protect against |
| empty/whitespace strings with the <code class="code">"x$foo" = "xbar"</code> |
| idiom. |
| </p></li></ol></div><p>Doing these things correctly takes some extra autoconf/autom4te code, |
| which made our macros nearly illegible. So all the ugliness is factored |
| out into this one helper macro. |
| </p><p>Many of the macros take an argument, passed from when they are expanded |
| in configure.ac. The argument controls the default value of the |
| enable/disable switch. Previously, the arguments themselves had defaults. |
| Now they don't, because that's extra complexity with zero gain for us. |
| </p><p>There are three "overloaded signatures". When reading the descriptions |
| below, keep in mind that the brackets are autoconf's quotation characters, |
| and that they will be stripped. Examples of just about everything occur |
| in acinclude.m4, if you want to look. |
| </p><pre class="programlisting"> |
| GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) |
| GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) |
| GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) |
| </pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> |
| FEATURE is the string that follows --enable. The results of the |
| test (such as it is) will be in the variable $enable_FEATURE, |
| where FEATURE has been squashed. Example: |
| <code class="code">[extra-foo]</code>, controlled by the --enable-extra-foo |
| option and stored in $enable_extra_foo. |
| </p></li><li class="listitem"><p> |
| DEFAULT is the value to store in $enable_FEATURE if the user does |
| not pass --enable/--disable. It should be one of the permitted |
| values passed later. Examples: <code class="code">[yes]</code>, or |
| <code class="code">[bar]</code>, or <code class="code">[$1]</code> (which passes the |
| argument given to the <code class="literal">GLIBCXX_ENABLE_FOO</code> macro |
| as the default). |
| </p><p> |
| For cases where we need to probe for particular models of things, |
| it is useful to have an undocumented "auto" value here (see |
| <code class="literal">GLIBCXX_ENABLE_CLOCALE</code> for an example). |
| </p></li><li class="listitem"><p> |
| HELP-ARG is any text to append to the option string itself in the |
| --help output. Examples: <code class="code">[]</code> (i.e., an empty string, |
| which appends nothing), <code class="code">[=BAR]</code>, which produces |
| <code class="code">--enable-extra-foo=BAR</code>, and |
| <code class="code">[@<:@=BAR@:>@]</code>, which produces |
| <code class="code">--enable-extra-foo[=BAR]</code>. See the difference? See |
| what it implies to the user? |
| </p><p> |
| If you're wondering what that line noise in the last example was, |
| that's how you embed autoconf special characters in output text. |
| 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> |
| and you should use them whenever necessary. |
| </p></li><li class="listitem"><p>HELP-STRING is what you think it is. Do not include the |
| "default" text like we used to do; it will be done for you by |
| GLIBCXX_ENABLE. By convention, these are not full English |
| sentences. Example: [turn on extra foo] |
| </p></li></ul></div><p> |
| With no other arguments, only the standard autoconf patterns are |
| allowed: "<code class="code">--{enable,disable}-foo[={yes,no}]</code>" The |
| $enable_FEATURE variable is guaranteed to equal either "yes" or "no" |
| after the macro. If the user tries to pass something else, an |
| explanatory error message will be given, and configure will halt. |
| </p><p> |
| The second signature takes a fifth argument, "<code class="code">[permit |
| a | b | c | ...]</code>" |
| This allows <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> or |
| ... after the equals sign in the option, and $enable_FEATURE is |
| guaranteed to equal one of them after the macro. Note that if you |
| want to allow plain --enable/--disable with no "=whatever", you must |
| include "yes" and "no" in the list of permitted values. Also note |
| that whatever you passed as DEFAULT must be in the list. If the |
| user tries to pass something not on the list, a semi-explanatory |
| error message will be given, and configure will halt. Example: |
| <code class="code">[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> |
| </p><p> |
| The third signature takes a fifth argument. It is arbitrary shell |
| code to execute if the user actually passes the enable/disable |
| option. (If the user does not, the default is used. Duh.) No |
| argument checking at all is done in this signature. See |
| GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error |
| message. |
| </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> |
| The build process has to make all of object files needed for |
| static or shared libraries, but first it has to generate some |
| include files. The general order is as follows: |
| </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> |
| make include files, make pre-compiled headers |
| </p></li><li class="listitem"><p> |
| make libsupc++ |
| </p><p> |
| Generates a libtool convenience library, |
| <code class="filename">libsupc++convenience</code> with language-support |
| routines. Also generates a freestanding static library, |
| <code class="filename">libsupc++.a</code>. |
| </p></li><li class="listitem"><p> |
| make src |
| </p><p> |
| Generates two convenience libraries, one for C++98 and one for |
| C++11, various compability files for shared and static |
| libraries, and then collects all the generated bits and creates |
| the final libstdc++ libraries. |
| </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p> |
| make src/c++98 |
| </p><p> |
| Generates a libtool convenience library, |
| <code class="filename">libc++98convenience</code> with language-support |
| routines. Uses the <code class="literal">-std=gnu++98</code> dialect. |
| </p></li><li class="listitem"><p> |
| make src/c++11 |
| </p><p> |
| Generates a libtool convenience library, |
| <code class="filename">libc++11convenience</code> with language-support |
| routines. Uses the <code class="literal">-std=gnu++11</code> dialect. |
| </p></li><li class="listitem"><p> |
| make src |
| </p><p> |
| Generates needed compatibility objects for shared and static |
| libraries. Shared-only code is seggregated at compile-time via |
| the macro <code class="literal">_GLIBCXX_SHARED</code>. |
| </p><p> |
| Then, collects all the generated convenience libraries, adds in |
| any required compatibility objects, and creates the final shared |
| and static libraries: <code class="filename">libstdc++.so</code> and |
| <code class="filename">libstdc++.a</code>. |
| </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> |