gcc/gcc/fixinc

FIXINCLUDES OPERATION
=====================

See also:  http://autogen.linuxbox.com/fixincludes

The set of fixes required was distilled down to just the data required
to specify what needed to happen for each fix.  Those data were edited
into a file named gcc/fixinc/inclhack.def.  A program called
AutoGen (http://autogen.linuxbox.com) uses these definitions to
instantiate several different templates (gcc/fixinc/*.tpl) that then
produces a fixincludes replacement shell script (inclhack.sh), a
replacement binary program (fixincl.x) and a script to drive the
binary fixincl.sh).

If there is no special purpose script, then mkfixinc.sh will try to
compile, link and test execute the binary version.  If it cannot be
successfully built, the shell version will be used instead.  If
mkfixinc.sh determines that your system needs machine-specific fixes
that have not yet been applied to inclhack.def, it will install and
use the current fixinc.* for that system instead.

Regards,
	Bruce <autogen@linuxbox.com>



GCC MAINTAINER INFORMATION
==========================

If you are having some problem with a system header that is either
broken by the manufacturer, or is broken by the fixinclude process,
then you will need to alter or add information to the include fix
definitions file, ``inclhack.def''.  Please also send relevant
information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and,
please, to me:  autogen@linuxbox.com.

Here are the rules for making fixes in the inclhack.def file:

1.  Every fix must have a "hackname" that is compatible with C syntax
    for variable names and is unique without regard to alphabetic case.
    Please keep them alphabetical by this name.  :-)

2.  If the problem is known to exist only in certain files,
    then name each such file with a "files = " entry.

3.  It is relatively expensive to fire off a process to fix a source
    file, therefore write apply tests to avoid unnecessary fix
    processes.  The preferred apply tests are "select", "bypass" and
    "c_test" because they are performed internally.  "test" sends
    a command to a server shell that actually fires off one or more
    processes to do the testing.  Avoid it, if you can, but it is
    still more efficient than a fix process.  Also available is
    "mach".  If the target machine matches any of the named
    globbing-style patterns, then the machine name test will pass.
    It is desired, however, to limit the use of this test.

    These tests are required to:

    1.  Be positive for all header files that require the fix.

    It is desireable to:

    2.  Be negative as often as possible whenever the fix is not
        required, avoiding the process overhead.

    It is nice if:

    3.  The expression is as simple as possible to both
        process and uderstand by people.  :-)

        Please take advantage of the fact AutoGen will glue
        together string fragments.  It helps.  Also take note
        that double quote strings and single quote strings have
        different formation rules.  Double quote strings are a
        tiny superset of ANSI-C string syntax.  Single quote
        strings follow shell single quote string formation
        rules, except that the backslash is processed before
        '\\', '\'' and '#' characters (using C character syntax).

    Examples of test specifications:

      hackname = broken_assert_stdio;
      files    = assert.h;
      select   = stderr;
      bypass   = "include.*stdio.h";

    The ``broken_assert_stdio'' fix will be applied only to a file
    named "assert.h" if it contains the string "stderr" _and_ it
    does _not_ contain the expression "include.*stdio.h".

      hackname = no_double_slash;
      c_test   = "double_slash";

    The ``no_double_slash'' fix will be applied if the
    ``double_slash_test()'' function says to.  See ``fixtests.c''
    for documentation on how to include new functions into that
    module.

4.  There are currently four methods of fixing a file:

    1.  a series of sed expressions.  Each will be an individual
        "-e" argument to a single invocation of sed.

    2.  a shell script.  These scripts are _required_ to read all
        of stdin in order to avoid pipe stalls.  They may choose to
        discard the input.

    3.  A C language subroutine method for both tests and fixes.
        See ``fixtests.c'' for instructions on writing C-language
        applicability tests and ``fixfixes.c'' for C-language fixing.

    4.  Replacement text.  If the replacement is empty, then no
        fix is applied.  Otherwise, the replacement text is
        written to the output file and no further fixes are
        applied.  If you really want a no-op file, replace the
        file with a comment.

        Replacement text "fixes" must be first in this file!!

    Examples of fixes:
    ------------------

      hackname = AAA_ki_iface;
      replace; /* empty replacement -> no fixing the file */

    When this ``fix'' is invoked, it will prevent any fixes
    from being applied.

    ------------------

      hackname = AAB_svr4_no_varargs;
      replace  = "/* This file was generated by fixincludes.  */\n"
                 "#ifndef _SYS_VARARGS_H\n"
                 "#define _SYS_VARARGS_H\n\n"

                 "#ifdef __STDC__\n"
                 "#include <stdarg.h>\n"
                 "#else\n"
                 "#include <varargs.h>\n"
                 "#endif\n\n"

                 "#endif  /* _SYS_VARARGS_H */\n";

    When this ``fix'' is invoked, the replacement text will be
    emitted into the replacement include file.  No further fixes
    will be applied.

    ------------------

      hackname = dec_intern_asm;
      files    = c_asm.h;
      sed = "/^[ \t]*float[ \t]*fasm/i\\\n#ifdef __DECC\n";
      sed = "/^[ \t]*#[ \t]*pragma[ \t]*intrinsic([ \t]*dasm/a\\\n"
            "#endif\n";

    When this ``fix'' is invoked, sed will be run on the original
    file with two "-e" arguments.  Since these arguments have double
    quoted string values, the strings actually passed to ``sed''
    will have been processed in the same fashion that the C compiler
    processes its string specifications.  Including the concatenation
    of the two pieces of the second sed "-e" argument.

    ------------------

      hackname = m88k_multi_incl;
      shell    =
        "echo Fixing $file, to protect against multiple inclusion. >&2
        cpp_wrapper=`echo $file | sed -e 's,\\.,_,g' -e 's,/,_,g'`
        echo \"#ifndef __GCC_GOT_${cpp_wrapper}_\"
        echo \"#define __GCC_GOT_${cpp_wrapper}_\"
        cat
        echo \"#endif /* ! __GCC_GOT_${cpp_wrapper}_ */\"";

    This is a shell script fix.  Note the ``cat'' without any arguments.
    This will drain stdin.  If the contents of the file were to be
    discarded, you would have to have something like ``cat > /dev/null''
    in the script.

    ------------------

      hackname = no_double_slash;
      c_fix    = "no_double_slash";

    This specifies a fix to be supplied via a hand coded internal
    function named ``no_double_slash_fix()''.  See ``fixfixes.c''
    for documentation on how to include new functions into that
    module.

5.  Testing fixes.

    The brute force method is, of course, to configure and build
    GCC.  There are easier ways, too.  You can run the compiled
    binaries in isolation.  ``c_tests'' can be tested with
    ``fixtests'', ``c_fixes'' with ``fixfixes'' and any fix or
    test can be tested with ``fixincl''.

    ``fixtests'' is invoked as follows:

        fixtests filename.h your_test_name
        if [ $? -ne 0 ]
        then echo do not apply your_fix_name
        else echo APPLY your_fix_name ; fi

    and ``fixfixes'' is invoked thus:

        fixfixes filename.h your_fix_name < filename.h > /tmp/fixed

    The file name argument is required, but is only used as a hint
    for use by ``your_fix_name'', it is not used for obtaining the
    data.  Also, ``your_fix_name'' and ``your_test_name'' may be
    the same, since fix names and test names are in different
    "name spaces."

    The ``fixincl'' program is a little harder to work with  :-}.
    It was written with the expectation that it would be run
    inside of the fixincl.sh script that handles everything.

    Run it with no arguments to get usage hints, but here is what
    you will need to do (approximately):

        FI=${top_builddir}/gcc/fixinc/fixincl
        TARGET_MACHINE=`sh ${top_srcdir}/config.guess`
        SRCDIR=/usr/include
        DESTDIR=/tmp/fixtest
        VERBOSE=4
        FIND_BASE="."
        export TARGET_MACHINE SRCDIR DESTDIR VERBOSE FIND_BASE
        rm -rf ${DESTDIR}
        mkdir -p ${DESTDIR}
        cd ${SRCDIR}
        find * -follow -type f -name '*.h' > ${DESTDIR}/LIST
        # you may edit this to the list you want
        ${FI} ${DESTDIR}/LIST > /dev/null 2> ${DESTDIR}/LOG

    Check your results in ${DESTDIR}/LOG.  The stdout output
    is merely some shell commands that are relevant only to
    the fixincl.sh shell script.