summaryrefslogtreecommitdiff
path: root/fixincludes/README
diff options
context:
space:
mode:
Diffstat (limited to 'fixincludes/README')
-rw-r--r--fixincludes/README331
1 files changed, 0 insertions, 331 deletions
diff --git a/fixincludes/README b/fixincludes/README
deleted file mode 100644
index 07a3964a2..000000000
--- a/fixincludes/README
+++ /dev/null
@@ -1,331 +0,0 @@
-
-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 <bkorb@gnu.org>
-
-
-
-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 <stdarg.h>\n"
- "#else\n"
- "#include <varargs.h>\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.