Subversion Repositories openrisc

         xml:id="appendix.porting.build_hacking" xreflabel="Build Hacking">

      C++

      BUILD_HACKING

      version

      dynamic

      shared

    As noted previously,

    certain other tools are necessary for hacking on files that

    control configure (configure.ac,

    acinclude.m4) and make

    (Makefile.am). These additional tools

    (automake, and autoconf) are further

    described in detail in their respective manuals. All the libraries

    in GCC try to stay in sync with each other in terms of versions of

    the auto-tools used, so please try to play nicely with the

    neighbors.

      Dependency Graph for Configure and Build Files

    Regenerate all generated files by using the command sequence

    "autoreconf" at the top level of the libstdc++ source

    directory. The following will also work, but is much more complex:

    "aclocal-1.11 && autoconf-2.64 &&

    autoheader-2.64 && automake-1.11" The version

    numbers may be absent entirely or otherwise vary depending on

    the

    current requirements and your vendor's choice of

    installation names.

    Until that glorious day when we can use AC_TRY_LINK with a

    cross-compiler, we have to hardcode the results of what the tests

    would have shown if they could be run.  So we have an inflexible

    mess like crossconfig.m4.

    Wouldn't it be nice if we could store that information in files

    like configure.host, which can be modified without needing to

    regenerate anything, and can even be tweaked without really

    knowing how the configury all works?  Perhaps break the pieces of

    crossconfig.m4 out and place them in their appropriate

    config/{cpu,os} directory.

    Alas, writing macros like

    "AC_DEFINE(HAVE_A_NICE_DAY)" can only be done inside

    files which are passed through autoconf.  Files which are pure

    shell script can be source'd at configure time.  Files which

    contain autoconf macros must be processed with autoconf.  We could

    still try breaking the pieces out into "config/*/cross.m4" bits,

    for instance, but then we would need arguments to aclocal/autoconf

    to properly find them all when generating configure.  I would

    discourage that.

    Most comments should use {octothorpes, shibboleths, hash marks,

    pound signs, whatever} rather than "dnl".  Nearly all comments in

    configure.ac should.  Comments inside macros written in ancilliary

    .m4 files should.  About the only comments which should

    not use #, but use dnl instead, are comments

    outside our own macros in the ancilliary

    files.  The difference is that # comments show up in

    configure (which is most helpful for debugging),

    while dnl'd lines just vanish.  Since the macros in ancilliary

    files generate code which appears in odd places, their "outside"

    comments tend to not be useful while reading

    configure.

    Do not use any $target* variables, such as

    $target_alias.  The single exception is in

    configure.ac, for automake+dejagnu's sake.

    The nice thing about acinclude.m4/aclocal.m4 is that macros aren't

    actually performed/called/expanded/whatever here, just loaded.  So

    we can arrange the contents however we like.  As of this writing,

    acinclude.m4 is arranged as follows:

    GLIBCXX_CHECK_HOST

    GLIBCXX_TOPREL_CONFIGURE

    GLIBCXX_CONFIGURE

    All the major variable "discovery" is done here.  CXX, multilibs,

    etc.

    fragments included from elsewhere

    Right now, "fragments" == "the math/linkage bits".

    GLIBCXX_CHECK_COMPILER_FEATURES

    GLIBCXX_CHECK_LINKER_FEATURES

    GLIBCXX_CHECK_WCHAR_T_SUPPORT

  Next come extra compiler/linker feature tests.  Wide character

  support was placed here because I couldn't think of another place

  for it.  It will probably get broken apart like the math tests,

  because we're still disabling wchars on systems which could actually

  support them.

    GLIBCXX_CHECK_SETRLIMIT_ancilliary

    GLIBCXX_CHECK_SETRLIMIT

    GLIBCXX_CHECK_S_ISREG_OR_S_IFREG

    GLIBCXX_CHECK_POLL

    GLIBCXX_CHECK_WRITEV

    GLIBCXX_CONFIGURE_TESTSUITE

  Feature tests which only get used in one place.  Here, things used

  only in the testsuite, plus a couple bits used in the guts of I/O.

    GLIBCXX_EXPORT_INCLUDES

    GLIBCXX_EXPORT_FLAGS

    GLIBCXX_EXPORT_INSTALL_INFO

  Installation variables, multilibs, working with the rest of the

  compiler.  Many of the critical variables used in the makefiles are

  set here.

    GLIBGCC_ENABLE

    GLIBCXX_ENABLE_C99

    GLIBCXX_ENABLE_CHEADERS

    GLIBCXX_ENABLE_CLOCALE

    GLIBCXX_ENABLE_CONCEPT_CHECKS

    GLIBCXX_ENABLE_CSTDIO

    GLIBCXX_ENABLE_CXX_FLAGS

    GLIBCXX_ENABLE_C_MBCHAR

    GLIBCXX_ENABLE_DEBUG

    GLIBCXX_ENABLE_DEBUG_FLAGS

    GLIBCXX_ENABLE_LONG_LONG

    GLIBCXX_ENABLE_PCH

    GLIBCXX_ENABLE_SJLJ_EXCEPTIONS

    GLIBCXX_ENABLE_SYMVERS

    GLIBCXX_ENABLE_THREADS

  All the features which can be controlled with enable/disable

  configure options.  Note how they're alphabetized now?  Keep them

  like that.  :-)

    AC_LC_MESSAGES

    libtool bits

  Things which we don't seem to use directly, but just has to be

  present otherwise stuff magically goes wonky.

    All the GLIBCXX_ENABLE_FOO macros use a common helper,

    GLIBCXX_ENABLE.  (You don't have to use it, but it's easy.)  The

    helper does two things for us:

     Builds the call to the AC_ARG_ENABLE macro, with --help text

     properly quoted and aligned.  (Death to changequote!)

     Checks the result against a list of allowed possibilities, and

     signals a fatal error if there's no match.  This means that the

     rest of the GLIBCXX_ENABLE_FOO macro doesn't need to test for

     strange arguments, nor do we need to protect against

     empty/whitespace strings with the "x$foo" = "xbar"

     idiom.

Doing these things correctly takes some extra autoconf/autom4te code,

   which made our macros nearly illegible.  So all the ugliness is factored

   out into this one helper macro.

Many of the macros take an argument, passed from when they are expanded

   in configure.ac.  The argument controls the default value of the

   enable/disable switch.  Previously, the arguments themselves had defaults.

   Now they don't, because that's extra complexity with zero gain for us.

There are three "overloaded signatures".  When reading the descriptions

   below, keep in mind that the brackets are autoconf's quotation characters,

   and that they will be stripped.  Examples of just about everything occur

   in acinclude.m4, if you want to look.

    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING)

    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c)

    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER)

     FEATURE is the string that follows --enable.  The results of the

     test (such as it is) will be in the variable $enable_FEATURE,

     where FEATURE has been squashed.  Example:

     [extra-foo], controlled by the --enable-extra-foo

     option and stored in $enable_extra_foo.

     DEFAULT is the value to store in $enable_FEATURE if the user does

     not pass --enable/--disable.  It should be one of the permitted

     values passed later.  Examples: [yes], or

     [bar], or [$1] (which passes the

     argument given to the GLIBCXX_ENABLE_FOO macro as the

     default).

     For cases where we need to probe for particular models of things,

     it is useful to have an undocumented "auto" value here (see

     GLIBCXX_ENABLE_CLOCALE for an example).

     HELP-ARG is any text to append to the option string itself in the

     --help output.  Examples: [] (i.e., an empty string,

     which appends nothing), [=BAR], which produces

     --enable-extra-foo=BAR, and

     [@<:@=BAR@:>@], which produces

     --enable-extra-foo[=BAR].  See the difference?  See

     what it implies to the user?

     If you're wondering what that line noise in the last example was,

     that's how you embed autoconf special characters in output text.

     They're called quadrigraphs

     and you should use them whenever necessary.

   HELP-STRING is what you think it is.  Do not include the

   "default" text like we used to do; it will be done for you by

   GLIBCXX_ENABLE.  By convention, these are not full English

   sentences.  Example: [turn on extra foo]

  With no other arguments, only the standard autoconf patterns are

  allowed: "--{enable,disable}-foo[={yes,no}]" The

  $enable_FEATURE variable is guaranteed to equal either "yes" or "no"

  after the macro.  If the user tries to pass something else, an

  explanatory error message will be given, and configure will halt.

  The second signature takes a fifth argument, "[permit

  a | b | c | ...]"

  This allows a or b or

  ... after the equals sign in the option, and $enable_FEATURE is

  guaranteed to equal one of them after the macro.  Note that if you

  want to allow plain --enable/--disable with no "=whatever", you must

  include "yes" and "no" in the list of permitted values.  Also note

  that whatever you passed as DEFAULT must be in the list.  If the

  user tries to pass something not on the list, a semi-explanatory

  error message will be given, and configure will halt.  Example:

  [permit generic|gnu|ieee_1003.1-2001|yes|no|auto]

  The third signature takes a fifth argument.  It is arbitrary shell

  code to execute if the user actually passes the enable/disable

  option.  (If the user does not, the default is used.  Duh.)  No

  argument checking at all is done in this signature.  See

  GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error

  message.