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>> open configury door</code></h1> 20<h1><code>> look</code></h1> 21 22<p class="larger"><code>You are in a maze of twisty passages, all 23different.</code></p> 24<p class="larger"><code>It is dark. You are likely to be eaten by a 25Canadian cross build.</code></p> 26 27 28<hr /> 29<h2>Notes on libstdc++-v3 configury</h2> 30<blockquote> 31No problem is insoluble in all conceivable circumstances.<br /> 32-- The Cosmic AC, 33<a href="http://mit.edu/tylerc/www/twt/LQ1.htm">The 34Last 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 && autoconf-2.59 && autoheader-2.59 52 && 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>[@<:@=BAR@:>@]</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 253href="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> 290
