build_hacking.xml revision 1.1
1<sect1 id="appendix.porting.build_hacking" xreflabel="Build Hacking"> 2<?dbhtml filename="build_hacking.html"?> 3 4<sect1info> 5 <keywordset> 6 <keyword> 7 C++ 8 </keyword> 9 <keyword> 10 BUILD_HACKING 11 </keyword> 12 <keyword> 13 version 14 </keyword> 15 <keyword> 16 dynamic 17 </keyword> 18 <keyword> 19 shared 20 </keyword> 21 </keywordset> 22</sect1info> 23 24<title>Configure and Build Hacking</title> 25 26<sect2 id="build_hacking.prereq"> 27 <title>Prerequisites</title> 28 <para> 29 As noted <ulink 30 url="http://gcc.gnu.org/install/prerequisites.html">previously</ulink>, 31 certain other tools are necessary for hacking on files that 32 control configure (<code>configure.ac</code>, 33 <code>acinclude.m4</code>) and make 34 (<code>Makefile.am</code>). These additional tools 35 (<code>automake</code>, and <code>autoconf</code>) are further 36 described in detail in their respective manuals. All the libraries 37 in GCC try to stay in sync with each other in terms of versions of 38 the auto-tools used, so please try to play nicely with the 39 neighbors. 40 </para> 41</sect2> 42 43<sect2 id="build_hacking.map"> 44 <title>Overview: What Comes from Where</title> 45 46 <screen> 47 <inlinemediaobject> 48 <imageobject> 49 <imagedata fileref="../images/confdeps.png"/> 50 </imageobject> 51 <textobject> 52 <phrase>Dependency Graph Configure to Build Files</phrase> 53 </textobject> 54 </inlinemediaobject> 55 </screen> 56 57 <para> 58 Regenerate all generated files by using the command sequence 59 <code>"autoreconf"</code> at the top level of the libstdc++ source 60 directory. The following will also work, but is much more complex: 61 <code>"aclocal-1.11 && autoconf-2.64 && 62 autoheader-2.64 && automake-1.11"</code> The version 63 numbers may be absent entirely or otherwise vary depending on 64 <ulink url="http://gcc.gnu.org/install/prerequisites.html">the 65 current requirements</ulink> and your vendor's choice of 66 installation names. 67 </para> 68</sect2> 69 70<sect2 id="build_hacking.scripts"> 71 <title>Storing Information in non-AC files (like configure.host)</title> 72 73 <para> 74 Until that glorious day when we can use AC_TRY_LINK with a 75 cross-compiler, we have to hardcode the results of what the tests 76 would have shown if they could be run. So we have an inflexible 77 mess like crossconfig.m4. 78 </para> 79 80 <para> 81 Wouldn't it be nice if we could store that information in files 82 like configure.host, which can be modified without needing to 83 regenerate anything, and can even be tweaked without really 84 knowing how the configury all works? Perhaps break the pieces of 85 crossconfig.m4 out and place them in their appropriate 86 config/{cpu,os} directory. 87 </para> 88 89 <para> 90 Alas, writing macros like 91 "<code>AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside 92 files which are passed through autoconf. Files which are pure 93 shell script can be source'd at configure time. Files which 94 contain autoconf macros must be processed with autoconf. We could 95 still try breaking the pieces out into "config/*/cross.m4" bits, 96 for instance, but then we would need arguments to aclocal/autoconf 97 to properly find them all when generating configure. I would 98 discourage that. 99</para> 100</sect2> 101 102<sect2 id="build_hacking.conventions"> 103 <title>Coding and Commenting Conventions</title> 104 105 <para> 106 Most comments should use {octothorpes, shibboleths, hash marks, 107 pound signs, whatever} rather than "dnl". Nearly all comments in 108 configure.ac should. Comments inside macros written in ancilliary 109 .m4 files should. About the only comments which should 110 <emphasis>not</emphasis> use #, but use dnl instead, are comments 111 <emphasis>outside</emphasis> our own macros in the ancilliary 112 files. The difference is that # comments show up in 113 <code>configure</code> (which is most helpful for debugging), 114 while dnl'd lines just vanish. Since the macros in ancilliary 115 files generate code which appears in odd places, their "outside" 116 comments tend to not be useful while reading 117 <code>configure</code>. 118 </para> 119 120 <para> 121 Do not use any <code>$target*</code> variables, such as 122 <code>$target_alias</code>. The single exception is in 123 configure.ac, for automake+dejagnu's sake. 124 </para> 125</sect2> 126 127<sect2 id="build_hacking.acinclude"> 128 <title>The acinclude.m4 layout</title> 129 <para> 130 The nice thing about acinclude.m4/aclocal.m4 is that macros aren't 131 actually performed/called/expanded/whatever here, just loaded. So 132 we can arrange the contents however we like. As of this writing, 133 acinclude.m4 is arranged as follows: 134 </para> 135 <programlisting> 136 GLIBCXX_CHECK_HOST 137 GLIBCXX_TOPREL_CONFIGURE 138 GLIBCXX_CONFIGURE 139 </programlisting> 140 <para> 141 All the major variable "discovery" is done here. CXX, multilibs, 142 etc. 143 </para> 144 <programlisting> 145 fragments included from elsewhere 146 </programlisting> 147 <para> 148 Right now, "fragments" == "the math/linkage bits". 149 </para> 150<programlisting> 151 GLIBCXX_CHECK_COMPILER_FEATURES 152 GLIBCXX_CHECK_LINKER_FEATURES 153 GLIBCXX_CHECK_WCHAR_T_SUPPORT 154</programlisting> 155<para> 156 Next come extra compiler/linker feature tests. Wide character 157 support was placed here because I couldn't think of another place 158 for it. It will probably get broken apart like the math tests, 159 because we're still disabling wchars on systems which could actually 160 support them. 161</para> 162<programlisting> 163 GLIBCXX_CHECK_SETRLIMIT_ancilliary 164 GLIBCXX_CHECK_SETRLIMIT 165 GLIBCXX_CHECK_S_ISREG_OR_S_IFREG 166 GLIBCXX_CHECK_POLL 167 GLIBCXX_CHECK_WRITEV 168 169 GLIBCXX_CONFIGURE_TESTSUITE 170</programlisting> 171<para> 172 Feature tests which only get used in one place. Here, things used 173 only in the testsuite, plus a couple bits used in the guts of I/O. 174</para> 175<programlisting> 176 GLIBCXX_EXPORT_INCLUDES 177 GLIBCXX_EXPORT_FLAGS 178 GLIBCXX_EXPORT_INSTALL_INFO 179</programlisting> 180<para> 181 Installation variables, multilibs, working with the rest of the 182 compiler. Many of the critical variables used in the makefiles are 183 set here. 184</para> 185<programlisting> 186 GLIBGCC_ENABLE 187 GLIBCXX_ENABLE_C99 188 GLIBCXX_ENABLE_CHEADERS 189 GLIBCXX_ENABLE_CLOCALE 190 GLIBCXX_ENABLE_CONCEPT_CHECKS 191 GLIBCXX_ENABLE_CSTDIO 192 GLIBCXX_ENABLE_CXX_FLAGS 193 GLIBCXX_ENABLE_C_MBCHAR 194 GLIBCXX_ENABLE_DEBUG 195 GLIBCXX_ENABLE_DEBUG_FLAGS 196 GLIBCXX_ENABLE_LONG_LONG 197 GLIBCXX_ENABLE_PCH 198 GLIBCXX_ENABLE_SJLJ_EXCEPTIONS 199 GLIBCXX_ENABLE_SYMVERS 200 GLIBCXX_ENABLE_THREADS 201</programlisting> 202<para> 203 All the features which can be controlled with enable/disable 204 configure options. Note how they're alphabetized now? Keep them 205 like that. :-) 206</para> 207<programlisting> 208 AC_LC_MESSAGES 209 libtool bits 210</programlisting> 211<para> 212 Things which we don't seem to use directly, but just has to be 213 present otherwise stuff magically goes wonky. 214</para> 215 216</sect2> 217 218<sect2 id="build_hacking.enable"> 219 <title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title> 220 221 <para> 222 All the GLIBCXX_ENABLE_FOO macros use a common helper, 223 GLIBCXX_ENABLE. (You don't have to use it, but it's easy.) The 224 helper does two things for us: 225 </para> 226 227<orderedlist> 228 <listitem> 229 <para> 230 Builds the call to the AC_ARG_ENABLE macro, with --help text 231 properly quoted and aligned. (Death to changequote!) 232 </para> 233 </listitem> 234 <listitem> 235 <para> 236 Checks the result against a list of allowed possibilities, and 237 signals a fatal error if there's no match. This means that the 238 rest of the GLIBCXX_ENABLE_FOO macro doesn't need to test for 239 strange arguments, nor do we need to protect against 240 empty/whitespace strings with the <code>"x$foo" = "xbar"</code> 241 idiom. 242 </para> 243 </listitem> 244</orderedlist> 245 246<para>Doing these things correctly takes some extra autoconf/autom4te code, 247 which made our macros nearly illegible. So all the ugliness is factored 248 out into this one helper macro. 249</para> 250 251<para>Many of the macros take an argument, passed from when they are expanded 252 in configure.ac. The argument controls the default value of the 253 enable/disable switch. Previously, the arguments themselves had defaults. 254 Now they don't, because that's extra complexity with zero gain for us. 255</para> 256 257<para>There are three "overloaded signatures". When reading the descriptions 258 below, keep in mind that the brackets are autoconf's quotation characters, 259 and that they will be stripped. Examples of just about everything occur 260 in acinclude.m4, if you want to look. 261</para> 262 263<programlisting> 264 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) 265 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) 266 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) 267</programlisting> 268 269<itemizedlist> 270 <listitem> 271 <para> 272 FEATURE is the string that follows --enable. The results of the 273 test (such as it is) will be in the variable $enable_FEATURE, 274 where FEATURE has been squashed. Example: 275 <code>[extra-foo]</code>, controlled by the --enable-extra-foo 276 option and stored in $enable_extra_foo. 277 </para> 278 </listitem> 279 <listitem> 280 <para> 281 DEFAULT is the value to store in $enable_FEATURE if the user does 282 not pass --enable/--disable. It should be one of the permitted 283 values passed later. Examples: <code>[yes]</code>, or 284 <code>[bar]</code>, or <code>[$1]</code> (which passes the 285 argument given to the GLIBCXX_ENABLE_FOO macro as the 286 default). 287 </para> 288 <para> 289 For cases where we need to probe for particular models of things, 290 it is useful to have an undocumented "auto" value here (see 291 GLIBCXX_ENABLE_CLOCALE for an example). 292 </para> 293 </listitem> 294 <listitem> 295 <para> 296 HELP-ARG is any text to append to the option string itself in the 297 --help output. Examples: <code>[]</code> (i.e., an empty string, 298 which appends nothing), <code>[=BAR]</code>, which produces 299 <code>--enable-extra-foo=BAR</code>, and 300 <code>[@<:@=BAR@:>@]</code>, which produces 301 <code>--enable-extra-foo[=BAR]</code>. See the difference? See 302 what it implies to the user? 303 </para> 304 <para> 305 If you're wondering what that line noise in the last example was, 306 that's how you embed autoconf special characters in output text. 307 They're called <ulink 308 url="http://www.gnu.org/software/autoconf/manual/autoconf.html#Quadrigraphs"><emphasis>quadrigraphs</emphasis></ulink> 309 and you should use them whenever necessary. 310 </para> 311 </listitem> 312 <listitem> 313 <para>HELP-STRING is what you think it is. Do not include the 314 "default" text like we used to do; it will be done for you by 315 GLIBCXX_ENABLE. By convention, these are not full English 316 sentences. Example: [turn on extra foo] 317 </para> 318 </listitem> 319</itemizedlist> 320 321<para> 322 With no other arguments, only the standard autoconf patterns are 323 allowed: "<code>--{enable,disable}-foo[={yes,no}]</code>" The 324 $enable_FEATURE variable is guaranteed to equal either "yes" or "no" 325 after the macro. If the user tries to pass something else, an 326 explanatory error message will be given, and configure will halt. 327</para> 328 329<para> 330 The second signature takes a fifth argument, "<code>[permit 331 a | b | c | ...]</code>" 332 This allows <emphasis>a</emphasis> or <emphasis>b</emphasis> or 333 ... after the equals sign in the option, and $enable_FEATURE is 334 guaranteed to equal one of them after the macro. Note that if you 335 want to allow plain --enable/--disable with no "=whatever", you must 336 include "yes" and "no" in the list of permitted values. Also note 337 that whatever you passed as DEFAULT must be in the list. If the 338 user tries to pass something not on the list, a semi-explanatory 339 error message will be given, and configure will halt. Example: 340 <code>[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> 341</para> 342 343<para> 344 The third signature takes a fifth argument. It is arbitrary shell 345 code to execute if the user actually passes the enable/disable 346 option. (If the user does not, the default is used. Duh.) No 347 argument checking at all is done in this signature. See 348 GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error 349 message. 350</para> 351 352</sect2> 353 354</sect1> 355