| 1 |
20 |
jlechner |
<?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
|
| 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 && 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
|
| 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>
|
