-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
==========================
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.
+ Do *NOT* specify test text for "wrap" or "replacement" fixes.
+ There is no real possibility that these fixes will fail.
+ If they do, you will surely know straight away.
+
+ NOTE: "test_text" is interpreted by the shell as it gets
+ copied into the test header. THEREFORE you must quote
+ dollar sign characters and back quotes -- unless you mean
+ for them to be interpreted by the shell.
+
+ e.g. the math_huge_val_from_dbl_max test_text needs to
+ put text into both float.h and math.h, so it includes a
+ back-quoted script to add text to float.h.
-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.
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"
+ "sum", 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.
+
+ * sum - Select a specific version of a file that has a matching
+ check sum. The BSD version of checksum ["sum(1BSD)"]
+ is used. Each "sum" entry should contain exactly three
+ space separated tokens: the sum, some number and the
+ basename of the file. The "some number" is ignored.
+ If there are multiple "sum" entries, only one needs to
+ match in order to pass. For example:
+
+ sum = '1234 3 foobar.h';
+
+ specifies that the "foobar.h" header in any directory
+ will match if it has the checksum 1234.
+
+ * 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.
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;
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.
+ "-e" argument to a single invocation of sed. Unless you
+ need to use multiple or complex sed expressions, please
+ use the "replacement text" method instead.
2. a shell script. These scripts are _required_ to read all
of stdin in order to avoid pipe stalls. They may choose to
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
GCC. But you can also:
cd ${top_builddir}/gcc
- rm -rf fixinc.sh include/ stmp-fixinc
+ rm -rf include-fixed/ stmp-fixinc
make stmp-fixinc
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.
projects / gcc.git / blobdiff