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