|
|
FIXINCLUDES OPERATION
|
FIXINCLUDES OPERATION
|
=====================
|
=====================
|
|
|
See also: http://autogen.SourceForge.net/fixinc.html
|
See also: http://autogen.SourceForge.net/fixinc.html
|
|
|
The set of fixes required was distilled down to just the data required
|
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
|
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 gcc/fixinc/inclhack.def. A program called AutoGen
|
(http://autogen.SourceForge.net) uses these definitions to instantiate
|
(http://autogen.SourceForge.net) uses these definitions to instantiate
|
several different templates that then produces code for a fixinclude
|
several different templates that then produces code for a fixinclude
|
program (fixincl.x) and a shell script to test its functioning. On
|
program (fixincl.x) and a shell script to test its functioning. On
|
certain platforms (viz. those that do not have functional bidirectional
|
certain platforms (viz. those that do not have functional bidirectional
|
pipes), the fixincl program is split into two. This should only concern
|
pipes), the fixincl program is split into two. This should only concern
|
you on DOS and BeOS.
|
you on DOS and BeOS.
|
|
|
Regards,
|
Regards,
|
Bruce
|
Bruce
|
|
|
|
|
|
|
GCC MAINTAINER INFORMATION
|
GCC MAINTAINER INFORMATION
|
==========================
|
==========================
|
|
|
If you are having some problem with a system header that is either
|
If you are having some problem with a system header that is either
|
broken by the manufacturer, or is broken by the fixinclude process,
|
broken by the manufacturer, or is broken by the fixinclude process,
|
then you will need to alter or add information to the include fix
|
then you will need to alter or add information to the include fix
|
definitions file, ``inclhack.def''. Please also send relevant
|
definitions file, ``inclhack.def''. Please also send relevant
|
information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and,
|
information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and,
|
please, to me: bkorb@gnu.org.
|
please, to me: bkorb@gnu.org.
|
|
|
To make your fix, you will need to do several things:
|
To make your fix, you will need to do several things:
|
|
|
1. Obtain access to the AutoGen program on some platform. It does
|
1. Obtain access to the AutoGen program on some platform. It does
|
not have to be your build platform, but it is more convenient.
|
not have to be your build platform, but it is more convenient.
|
|
|
2. Edit "inclhack.def" to reflect the changes you need to make.
|
2. Edit "inclhack.def" to reflect the changes you need to make.
|
See below for information on how to make those changes.
|
See below for information on how to make those changes.
|
|
|
3. Run the "genfixes" shell script to produce a new copy of
|
3. Run the "genfixes" shell script to produce a new copy of
|
the "fixincl.x" file.
|
the "fixincl.x" file.
|
|
|
4. Rebuild the compiler and check the header causing the issue.
|
4. Rebuild the compiler and check the header causing the issue.
|
Make sure it is now properly handled. Add tests to the
|
Make sure it is now properly handled. Add tests to the
|
"test_text" entry(ies) that validate your fix. This will
|
"test_text" entry(ies) that validate your fix. This will
|
help ensure that future fixes won't negate your work.
|
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 fixinc build directory and type, "make check".
|
You are guaranteed to have issues printed out as a result.
|
You are guaranteed to have issues printed out as a result.
|
Look at the diffs produced. Make sure you have not clobbered
|
Look at the diffs produced. Make sure you have not clobbered
|
the proper functioning of a different fix. Make sure your
|
the proper functioning of a different fix. Make sure your
|
fix is properly tested and it does what it is supposed to do.
|
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, syncronize the
|
$(srcdir)/tests/base directory with the $(builddir)/tests/res
|
$(srcdir)/tests/base directory with the $(builddir)/tests/res
|
directory. The output of "make check" will be some diffs that
|
directory. The output of "make check" will be some diffs that
|
should give you some hints about what to do.
|
should give you some hints about what to do.
|
|
|
7. Rerun "make check" and verify that there are no issues left.
|
7. Rerun "make check" and verify that there are no issues left.
|
|
|
|
|
MAKING CHANGES TO INCLHACK.DEF
|
MAKING CHANGES TO INCLHACK.DEF
|
==============================
|
==============================
|
|
|
0. If you are not the fixincludes maintainer, please send that
|
0. If you are not the fixincludes maintainer, please send that
|
person email about any changes you may want to make. Thanks!
|
person email about any changes you may want to make. Thanks!
|
|
|
1. Every fix must have a "hackname" that is compatible with C syntax
|
1. Every fix must have a "hackname" that is compatible with C syntax
|
for variable names and is unique without regard to alphabetic case.
|
for variable names and is unique without regard to alphabetic case.
|
Please keep them alphabetical by this name. :-)
|
Please keep them alphabetical by this name. :-)
|
|
|
2. If the problem is known to exist only in certain files,
|
2. If the problem is known to exist only in certain files,
|
then name each such file with a "files = " entry.
|
then name each such file with a "files = " entry.
|
|
|
3. It is relatively expensive to fire off a process to fix a source
|
3. It is relatively expensive to fire off a process to fix a source
|
file, therefore write apply tests to avoid unnecessary fix
|
file, therefore write apply tests to avoid unnecessary fix
|
processes. The preferred apply tests are "select", "bypass" and
|
processes. The preferred apply tests are "select", "bypass" and
|
"c_test" because they are performed internally. The available
|
"c_test" because they are performed internally. The available
|
tests are:
|
tests are:
|
|
|
* select - Run a regex on the contents of the file being considered.
|
* select - Run a regex on the contents of the file being considered.
|
All such regex-es must match.
|
All such regex-es must match.
|
|
|
* bypass - Run a regex on the contents of the file being considered.
|
* bypass - Run a regex on the contents of the file being considered.
|
No such regex may match.
|
No such regex may match.
|
|
|
* c_test - call a function in fixtests.c. See that file.
|
* c_test - call a function in fixtests.c. See that file.
|
|
|
The next two tests are relatively slow because they must be handled
|
The next two tests are relatively slow because they must be handled
|
in a separate shell process. Some platforms do not support server
|
in a separate shell process. Some platforms do not support server
|
shells, so the whole process is even slower and more cumbersome there.
|
shells, so the whole process is even slower and more cumbersome there.
|
|
|
* mach - Match the output of config.conf against a series of globbing
|
* mach - Match the output of config.conf against a series of globbing
|
patterns. It must match at least one of the patterns, unless
|
patterns. It must match at least one of the patterns, unless
|
"not-machine" has also been specified. If that has been
|
"not-machine" has also been specified. If that has been
|
specified, then the config.conf output may not match any of
|
specified, then the config.conf output may not match any of
|
the patterns.
|
the patterns.
|
|
|
* test - These should be arguments to the program, "/bin/test".
|
* test - These should be arguments to the program, "/bin/test".
|
You may perform multiple commands, if you enclose them
|
You may perform multiple commands, if you enclose them
|
in backquotes and echo out valid test arguments. For
|
in backquotes and echo out valid test arguments. For
|
example, you might echo out '0 -eq 1' if you want a false
|
example, you might echo out '0 -eq 1' if you want a false
|
result, or '0 -eq 0' for a true result.
|
result, or '0 -eq 0' for a true result.
|
|
|
These tests are required to:
|
These tests are required to:
|
|
|
1. Be positive for all header files that require the fix.
|
1. Be positive for all header files that require the fix.
|
|
|
It is desireable to:
|
It is desireable to:
|
|
|
2. Be negative as often as possible whenever the fix is not
|
2. Be negative as often as possible whenever the fix is not
|
required, avoiding the process overhead.
|
required, avoiding the process overhead.
|
|
|
It is nice if:
|
It is nice if:
|
|
|
3. The expression is as simple as possible to both
|
3. The expression is as simple as possible to both
|
process and understand by people. :-)
|
process and understand by people. :-)
|
|
|
Please take advantage of the fact AutoGen will glue
|
Please take advantage of the fact AutoGen will glue
|
together string fragments. It helps. Also take note
|
together string fragments. It helps. Also take note
|
that double quote strings and single quote strings have
|
that double quote strings and single quote strings have
|
different formation rules. Double quote strings are a
|
different formation rules. Double quote strings are a
|
tiny superset of ANSI-C string syntax. Single quote
|
tiny superset of ANSI-C string syntax. Single quote
|
strings follow shell single quote string formation
|
strings follow shell single quote string formation
|
rules, except that the backslash is processed before
|
rules, except that the backslash is processed before
|
'\\', '\'' and '#' characters (using C character syntax).
|
'\\', '\'' and '#' characters (using C character syntax).
|
|
|
Each test must pass or the fix is not applied. For example,
|
Each test must pass or the fix is not applied. For example,
|
all "select" expressions must be found and not one "bypass"
|
all "select" expressions must be found and not one "bypass"
|
selection may be found.
|
selection may be found.
|
|
|
Examples of test specifications:
|
Examples of test specifications:
|
|
|
hackname = broken_assert_stdio;
|
hackname = broken_assert_stdio;
|
files = assert.h;
|
files = assert.h;
|
select = stderr;
|
select = stderr;
|
bypass = "include.*stdio.h";
|
bypass = "include.*stdio.h";
|
|
|
The ``broken_assert_stdio'' fix will be applied only to a file
|
The ``broken_assert_stdio'' fix will be applied only to a file
|
named "assert.h" if it contains the string "stderr" _and_ it
|
named "assert.h" if it contains the string "stderr" _and_ it
|
does _not_ contain the expression "include.*stdio.h".
|
does _not_ contain the expression "include.*stdio.h".
|
|
|
hackname = no_double_slash;
|
hackname = no_double_slash;
|
c_test = "double_slash";
|
c_test = "double_slash";
|
|
|
The ``no_double_slash'' fix will be applied if the
|
The ``no_double_slash'' fix will be applied if the
|
``double_slash_test()'' function says to. See ``fixtests.c''
|
``double_slash_test()'' function says to. See ``fixtests.c''
|
for documentation on how to include new functions into that
|
for documentation on how to include new functions into that
|
module.
|
module.
|
|
|
4. There are currently four methods of fixing a file:
|
4. There are currently four methods of fixing a file:
|
|
|
1. a series of sed expressions. Each will be an individual
|
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.
|
|
|
2. a shell script. These scripts are _required_ to read all
|
2. a shell script. These scripts are _required_ to read all
|
of stdin in order to avoid pipe stalls. They may choose to
|
of stdin in order to avoid pipe stalls. They may choose to
|
discard the input.
|
discard the input.
|
|
|
3. Replacement text. If the replacement is empty, then no
|
3. Replacement text. If the replacement is empty, then no
|
fix is applied. Otherwise, the replacement text is
|
fix is applied. Otherwise, the replacement text is
|
written to the output file and no further fixes are
|
written to the output file and no further fixes are
|
applied. If you really want a no-op file, replace the
|
applied. If you really want a no-op file, replace the
|
file with a comment.
|
file with a comment.
|
|
|
Replacement text "fixes" must be first in this file!!
|
Replacement text "fixes" must be first in this file!!
|
|
|
4. A C language subroutine method for both tests and fixes.
|
4. A C language subroutine method for both tests and fixes.
|
See ``fixtests.c'' for instructions on writing C-language
|
See ``fixtests.c'' for instructions on writing C-language
|
applicability tests and ``fixfixes.c'' for C-language fixing.
|
applicability tests and ``fixfixes.c'' for C-language fixing.
|
These files also contain tables that describe the currently
|
These files also contain tables that describe the currently
|
implemented fixes and tests.
|
implemented fixes and tests.
|
|
|
If at all possible, you should try to use one of the C language
|
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
|
fixes as it is far more efficient. There are currently five
|
such fixes, three of which are very special purpose:
|
such fixes, three of which are very special purpose:
|
|
|
i) char_macro_def - This function repairs the definition of an
|
i) char_macro_def - This function repairs the definition of an
|
ioctl macro that presumes CPP macro substitution within
|
ioctl macro that presumes CPP macro substitution within
|
pairs of single quote characters.
|
pairs of single quote characters.
|
|
|
ii) char_macro_use - This function repairs the usage of ioctl
|
ii) char_macro_use - This function repairs the usage of ioctl
|
macros that no longer can wrap an argument with single quotes.
|
macros that no longer can wrap an argument with single quotes.
|
|
|
iii) machine_name - This function will look at "#if", "#ifdef",
|
iii) machine_name - This function will look at "#if", "#ifdef",
|
"#ifndef" and "#elif" directive lines and replace the first
|
"#ifndef" and "#elif" directive lines and replace the first
|
occurrence of a non-reserved name that is traditionally
|
occurrence of a non-reserved name that is traditionally
|
pre-defined by the native compiler.
|
pre-defined by the native compiler.
|
|
|
The next two are for general use:
|
The next two are for general use:
|
|
|
iv) wrap - wraps the entire file with "#ifndef", "#define" and
|
iv) wrap - wraps the entire file with "#ifndef", "#define" and
|
"#endif" self-exclusionary text. It also, optionally, inserts
|
"#endif" self-exclusionary text. It also, optionally, inserts
|
a prolog after the "#define" and an epilog just before the
|
a prolog after the "#define" and an epilog just before the
|
"#endif". You can use this for a fix as follows:
|
"#endif". You can use this for a fix as follows:
|
|
|
c_fix = wrap;
|
c_fix = wrap;
|
c_fix_arg = "/* prolog text */";
|
c_fix_arg = "/* prolog text */";
|
c_fix_arg = "/* epilog text */";
|
c_fix_arg = "/* epilog text */";
|
|
|
If you want an epilog without a prolog, set the first "c_fix_arg"
|
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
|
to the empty string. Both or the second "c_fix_arg"s may be
|
omitted and the file will still be wrapped.
|
omitted and the file will still be wrapped.
|
|
|
THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
|
THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
|
|
|
If the regular expression '#if.*__need' is found, then it is
|
If the regular expression '#if.*__need' is found, then it is
|
assumed that the file needs to be read and interpreted more
|
assumed that the file needs to be read and interpreted more
|
than once. However, the prolog and epilog text (if any) will
|
than once. However, the prolog and epilog text (if any) will
|
be inserted.
|
be inserted.
|
|
|
v) format - Replaces text selected with a regular expression with
|
v) format - Replaces text selected with a regular expression with
|
a specialized formating string. The formatting works as follows:
|
a specialized formating string. The formatting works as follows:
|
The format text is copied to the output until a '%' character
|
The format text is copied to the output until a '%' character
|
is found. If the character after the '%' is another '%', then
|
is found. If the character after the '%' is another '%', then
|
one '%' is output and processing continues. If the following
|
one '%' is output and processing continues. If the following
|
character is not a digit, then the '%' and that character are
|
character is not a digit, then the '%' and that character are
|
copied and processing continues. Finally, if the '%' *is*
|
copied and processing continues. Finally, if the '%' *is*
|
followed by a digit, that digit is used as an index into the
|
followed by a digit, that digit is used as an index into the
|
regmatch_t array to replace the two characters with the matched
|
regmatch_t array to replace the two characters with the matched
|
text. i.e.: "%0" is replaced by the full matching text, "%1"
|
text. i.e.: "%0" is replaced by the full matching text, "%1"
|
is the first matching sub-expression, etc.
|
is the first matching sub-expression, etc.
|
|
|
This is used as follows:
|
This is used as follows:
|
|
|
c_fix = format;
|
c_fix = format;
|
c_fix_arg = "#ifndef %1\n%0\n#endif";
|
c_fix_arg = "#ifndef %1\n%0\n#endif";
|
c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
|
c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
|
|
|
This would wrap a traditional #define inside of a "#ifndef"/"#endif"
|
This would wrap a traditional #define inside of a "#ifndef"/"#endif"
|
pair. The second "c_fix_arg" may be omitted *IF* there is
|
pair. The second "c_fix_arg" may be omitted *IF* there is
|
a select clause and the first one matches the text you want
|
a select clause and the first one matches the text you want
|
replaced. You may delete text by supplying an empty string for
|
replaced. You may delete text by supplying an empty string for
|
the format (the first "c_fix_arg").
|
the format (the first "c_fix_arg").
|
|
|
Note: In general, a format c_fix may be used in place of one
|
Note: In general, a format c_fix may be used in place of one
|
sed expression. However, it will need to be rewritten by
|
sed expression. However, it will need to be rewritten by
|
hand. For example:
|
hand. For example:
|
|
|
sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
|
sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
|
'@& || __GNUC__ >= 3@';
|
'@& || __GNUC__ >= 3@';
|
|
|
may be rewritten using a format c_fix as:
|
may be rewritten using a format c_fix as:
|
|
|
c_fix = format;
|
c_fix = format;
|
c_fix_arg = '%0 || __GNUC__ >= 3';
|
c_fix_arg = '%0 || __GNUC__ >= 3';
|
c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
|
c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
|
|
|
Multiple sed substitution expressions probably ought to remain sed
|
Multiple sed substitution expressions probably ought to remain sed
|
expressions in order to maintain clarity. Also note that if the
|
expressions in order to maintain clarity. Also note that if the
|
second sed expression is the same as the first select expression,
|
second sed expression is the same as the first select expression,
|
then you may omit the second c_fix_arg. The select expression will
|
then you may omit the second c_fix_arg. The select expression will
|
be picked up and used in its absence.
|
be picked up and used in its absence.
|
|
|
EXAMPLES OF FIXES:
|
EXAMPLES OF FIXES:
|
==================
|
==================
|
|
|
hackname = AAA_ki_iface;
|
hackname = AAA_ki_iface;
|
replace; /* empty replacement -> no fixing the file */
|
replace; /* empty replacement -> no fixing the file */
|
|
|
When this ``fix'' is invoked, it will prevent any fixes
|
When this ``fix'' is invoked, it will prevent any fixes
|
from being applied.
|
from being applied.
|
|
|
------------------
|
------------------
|
|
|
hackname = AAB_svr4_no_varargs;
|
hackname = AAB_svr4_no_varargs;
|
replace = "/* This file was generated by fixincludes. */\n"
|
replace = "/* This file was generated by fixincludes. */\n"
|
"#ifndef _SYS_VARARGS_H\n"
|
"#ifndef _SYS_VARARGS_H\n"
|
"#define _SYS_VARARGS_H\n\n"
|
"#define _SYS_VARARGS_H\n\n"
|
|
|
"#ifdef __STDC__\n"
|
"#ifdef __STDC__\n"
|
"#include \n"
|
"#include \n"
|
"#else\n"
|
"#else\n"
|
"#include \n"
|
"#include \n"
|
"#endif\n\n"
|
"#endif\n\n"
|
|
|
"#endif /* _SYS_VARARGS_H */\n";
|
"#endif /* _SYS_VARARGS_H */\n";
|
|
|
When this ``fix'' is invoked, the replacement text will be
|
When this ``fix'' is invoked, the replacement text will be
|
emitted into the replacement include file. No further fixes
|
emitted into the replacement include file. No further fixes
|
will be applied.
|
will be applied.
|
|
|
------------------
|
------------------
|
|
|
hackname = hpux11_fabsf;
|
hackname = hpux11_fabsf;
|
files = math.h;
|
files = math.h;
|
select = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
|
select = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
|
bypass = "__cplusplus";
|
bypass = "__cplusplus";
|
|
|
c_fix = format;
|
c_fix = format;
|
c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
|
c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
|
|
|
test_text =
|
test_text =
|
"# define fabsf(x) ((float)fabs((double)(float)(x)))\n";
|
"# define fabsf(x) ((float)fabs((double)(float)(x)))\n";
|
|
|
This fix will ensure that the #define for fabs is wrapped
|
This fix will ensure that the #define for fabs is wrapped
|
with C++ protection, providing the header is not already
|
with C++ protection, providing the header is not already
|
C++ aware.
|
C++ aware.
|
|
|
------------------
|
------------------
|
|
|
5. Testing fixes.
|
5. Testing fixes.
|
|
|
The brute force method is, of course, to configure and build
|
The brute force method is, of course, to configure and build
|
GCC. But you can also:
|
GCC. But you can also:
|
|
|
cd ${top_builddir}/gcc
|
cd ${top_builddir}/gcc
|
rm -rf fixinc.sh include/ stmp-fixinc
|
rm -rf fixinc.sh include/ stmp-fixinc
|
make stmp-fixinc
|
make stmp-fixinc
|
|
|
I would really recommend, however:
|
I would really recommend, however:
|
|
|
cd ${top_builddir}/gcc/fixinc
|
cd ${top_builddir}/gcc/fixinc
|
make check
|
make check
|
|
|
To do this, you *must* have autogen installed on your system.
|
To do this, you *must* have autogen installed on your system.
|
The "check" step will proceed to construct a shell script that
|
The "check" step will proceed to construct a shell script that
|
will exercise 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
|
provided with each fix. Once done, the changes made will
|
be compared against the changes saved in the source directory.
|
be compared against the changes saved in the source directory.
|
If you are changing the tests or fixes, the change will likely
|
If you are changing the tests or fixes, the change will likely
|
be highlighted.
|
be highlighted.
|
|
|
