FIXINCLUDES OPERATION
=====================
See also: http://autogen.linuxbox.com/fixincludes
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.linuxbox.com) uses these definitions to
instantiate several different templates (gcc/fixinc/*.tpl) that then
produces a fixincludes replacement shell script (inclhack.sh), a
replacement binary program (fixincl.x) and a script to drive the
binary fixincl.sh).
If there is no special purpose script, then mkfixinc.sh will try to
compile, link and test execute the binary version. If it cannot be
successfully built, the shell version will be used instead. If
mkfixinc.sh determines that your system needs machine-specific fixes
that have not yet been applied to inclhack.def, it will install and
use the current fixinc.* for that system instead.
Regards,
Bruce <autogen@linuxbox.com>
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.
Here are the rules for making fixes in the inclhack.def file:
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 name each such file with a "files = " entry.
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.
These tests are required to:
1. Be positive for all header files that require the fix.
It is desireable 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 uderstand 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).
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.
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 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").
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}/gcc/fixinc
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
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.
