Daily bump.

[pf3gnuchains/gcc-fork.git] / fixincludes / README

diff --git a/fixincludes/README b/fixincludes/README
index 8b8cc98..07a3964 100644 (file)
--- a/fixincludes/README
+++ b/fixincludes/README
@@ -6,7 +6,7 @@ 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
 
 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
+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
 (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


@@ -45,13 +45,13 @@ To make your fix, you will need to do several things:
     "test_text" entry(ies) that validate your fix.  This will
     help ensure that future fixes won't negate your work.
 
     "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".
+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.
 
     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
+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.
     $(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.


@@ -69,32 +69,40 @@ MAKING CHANGES TO INCLHACK.DEF
     for variable names and is unique without regard to alphabetic case.
     Please keep them alphabetical by this name.  :-)
 
     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.
+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
 
 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.  The available
-    tests are:
+    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.
 
     * select - Run a regex on the contents of the file being considered.

-               All such regex-es must match.
+               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.
 
 
     * 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.
 

-    The next two tests are relatively slow because they 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.
+    * 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.conf against a series of globbing
+    * mach   - Match the output of config.guess against a series of fnmatch

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

-               "not-machine" has also been specified.  If that has been
-               specified, then the config.conf output may not match any of
-               the patterns.
+               "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
 
     * test   - These should be arguments to the program, "/bin/test".
                You may perform multiple commands, if you enclose them


@@ -106,7 +114,7 @@ MAKING CHANGES TO INCLHACK.DEF
 
     1.  Be positive for all header files that require the fix.
 
 
     1.  Be positive for all header files that require the fix.
 

-    It is desireable to:
+    It is desirable to:

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


@@ -227,11 +235,12 @@ MAKING CHANGES TO INCLHACK.DEF
             c_fix_arg = "#ifndef %1\n%0\n#endif";
             c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
 
             c_fix_arg = "#ifndef %1\n%0\n#endif";
             c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
 

-        This would wrap a traditional #define inside of a "#ifndef"/"#endif"
-        pair.  The second "c_fix_arg" may be omitted *IF* there is
-        a select clause and the first one matches the text you want
-        replaced.  You may delete text by supplying an empty string for
-        the format (the first "c_fix_arg").
+        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
 
        Note: In general, a format c_fix may be used in place of one
        sed expression.  However, it will need to be rewritten by


@@ -310,7 +319,7 @@ EXAMPLES OF FIXES:
 
     I would really recommend, however:
 
 
     I would really recommend, however:
 

-        cd ${top_builddir}/gcc/fixinc
+        cd ${top_builddir}/fixincludes

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