| <?xml version="1.0" encoding="ISO-8859-1"?> |
| <!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" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> |
| <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> |
| <meta name="DESCRIPTION" content="configury for libstdc++" /> |
| <meta name="GENERATOR" content="vi and eight fingers" /> |
| <title>libstdc++-v3 configury</title> |
| <link rel="StyleSheet" href="../lib3styles.css" type='text/css' /> |
| <link rel="Start" href="../documentation.html" type="text/html" |
| title="GNU C++ Standard Library" /> |
| </head> |
| <body> |
| |
| <h1><code>> open configury door</code></h1> |
| <h1><code>> look</code></h1> |
| |
| <p class="larger"><code>You are in a maze of twisty passages, all |
| different.</code></p> |
| <p class="larger"><code>It is dark. You are likely to be eaten by a |
| Canadian cross build.</code></p> |
| |
| |
| <hr /> |
| <h2>Notes on libstdc++-v3 configury</h2> |
| <blockquote> |
| No problem is insoluble in all conceivable circumstances.<br /> |
| -- The Cosmic AC, |
| <a href="http://mit.edu/tylerc/www/twt/LQ1.htm">The |
| Last Question</a>, by Isaac Asimov |
| </blockquote> |
| <ul> |
| <li><a href="#deps">what comes from where</a></li> |
| <li><a href="#breakout">storing information in non-AC files, like |
| configure.host</a></li> |
| <li><a href="#general">general config notes</a></li> |
| <li><a href="#aclayout">acinclude.m4 layout</a></li> |
| <li><a href="#enable"><code>--enable</code> howto</a></li> |
| </ul> |
| |
| <hr /> |
| <h3><a name="deps">what comes from where</a></h3> |
| <p class="centered"><img src="confdeps.png" |
| alt="Dependency graph in PNG graphics format. (Get a better browser!)" /></p> |
| |
| <p>Regenerate using a command sequence like |
| <code>"aclocal-1.7 && autoconf-2.59 && autoheader-2.59 |
| && automake-1.7"</code> as needed. And/or configure with |
| --enable-maintainer-mode. The version numbers will vary depending on |
| <a href="http://gcc.gnu.org/install/prerequisites.html">the current |
| requirements</a> and your vendor's choice of installation names. |
| </p> |
| |
| |
| <hr /> |
| <h3><a name="breakout">storing information in non-AC files, like |
| configure.host</a></h3> |
| <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>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> |
| |
| |
| <hr /> |
| <h3><a name="general">general config notes</a></h3> |
| <p>Lots of stuff got thrown out because the new autotools kindly generate |
| the same (or better) shell code for us. |
| </p> |
| |
| <p>Most comments should use {octothorpes, shibboleths, hash marks, pound |
| signs, whatevers} 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 <em>not</em> use #, but use dnl |
| instead, are comments <em>outside</em> our own macros in the ancilliary |
| files. The difference is that # comments show up in <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>configure</code>. |
| </p> |
| |
| <p>Do not use any <code>$target*</code> variables, such as |
| <code>$target_alias</code>. The single exception is in configure.ac, |
| for automake+dejagnu's sake. |
| </p> |
| |
| <p> |
| </p> |
| |
| <hr /> |
| <h3><a name="aclayout">acinclude.m4 layout</a></h3> |
| <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> |
| GLIBCXX_CHECK_HOST |
| GLIBCXX_TOPREL_CONFIGURE |
| GLIBCXX_CONFIGURE |
| </pre> |
| <p>All the major variable "discovery" is done here. CXX, multilibs, etc. |
| </p> |
| <pre> |
| fragments included from elsewhere |
| </pre> |
| <p>Right now, "fragments" == "the math/linkage bits". |
| </p> |
| <pre> |
| 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> |
| 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> |
| 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> |
| 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> |
| 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> |
| |
| |
| <hr /> |
| <h3><a name="enable"><code>--enable</code> howto</a></h3> |
| <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> |
| |
| <ol> |
| <li>Builds the call to the AC_ARG_ENABLE macro, with --help text properly |
| quoted and aligned. (Death to changequote!)</li> |
| <li>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>"x$foo" = "xbar"</code> idiom.</li> |
| </ol> |
| |
| <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> |
| 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> |
| |
| <ul> |
| <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>[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>[yes]</code>, or <code>[bar]</code>, or |
| <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>[]</code> (i.e., an empty string, |
| which appends nothing), |
| <code>[=BAR]</code>, which produces |
| <code>--enable-extra-foo=BAR</code>, and |
| <code>[@<:@=BAR@:>@]</code>, which produces |
| <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 |
| href="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_95.html#SEC95"><em>quadrigraphs</em></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> |
| |
| <p>With no other arguments, only the standard autoconf patterns are |
| allowed: "<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>[permit <em>a</em>|<em>b</em>|<em>c</em>|<em>...</em>]</code>" |
| This allows <em>a</em> or <em>b</em> 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>[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> |
| |
| <hr /> |
| </body> |
| </html> |
