OSDN Git Service

Daily bump.
[pf3gnuchains/gcc-fork.git] / fixincludes / README
index 29c4edb..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,25 +69,52 @@ 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.  "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.
+    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 desireable to:
+    It is desirable to:
 
     2.  Be negative as often as possible whenever the fix is not
         required, avoiding the process overhead.
@@ -106,6 +133,10 @@ MAKING CHANGES TO INCLHACK.DEF
         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;
@@ -204,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
@@ -287,12 +319,12 @@ 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.
     The "check" step will proceed to construct a shell script that
-    will exercize all the fixes, using the sample test_text
+    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