Subversion Repositories openrisc_2011-10-31

FIXINCLUDES OPERATION

=====================

See also:  http://autogen.SourceForge.net/fixinc.html

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 fixincludes/inclhack.def.  A program called AutoGen

(http://autogen.SourceForge.net) uses these definitions to instantiate

several different templates that then produces code for a fixinclude

program (fixincl.x) and a shell script to test its functioning.  On

certain platforms (viz. those that do not have functional bidirectional

pipes), the fixincl program is split into two.  This should only concern

you on DOS and BeOS.

Regards,

        Bruce 

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:  bkorb@gnu.org.

To make your fix, you will need to do several things:

1.  Obtain access to the AutoGen program on some platform.  It does

    not have to be your build platform, but it is more convenient.

2.  Edit "inclhack.def" to reflect the changes you need to make.

    See below for information on how to make those changes.

3.  Run the "genfixes" shell script to produce a new copy of

    the "fixincl.x" file.

4.  Rebuild the compiler and check the header causing the issue.

    Make sure it is now properly handled.  Add tests to the

    "test_text" entry(ies) that validate your fix.  This will

    help ensure that future fixes won't negate your work.

5.  Go into the fixincludes build directory and type, "make check".

    You are guaranteed to have issues printed out as a result.

    Look at the diffs produced.  Make sure you have not clobbered

    the proper functioning of a different fix.  Make sure your

    fix is properly tested and it does what it is supposed to do.

6.  Now that you have the right things happening, synchronize the

    $(srcdir)/tests/base directory with the $(builddir)/tests/res

    directory.  The output of "make check" will be some diffs that

    should give you some hints about what to do.

7.  Rerun "make check" and verify that there are no issues left.

MAKING CHANGES TO INCLHACK.DEF

==============================

0.  If you are not the fixincludes maintainer, please send that

    person email about any changes you may want to make.  Thanks!

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

    identify the files with "files = " entries.  If you use fnmatch(3C)

    wild card characters in a "files" entry, be certain that the first

    "files" entry has no such character.  Otherwise, the "make check"

    machinery will attempt to create files with those characters in the

    name.  That is inconvenient.

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", "mach"

    and "c-test" because they are performed internally:

    * select - Run a regex on the contents of the file being considered.

               All such regex-es must match.  Matching is done with

               extended regular expressions.

    * bypass - Run a regex on the contents of the file being considered.

               No such regex may match.

    * c_test - call a function in fixtests.c.  See that file.

    * files  - the "fnmatch" pattern of the file(s) to examine for

               the issue.  There may be several copies of this attribute.

               If the header lives in a /usr/include subdirectory, be

               sure to include that subdirectory in the name. e.g. net/if.h

    * mach   - Match the output of config.guess against a series of fnmatch

               patterns.  It must match at least one of the patterns, unless

               "not-machine" has also been specified.  In that case, the

               config.guess output must not match any of the patterns.

    The next test is relatively slow because it must be handled in a

    separate shell process.  Some platforms do not support server shells,

    so the whole process is even slower and more cumbersome there.

    * test   - These should be arguments to the program, "/bin/test".

               You may perform multiple commands, if you enclose them

               in backquotes and echo out valid test arguments.  For

               example, you might echo out '0 -eq 1' if you want a false

               result, or '0 -eq 0' for a true result.

    These tests are required to:

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

    It is desirable 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 understand 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).

    Each test must pass or the fix is not applied.  For example,

    all "select" expressions must be found and not one "bypass"

    selection may be found.

    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.  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!!

    4.  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.

        These files also contain tables that describe the currently

        implemented fixes and tests.

    If at all possible, you should try to use one of the C language

    fixes as it is far more efficient.  There are currently five

    such fixes, three of which are very special purpose:

    i) char_macro_def - This function repairs the definition of an

        ioctl macro that presumes CPP macro substitution within

        pairs of single quote characters.

    ii) char_macro_use - This function repairs the usage of ioctl

        macros that no longer can wrap an argument with single quotes.

    iii) machine_name - This function will look at "#if", "#ifdef",

        "#ifndef" and "#elif" directive lines and replace the first

        occurrence of a non-reserved name that is traditionally

        pre-defined by the native compiler.

    The next two are for general use:

    iv) wrap - wraps the entire file with "#ifndef", "#define" and

        "#endif" self-exclusionary text.  It also, optionally, inserts

        a prolog after the "#define" and an epilog just before the

        "#endif".  You can use this for a fix as follows:

            c_fix     = wrap;

            c_fix_arg = "/* prolog text */";

            c_fix_arg = "/* epilog text */";

        If you want an epilog without a prolog, set the first "c_fix_arg"

        to the empty string.  Both or the second "c_fix_arg"s may be

        omitted and the file will still be wrapped.

        THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:

        If the regular expression '#if.*__need' is found, then it is

        assumed that the file needs to be read and interpreted more

        than once.  However, the prolog and epilog text (if any) will

        be inserted.

    v) format - Replaces text selected with a regular expression with

        a specialized formating string.  The formatting works as follows:

        The format text is copied to the output until a '%' character

        is found.  If the character after the '%' is another '%', then

        one '%' is output and processing continues.  If the following

        character is not a digit, then the '%' and that character are

        copied and processing continues.  Finally, if the '%' *is*

        followed by a digit, that digit is used as an index into the

        regmatch_t array to replace the two characters with the matched

        text.  i.e.: "%0" is replaced by the full matching text, "%1"

        is the first matching sub-expression, etc.

        This is used as follows:

            c_fix     = format;

            c_fix_arg = "#ifndef %1\n%0\n#endif";

            c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";

        This would wrap a one line #define inside of a "#ifndef"/"#endif"

        pair.  The second "c_fix_arg" may be omitted *IF* there is at least

        one select clause and the first one identifies the text you wish to

        reformat.  It will then be used as the second "c_fix_arg".  You may

        delete the selected text by supplying an empty string for the

        replacement format (the first "c_fix_arg").

        Note: In general, a format c_fix may be used in place of one

        sed expression.  However, it will need to be rewritten by

        hand.  For example:

        sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'

               '@& || __GNUC__ >= 3@';

        may be rewritten using a format c_fix as:

        c_fix     = format;

        c_fix_arg = '%0 || __GNUC__ >= 3';

        c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';

        Multiple sed substitution expressions probably ought to remain sed

        expressions in order to maintain clarity.  Also note that if the

        second sed expression is the same as the first select expression,

        then you may omit the second c_fix_arg.  The select expression will

        be picked up and used in its absence.

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 \n"

                 "#else\n"

                 "#include \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  = hpux11_fabsf;

        files     = math.h;

        select    = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";

        bypass    = "__cplusplus";

        c_fix     = format;

        c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";

        test_text =

        "#  define fabsf(x) ((float)fabs((double)(float)(x)))\n";

    This fix will ensure that the #define for fabs is wrapped

    with C++ protection, providing the header is not already

    C++ aware.

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

5.  Testing fixes.

    The brute force method is, of course, to configure and build

    GCC.  But you can also:

        cd ${top_builddir}/gcc

        rm -rf fixinc.sh include/ stmp-fixinc

        make stmp-fixinc

    I would really recommend, however:

        cd ${top_builddir}/fixincludes

        make check

    To do this, you *must* have autogen installed on your system.

    The "check" step will proceed to construct a shell script that

    will exercise all the fixes, using the sample test_text

    provided with each fix.  Once done, the changes made will

    be compared against the changes saved in the source directory.

    If you are changing the tests or fixes, the change will likely

    be highlighted.