libstdc++-v3/doc/html/17_intro/configury.html

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   9    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
  10    <meta name="DESCRIPTION" content="configury for libstdc++" />
  11    <meta name="GENERATOR" content="vi and eight fingers" />
  12    <title>libstdc++ configury</title>
  13 <link rel="StyleSheet" href="../lib3styles.css" type='text/css' />
  14 <link rel="Start" href="../documentation.html" type="text/html"
  15  title="GNU C++ Standard Library" />
  16 </head>
  17 <body>
  18
  19 <h1><code>&gt; open configury door</code></h1>
  20 <h1><code>&gt; look</code></h1>
  21
  22 <p class="larger"><code>You are in a maze of twisty passages, all
  23 different.</code></p>
  24 <p class="larger"><code>It is dark.  You are likely to be eaten by a
  25 Canadian cross build.</code></p>
  26
  27
  28 <hr />
  29 <h2>Notes on libstdc++ configury</h2>
  30 <blockquote>
  31 No problem is insoluble in all conceivable circumstances.<br />
  32 -- The Cosmic AC,
  33 <a href="http://mit.edu/tylerc/www/twt/LQ1.htm">The
  34 Last Question</a>, by Isaac Asimov
  35 </blockquote>
  36 <ul>
  37  <li><a href="#prereq">Prerequisites for configure and make hacking</a></li>
  38  <li><a href="#deps">Overview: what comes from where</a></li>
  39  <li><a href="#breakout">Storing information in non-AC files, like
  40                          configure.host</a></li>
  41  <li><a href="#general">Coding and commenting conventions</a></li>
  42  <li><a href="#aclayout">The acinclude.m4 layout</a></li>
  43  <li><a href="#enable"><code>GLIBCXX_ENABLE, the --enable</code> howto</a></li>
  44 </ul>
  45
  46 <hr />
  47 <h3><a name="prereq">Prerequisites for configure and make hacking</a></h3>
  48
  49 <p> As
  50 noted <a href="http://gcc.gnu.org/install/prerequisites.html">previously</a>,
  51 certain other tools are necessary for hacking on files that control
  52 configure (<code>configure.ac</code>, <code>acinclude.m4</code>) and
  53 make (<code>Makefile.am</code>). These additional tools
  54 (<code>automake</code>, and <code>autoconf</code>) are further
  55 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.
  56 </p>
  57
  58
  59 <hr />
  60 <h3><a name="deps">Overview: what comes from where</a></h3>
  61 <p class="centered"><img src="confdeps.png"
  62   alt="Dependency graph in PNG graphics format.  (Get a better browser!)" /></p>
  63
  64 <p>Regenerate all generated files by using the command sequence
  65  <code>"autoreconf"</code> at the top level of the libstdc++ source
  66  directory. The following will also work, but is much more complex:
  67    <code>"aclocal-1.7 &amp;&amp; autoconf-2.59 &amp;&amp;
  68    autoheader-2.59 &amp;&amp; automake-1.7"</code> The version numbers
  69    may be absent entirely or otherwise vary depending on
  70    <a href="http://gcc.gnu.org/install/prerequisites.html">the current
  71    requirements</a> and your vendor's choice of installation names.
  72 </p>
  73
  74
  75 <hr />
  76 <h3><a name="breakout">Storing information in non-AC files, like
  77                        configure.host</a></h3>
  78 <p>Until that glorious day when we can use AC_TRY_LINK with a cross-compiler,
  79    we have to hardcode the results of what the tests would have shown if
  80    they could be run.  So we have an inflexible mess like crossconfig.m4.
  81 </p>
  82
  83 <p>Wouldn't it be nice if we could store that information in files like
  84    configure.host, which can be modified without needing to regenerate
  85    anything, and can even be tweaked without really knowing how the configury
  86    all works?  Perhaps break the pieces of crossconfig.m4 out and place them in
  87    their appropriate config/{cpu,os} directory.
  88 </p>
  89
  90 <p>Alas, writing macros like "<code>AC_DEFINE(HAVE_A_NICE_DAY)</code>" can
  91    only be done inside files which are passed through autoconf.  Files which
  92    are pure shell script can be source'd at configure time.  Files which
  93    contain autoconf macros must be processed with autoconf.  We could still
  94    try breaking the pieces out into "config/*/cross.m4" bits, for instance,
  95    but then we would need arguments to aclocal/autoconf to properly find
  96    them all when generating configure.  I would discourage that.
  97 </p>
  98
  99
 100 <hr />
 101 <h3><a name="general">Coding and commenting conventions</a></h3>
 102 <p>Lots of stuff got thrown out because the new autotools kindly generate
 103    the same (or better) shell code for us.
 104 </p>
 105
 106 <p>Most comments should use {octothorpes, shibboleths, hash marks, pound
 107    signs, whatevers} rather than "dnl".  Nearly all comments in configure.ac
 108    should.  Comments inside macros written in ancilliary .m4 files should.
 109    About the only comments which should <em>not</em> use #, but use dnl
 110    instead, are comments <em>outside</em> our own macros in the ancilliary
 111    files.  The difference is that # comments show up in <code>configure</code>
 112    (which is most helpful for debugging), while dnl'd lines just vanish.
 113    Since the macros in ancilliary files generate code which appears in odd
 114    places, their "outside" comments tend to not be useful while reading
 115    <code>configure</code>.
 116 </p>
 117
 118 <p>Do not use any <code>$target*</code> variables, such as
 119    <code>$target_alias</code>.  The single exception is in configure.ac,
 120    for automake+dejagnu's sake.
 121 </p>
 122
 123 <p>
 124 </p>
 125
 126 <hr />
 127 <h3><a name="aclayout">The acinclude.m4 layout</a></h3>
 128 <p>The nice thing about acinclude.m4/aclocal.m4 is that macros aren't actually
 129    performed/called/expanded/whatever here, just loaded.  So we can arrange
 130    the contents however we like.  As of this writing, acinclude.m4 is arranged
 131    as follows:
 132 </p>
 133 <pre>
 134     GLIBCXX_CHECK_HOST
 135     GLIBCXX_TOPREL_CONFIGURE
 136     GLIBCXX_CONFIGURE
 137 </pre>
 138 <p>All the major variable "discovery" is done here.  CXX, multilibs, etc.
 139 </p>
 140 <pre>
 141     fragments included from elsewhere
 142 </pre>
 143 <p>Right now, "fragments" == "the math/linkage bits".
 144 </p>
 145 <pre>
 146     GLIBCXX_CHECK_COMPILER_FEATURES
 147     GLIBCXX_CHECK_LINKER_FEATURES
 148     GLIBCXX_CHECK_WCHAR_T_SUPPORT
 149 </pre>
 150 <p>Next come extra compiler/linker feature tests.  Wide character support
 151    was placed here because I couldn't think of another place for it.  It will
 152    probably get broken apart like the math tests, because we're still disabling
 153    wchars on systems which could actually support them.
 154 </p>
 155 <pre>
 156     GLIBCXX_CHECK_SETRLIMIT_ancilliary
 157     GLIBCXX_CHECK_SETRLIMIT
 158     GLIBCXX_CHECK_S_ISREG_OR_S_IFREG
 159     GLIBCXX_CHECK_POLL
 160     GLIBCXX_CHECK_WRITEV
 161
 162     GLIBCXX_CONFIGURE_TESTSUITE
 163 </pre>
 164 <p>Feature tests which only get used in one place.  Here, things used only in
 165    the testsuite, plus a couple bits used in the guts of I/O.
 166 </p>
 167 <pre>
 168     GLIBCXX_EXPORT_INCLUDES
 169     GLIBCXX_EXPORT_FLAGS
 170     GLIBCXX_EXPORT_INSTALL_INFO
 171 </pre>
 172 <p>Installation variables, multilibs, working with the rest of the compiler.
 173    Many of the critical variables used in the makefiles are set here.
 174 </p>
 175 <pre>
 176     GLIBGCC_ENABLE
 177     GLIBCXX_ENABLE_C99
 178     GLIBCXX_ENABLE_CHEADERS
 179     GLIBCXX_ENABLE_CLOCALE
 180     GLIBCXX_ENABLE_CONCEPT_CHECKS
 181     GLIBCXX_ENABLE_CSTDIO
 182     GLIBCXX_ENABLE_CXX_FLAGS
 183     GLIBCXX_ENABLE_C_MBCHAR
 184     GLIBCXX_ENABLE_DEBUG
 185     GLIBCXX_ENABLE_DEBUG_FLAGS
 186     GLIBCXX_ENABLE_LONG_LONG
 187     GLIBCXX_ENABLE_PCH
 188     GLIBCXX_ENABLE_SJLJ_EXCEPTIONS
 189     GLIBCXX_ENABLE_SYMVERS
 190     GLIBCXX_ENABLE_THREADS
 191 </pre>
 192 <p>All the features which can be controlled with enable/disable configure
 193    options.  Note how they're alphabetized now?  Keep them like that.  :-)
 194 </p>
 195 <pre>
 196     AC_LC_MESSAGES
 197     libtool bits
 198 </pre>
 199 <p>Things which we don't seem to use directly, but just has to be present
 200    otherwise stuff magically goes wonky.
 201 </p>
 202
 203
 204 <hr />
 205 <h3><a name="enable">GLIBCXX_ENABLE, the <code>--enable</code> howto</a></h3>
 206 <p>All the GLIBCXX_ENABLE_FOO macros use a common helper, GLIBCXX_ENABLE.
 207    (You don't have to use it, but it's easy.)  The helper does two things
 208    for us:
 209 </p>
 210
 211 <ol>
 212  <li>Builds the call to the AC_ARG_ENABLE macro, with --help text properly
 213      quoted and aligned.  (Death to changequote!)</li>
 214  <li>Checks the result against a list of allowed possibilities, and signals
 215      a fatal error if there's no match.  This means that the rest of the
 216      GLIBCXX_ENABLE_FOO macro doesn't need to test for strange arguments,
 217      nor do we need to protect against empty/whitespace strings with the
 218      <code>"x$foo" = "xbar"</code> idiom.</li>
 219 </ol>
 220
 221 <p>Doing these things correctly takes some extra autoconf/autom4te code,
 222    which made our macros nearly illegible.  So all the ugliness is factored
 223    out into this one helper macro.
 224 </p>
 225
 226 <p>Many of the macros take an argument, passed from when they are expanded
 227    in configure.ac.  The argument controls the default value of the
 228    enable/disable switch.  Previously, the arguments themselves had defaults.
 229    Now they don't, because that's extra complexity with zero gain for us.
 230 </p>
 231
 232 <p>There are three "overloaded signatures".  When reading the descriptions
 233    below, keep in mind that the brackets are autoconf's quotation characters,
 234    and that they will be stripped.  Examples of just about everything occur
 235    in acinclude.m4, if you want to look.
 236 </p>
 237
 238 <pre>
 239     GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING)
 240     GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c)
 241     GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER)
 242 </pre>
 243
 244 <ul>
 245  <li><p>FEATURE is the string that follows --enable.  The results of the test
 246      (such as it is) will be in the variable $enable_FEATURE, where FEATURE
 247      has been squashed.  Example:  <code>[extra-foo]</code>, controlled by the
 248      --enable-extra-foo option and stored in $enable_extra_foo.</p></li>
 249  <li><p>DEFAULT is the value to store in $enable_FEATURE if the user does not
 250      pass --enable/--disable.  It should be one of the permitted values
 251      passed later.  Examples:  <code>[yes]</code>, or <code>[bar]</code>, or
 252      <code>[$1]</code> (which passes the argument given to the
 253      GLIBCXX_ENABLE_FOO macro as the default).</p>
 254      <p>For cases where we need to probe for particular models
 255      of things, it is useful to have an undocumented "auto" value here (see
 256      GLIBCXX_ENABLE_CLOCALE for an example).</p></li>
 257  <li><p>HELP-ARG is any text to append to the option string itself in the
 258      --help output.  Examples: <code>[]</code> (i.e., an empty string,
 259      which appends nothing),
 260      <code>[=BAR]</code>, which produces
 261      <code>--enable-extra-foo=BAR</code>, and
 262      <code>[@&lt;:@=BAR@:&gt;@]</code>, which produces
 263      <code>--enable-extra-foo[=BAR]</code>.  See the difference?  See what
 264      it implies to the user?</p>
 265      <p>If you're wondering what that line noise in the last example was,
 266      that's how you embed autoconf special characters in output text.
 267      They're called
 268 <a
 269 href="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_95.html#SEC95"><em>quadrigraphs</em></a>
 270      and you should use them whenever necessary.</p></li>
 271  <li><p>HELP-STRING is what you think it is.  Do not include the "default"
 272      text like we used to do; it will be done for you by GLIBCXX_ENABLE.
 273      By convention, these are not full English sentences.
 274      Example:  [turn on extra foo]</p></li>
 275 </ul>
 276
 277 <p>With no other arguments, only the standard autoconf patterns are
 278    allowed:  "<code>--{enable,disable}-foo[={yes,no}]</code>"  The
 279    $enable_FEATURE variable is guaranteed to equal either "yes" or "no"
 280    after the macro.  If the user tries to pass something else, an
 281    explanatory error message will be given, and configure will halt.
 282 </p>
 283
 284 <p>The second signature takes a fifth argument,
 285    "<code>[permit <em>a</em>|<em>b</em>|<em>c</em>|<em>...</em>]</code>"
 286    This allows <em>a</em> or <em>b</em> or ... after the equals sign in the
 287    option, and $enable_FEATURE is guaranteed to equal one of them after the
 288    macro.  Note that if you want to allow plain --enable/--disable with no
 289    "=whatever", you must include "yes" and "no" in the list of permitted
 290    values.  Also note that whatever you passed as DEFAULT must be in the list.
 291    If the user tries to pass something not on the list, a semi-explanatory
 292    error message will be given, and configure will halt.
 293    Example:  <code>[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code>
 294 </p>
 295
 296 <p>The third signature takes a fifth argument.  It is arbitrary shell code
 297    to execute if the user actually passes the enable/disable option.  (If
 298    the user does not, the default is used.  Duh.)  No argument checking at
 299    all is done in this signature.  See GLIBCXX_ENABLE_CXX_FLAGS for an
 300    example of handling, and an error message.
 301 </p>
 302
 303 <hr />
 304 </body>
 305 </html>