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