summaryrefslogtreecommitdiff
path: root/libstdc++-v3/doc/html/manual/appendix_porting.html
blob: 8cb4398ffadd2f48823023f520c30c8789bc9a72 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Appendix B.  Porting and Maintenance</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="bk01pt04.html" title="Part IV.  Appendices"/><link rel="prev" href="source_design_notes.html" title="Design Notes"/><link rel="next" href="documentation_hacking.html" title="Writing and Generating Documentation"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix B. 
  Porting and Maintenance
  
</th></tr><tr><td align="left"><a accesskey="p" href="source_design_notes.html">Prev</a> </td><th width="60%" align="center">Part IV. 
  Appendices
</th><td align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr></table><hr/></div><div class="appendix" title="Appendix B.  Porting and Maintenance"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.porting"/>
  Porting and Maintenance
  <a id="id494054" class="indexterm"/>
</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.map">Overview: What Comes from Where</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt></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><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><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><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt></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><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><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><dt><span class="section"><a href="backwards.html#backwards.second">Second</a></span></dt><dt><span class="section"><a href="backwards.html#backwards.third">Third</a></span></dt></dl></dd></dl></div><div class="section" title="Configure and Build Hacking"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting.build_hacking"/>Configure and Build Hacking</h2></div></div></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.prereq"/>Prerequisites</h3></div></div></div><p>
    As noted <a class="link" href="http://gcc.gnu.org/install/prerequisites.html">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" title="Overview: What Comes from Where"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.map"/>Overview: What Comes from Where</h3></div></div></div><div class="figure"><a id="id494186"/><p class="title"><strong>Figure B.1. Configure and Build File Dependencies</strong></p><div class="figure-contents"><div class="mediaobject" style="text-align: center"><img src="/mnt/share/src/gcc.svn-trunk/libstdc++-v3/doc/xml/images/confdeps.png" style="text-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 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.11 &amp;&amp; autoconf-2.64 &amp;&amp;
    autoheader-2.64 &amp;&amp; automake-1.11"</code> The version
    numbers may be absent entirely or otherwise vary depending on
    <a class="link" href="http://gcc.gnu.org/install/prerequisites.html">the
    current requirements</a> and your vendor's choice of
    installation names.
  </p></div><div class="section" title="Storing Information in non-AC files (like configure.host)"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.scripts"/>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="section" title="Coding and Commenting Conventions"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.conventions"/>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="section" title="The acinclude.m4 layout"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.acinclude"/>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="section" title="GLIBCXX_ENABLE, the --enable maker"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.enable"/><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 class="orderedlist"><li class="listitem"><p>
     Builds the call to the AC_ARG_ENABLE 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 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 class="itemizedlist"><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 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 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">[@&lt;:@=BAR@:&gt;@]</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"><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><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="source_design_notes.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt04.html">Up</a></td><td align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr><tr><td align="left" valign="top">Design Notes </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Writing and Generating Documentation</td></tr></table></div></body></html>