--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/fixincludes/README	Fri Jul 17 14:47:48 2009 +0900
@@ -0,0 +1,325 @@
+
+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 gcc/fixinc/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 <bkorb@gnu.org>
+
+
+
+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 fixinc 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, syncronize 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.
+
+    * 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.
+
+    * mach   - Match the output of config.conf 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.conf 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 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 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 <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  = 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}/gcc/fixinc
+        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.