OSDN Git Service

Daily bump.
[pf3gnuchains/gcc-fork.git] / fixincludes / README
index 8b8cc98..07a3964 100644 (file)
@@ -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
-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
@@ -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.
 
-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.
 
-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.
@@ -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.  :-)
 
-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
-    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.
-               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.
 
-    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
-               "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
@@ -106,7 +114,7 @@ MAKING CHANGES TO INCLHACK.DEF
 
     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.
@@ -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_]*).*";
 
-        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
@@ -310,7 +319,7 @@ EXAMPLES OF FIXES:
 
     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.