Index: gcc/libstdc++-v3/doc/html/manual/appendix_porting.html |
diff --git a/gcc/libstdc++-v3/doc/html/manual/appendix_porting.html b/gcc/libstdc++-v3/doc/html/manual/appendix_porting.html |
deleted file mode 100644 |
index fb73ccab9e0a87d0267a30c65aa3be0d9e4cca95..0000000000000000000000000000000000000000 |
--- a/gcc/libstdc++-v3/doc/html/manual/appendix_porting.html |
+++ /dev/null |
@@ -1,230 +0,0 @@ |
-<?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 Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="source_design_notes.html" title="Design Notes" /><link rel="next" href="internals.html" title="Porting to New Hardware or Operating Systems" /></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">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr /></div><div class="appendix" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting"></a>Appendix B. |
- Porting and Maintenance |
- <a id="id517404" class="indexterm"></a> |
-</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.map">Overview: What Comes from Where</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.enable">GLIBCXX_ENABLE, the --enable maker</a></span></dt></dl></dd><dt><span class="sect1"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="sect2"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="sect1"><a href="abi.html">ABI Policy and Guidelines</a></span></dt><dd><dl><dt><span class="sect2"><a href="abi.html#abi.cxx_interface">The C++ Interface</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.versioning">Versioning</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.changes_allowed">Allowed Changes</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.changes_no">Prohibited Changes</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.testing">Testing</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.issues">Outstanding Issues</a></span></dt></dl></dd><dt><span class="sect1"><a href="api.html">API Evolution and Deprecation History</a></span></dt><dd><dl><dt><span class="sect2"><a href="api.html#api.rel_300">3.0</a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_310">3.1</a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_320">3.2</a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_330">3.3</a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_340">3.4</a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_400">4.0</a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_410">4.1</a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_420">4.2</a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_430">4.3</a></span></dt></dl></dd><dt><span class="sect1"><a href="backwards.html">Backwards Compatibility</a></span></dt><dd><dl><dt><span class="sect2"><a href="backwards.html#backwards.first">First</a></span></dt><dt><span class="sect2"><a href="backwards.html#backwards.second">Second</a></span></dt><dt><span class="sect2"><a href="backwards.html#backwards.third">Third</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><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="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.prereq"></a>Prerequisites</h3></div></div></div><p> |
- As noted <a class="ulink" 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="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.map"></a>Overview: What Comes from Where</h3></div></div></div><pre class="screen"> |
- <img src="../images/confdeps.png" alt="Dependency Graph Configure to Build Files" /> |
- </pre><p> |
- Regenerate all generated files by using the command sequence |
- <code class="code">"autoreconf"</code> at the top level of the libstdc++ source |
- directory. The following will also work, but is much more complex: |
- <code class="code">"aclocal-1.7 && autoconf-2.59 && |
- autoheader-2.59 && automake-1.7"</code> The version |
- numbers may be absent entirely or otherwise vary depending on |
- <a class="ulink" href="http://gcc.gnu.org/install/prerequisites.html" target="_top">the |
- current requirements</a> and your vendor's choice of |
- installation names. |
- </p></div><div class="sect2" lang="en" xml:lang="en"><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> |
- 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="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.conventions"></a>Coding and Commenting Conventions</h3></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="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.acinclude"></a>The acinclude.m4 layout</h3></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="sect2" lang="en" xml:lang="en"><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> |
- All the GLIBCXX_ENABLE_FOO macros use a common helper, |
- GLIBCXX_ENABLE. (You don't have to use it, but it's easy.) The |
- helper does two things for us: |
- </p><div class="orderedlist"><ol type="1"><li><p> |
- Builds the call to the AC_ARG_ENABLE macro, with --help text |
- properly quoted and aligned. (Death to changequote!) |
- </p></li><li><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 GLIBCXX_ENABLE_FOO 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 type="disc"><li><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><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 GLIBCXX_ENABLE_FOO 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 |
- GLIBCXX_ENABLE_CLOCALE for an example). |
- </p></li><li><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="ulink" href="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_95.html#SEC95" target="_top"><span class="emphasis"><em>quadrigraphs</em></span></a> |
- and you should use them whenever necessary. |
- </p></li><li><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><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="spine.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="internals.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="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Porting to New Hardware or Operating Systems</td></tr></table></div></body></html> |