libstdc++-v3/doc/xml/manual/build_hacking.xml

   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 &amp;&amp; autoconf-2.64 &amp;&amp;
  62     autoheader-2.64 &amp;&amp; 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>[@&lt;:@=BAR@:&gt;@]</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>