build_hacking.xml revision 1.5
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_SJLJ_EXCEPTIONS 236 GLIBCXX_ENABLE_SYMVERS 237 GLIBCXX_ENABLE_THREADS 238</programlisting> 239<para> 240 All the features which can be controlled with enable/disable 241 configure options. Note how they're alphabetized now? Keep them 242 like that. :-) 243</para> 244<programlisting> 245 AC_LC_MESSAGES 246 libtool bits 247</programlisting> 248<para> 249 Things which we don't seem to use directly, but just has to be 250 present otherwise stuff magically goes wonky. 251</para> 252 253</section> 254 255<section xml:id="build_hacking.configure.enable"><info><title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title></info> 256 257 258 <para> 259 All the <literal>GLIBCXX_ENABLE_FOO</literal> macros use a common 260 helper, <literal>GLIBCXX_ENABLE</literal>. (You don't have to use 261 it, but it's easy.) The helper does two things for us: 262 </para> 263 264<orderedlist> 265 <listitem> 266 <para> 267 Builds the call to the <literal>AC_ARG_ENABLE</literal> macro, with --help text 268 properly quoted and aligned. (Death to changequote!) 269 </para> 270 </listitem> 271 <listitem> 272 <para> 273 Checks the result against a list of allowed possibilities, and 274 signals a fatal error if there's no match. This means that the 275 rest of the <literal>GLIBCXX_ENABLE_FOO</literal> macro doesn't need to test for 276 strange arguments, nor do we need to protect against 277 empty/whitespace strings with the <code>"x$foo" = "xbar"</code> 278 idiom. 279 </para> 280 </listitem> 281</orderedlist> 282 283<para>Doing these things correctly takes some extra autoconf/autom4te code, 284 which made our macros nearly illegible. So all the ugliness is factored 285 out into this one helper macro. 286</para> 287 288<para>Many of the macros take an argument, passed from when they are expanded 289 in configure.ac. The argument controls the default value of the 290 enable/disable switch. Previously, the arguments themselves had defaults. 291 Now they don't, because that's extra complexity with zero gain for us. 292</para> 293 294<para>There are three "overloaded signatures". When reading the descriptions 295 below, keep in mind that the brackets are autoconf's quotation characters, 296 and that they will be stripped. Examples of just about everything occur 297 in acinclude.m4, if you want to look. 298</para> 299 300<programlisting> 301 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) 302 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) 303 GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) 304</programlisting> 305 306<itemizedlist> 307 <listitem> 308 <para> 309 FEATURE is the string that follows --enable. The results of the 310 test (such as it is) will be in the variable $enable_FEATURE, 311 where FEATURE has been squashed. Example: 312 <code>[extra-foo]</code>, controlled by the --enable-extra-foo 313 option and stored in $enable_extra_foo. 314 </para> 315 </listitem> 316 <listitem> 317 <para> 318 DEFAULT is the value to store in $enable_FEATURE if the user does 319 not pass --enable/--disable. It should be one of the permitted 320 values passed later. Examples: <code>[yes]</code>, or 321 <code>[bar]</code>, or <code>[$1]</code> (which passes the 322 argument given to the <literal>GLIBCXX_ENABLE_FOO</literal> macro 323 as the default). 324 </para> 325 <para> 326 For cases where we need to probe for particular models of things, 327 it is useful to have an undocumented "auto" value here (see 328 <literal>GLIBCXX_ENABLE_CLOCALE</literal> for an example). 329 </para> 330 </listitem> 331 <listitem> 332 <para> 333 HELP-ARG is any text to append to the option string itself in the 334 --help output. Examples: <code>[]</code> (i.e., an empty string, 335 which appends nothing), <code>[=BAR]</code>, which produces 336 <code>--enable-extra-foo=BAR</code>, and 337 <code>[@<:@=BAR@:>@]</code>, which produces 338 <code>--enable-extra-foo[=BAR]</code>. See the difference? See 339 what it implies to the user? 340 </para> 341 <para> 342 If you're wondering what that line noise in the last example was, 343 that's how you embed autoconf special characters in output text. 344 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> 345 and you should use them whenever necessary. 346 </para> 347 </listitem> 348 <listitem> 349 <para>HELP-STRING is what you think it is. Do not include the 350 "default" text like we used to do; it will be done for you by 351 GLIBCXX_ENABLE. By convention, these are not full English 352 sentences. Example: [turn on extra foo] 353 </para> 354 </listitem> 355</itemizedlist> 356 357<para> 358 With no other arguments, only the standard autoconf patterns are 359 allowed: "<code>--{enable,disable}-foo[={yes,no}]</code>" The 360 $enable_FEATURE variable is guaranteed to equal either "yes" or "no" 361 after the macro. If the user tries to pass something else, an 362 explanatory error message will be given, and configure will halt. 363</para> 364 365<para> 366 The second signature takes a fifth argument, "<code>[permit 367 a | b | c | ...]</code>" 368 This allows <emphasis>a</emphasis> or <emphasis>b</emphasis> or 369 ... after the equals sign in the option, and $enable_FEATURE is 370 guaranteed to equal one of them after the macro. Note that if you 371 want to allow plain --enable/--disable with no "=whatever", you must 372 include "yes" and "no" in the list of permitted values. Also note 373 that whatever you passed as DEFAULT must be in the list. If the 374 user tries to pass something not on the list, a semi-explanatory 375 error message will be given, and configure will halt. Example: 376 <code>[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> 377</para> 378 379<para> 380 The third signature takes a fifth argument. It is arbitrary shell 381 code to execute if the user actually passes the enable/disable 382 option. (If the user does not, the default is used. Duh.) No 383 argument checking at all is done in this signature. See 384 GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error 385 message. 386</para> 387 388</section> 389</section> <!-- configure --> 390 391<section xml:id="build_hacking.make"><info><title>Make</title></info> 392 393 <para> 394 The build process has to make all of object files needed for 395 static or shared libraries, but first it has to generate some 396 include files. The general order is as follows: 397 </para> 398 399<orderedlist> 400 <listitem> 401 <para> 402 make include files, make pre-compiled headers 403 </para> 404 </listitem> 405 <listitem> 406 <para> 407 make libsupc++ 408 </para> 409 <para> 410 Generates a libtool convenience library, 411 <filename>libsupc++convenience</filename> with language-support 412 routines. Also generates a freestanding static library, 413 <filename>libsupc++.a</filename>. 414 </para> 415 </listitem> 416 <listitem> 417 <para> 418 make src 419 </para> 420 <para> 421 Generates two convenience libraries, one for C++98 and one for 422 C++11, various compatibility files for shared and static 423 libraries, and then collects all the generated bits and creates 424 the final libstdc++ libraries. 425 </para> 426<orderedlist> 427 <listitem> 428 <para> 429 make src/c++98 430 </para> 431 <para> 432 Generates a libtool convenience library, 433 <filename>libc++98convenience</filename> with language-support 434 routines. Uses the <literal>-std=gnu++98</literal> dialect. 435 </para> 436 </listitem> 437 <listitem> 438 <para> 439 make src/c++11 440 </para> 441 <para> 442 Generates a libtool convenience library, 443 <filename>libc++11convenience</filename> with language-support 444 routines. Uses the <literal>-std=gnu++11</literal> dialect. 445 </para> 446 </listitem> 447 <listitem> 448 <para> 449 make src 450 </para> 451 <para> 452 Generates needed compatibility objects for shared and static 453 libraries. Shared-only code is seggregated at compile-time via 454 the macro <literal>_GLIBCXX_SHARED</literal>. 455 </para> 456 457 <para> 458 Then, collects all the generated convenience libraries, adds in 459 any required compatibility objects, and creates the final shared 460 and static libraries: <filename>libstdc++.so</filename> and 461 <filename>libstdc++.a</filename>. 462 </para> 463 464 </listitem> 465</orderedlist> 466 </listitem> 467</orderedlist> 468 469</section> <!-- make --> 470 471</section> 472