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