From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- fixincludes/README | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 331 insertions(+) create mode 100644 fixincludes/README (limited to 'fixincludes/README') diff --git a/fixincludes/README b/fixincludes/README new file mode 100644 index 000000000..07a3964a2 --- /dev/null +++ b/fixincludes/README @@ -0,0 +1,331 @@ + +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 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 +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 + + + +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 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, 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. + +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. 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 desirable 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 \n" + "#else\n" + "#include \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}/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 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. -- cgit v1.2.3