gcc/fixinc/README

   1
   2 FIXINCLUDES OPERATION
   3 =====================
   4
   5 See also:  http://autogen.SourceForge.net/fixincludes
   6
   7 The set of fixes required was distilled down to just the data required
   8 to specify what needed to happen for each fix.  Those data were edited
   9 into a file named gcc/fixinc/inclhack.def.  A program called
  10 AutoGen (http://autogen.SourceForge.net, ver 4.x) uses these definitions
  11 to instantiate several different templates (gcc/fixinc/*.tpl) that then
  12 produces a fixincludes replacement shell script (inclhack.sh), a
  13 replacement binary program (fixincl.x).
  14
  15 If there is no special purpose script, then mkfixinc.sh will try to
  16 compile, link and execute the fixincl program.  Otherwise, it will
  17 install and use the current fixinc.* for that system instead.
  18 Also, on certain platforms (viz. those that do not have functional
  19 bidirectional pipes), the fixincl program is split into two.
  20 This should only concern you on DOS and BeOS.
  21
  22 Regards,
  23         Bruce <bkorb@gnu.org>
  24
  25
  26
  27 GCC MAINTAINER INFORMATION
  28 ==========================
  29
  30 If you are having some problem with a system header that is either
  31 broken by the manufacturer, or is broken by the fixinclude process,
  32 then you will need to alter or add information to the include fix
  33 definitions file, ``inclhack.def''.  Please also send relevant
  34 information to gcc-bugs@gcc.gnu.org, gcc-patches@gcc.gnu.org and,
  35 please, to me:  bkorb@gnu.org.
  36
  37 Here are the rules for making fixes in the inclhack.def file:
  38
  39 1.  Every fix must have a "hackname" that is compatible with C syntax
  40     for variable names and is unique without regard to alphabetic case.
  41     Please keep them alphabetical by this name.  :-)
  42
  43 2.  If the problem is known to exist only in certain files,
  44     then name each such file with a "files = " entry.
  45
  46 3.  It is relatively expensive to fire off a process to fix a source
  47     file, therefore write apply tests to avoid unnecessary fix
  48     processes.  The preferred apply tests are "select", "bypass" and
  49     "c_test" because they are performed internally.  "test" sends
  50     a command to a server shell that actually fires off one or more
  51     processes to do the testing.  Avoid it, if you can, but it is
  52     still more efficient than a fix process.  Also available is
  53     "mach".  If the target machine matches any of the named
  54     globbing-style patterns, then the machine name test will pass.
  55     It is desired, however, to limit the use of this test.
  56
  57     These tests are required to:
  58
  59     1.  Be positive for all header files that require the fix.
  60
  61     It is desireable to:
  62
  63     2.  Be negative as often as possible whenever the fix is not
  64         required, avoiding the process overhead.
  65
  66     It is nice if:
  67
  68     3.  The expression is as simple as possible to both
  69         process and understand by people.  :-)
  70
  71         Please take advantage of the fact AutoGen will glue
  72         together string fragments.  It helps.  Also take note
  73         that double quote strings and single quote strings have
  74         different formation rules.  Double quote strings are a
  75         tiny superset of ANSI-C string syntax.  Single quote
  76         strings follow shell single quote string formation
  77         rules, except that the backslash is processed before
  78         '\\', '\'' and '#' characters (using C character syntax).
  79
  80     Examples of test specifications:
  81
  82       hackname = broken_assert_stdio;
  83       files    = assert.h;
  84       select   = stderr;
  85       bypass   = "include.*stdio.h";
  86
  87     The ``broken_assert_stdio'' fix will be applied only to a file
  88     named "assert.h" if it contains the string "stderr" _and_ it
  89     does _not_ contain the expression "include.*stdio.h".
  90
  91       hackname = no_double_slash;
  92       c_test   = "double_slash";
  93
  94     The ``no_double_slash'' fix will be applied if the
  95     ``double_slash_test()'' function says to.  See ``fixtests.c''
  96     for documentation on how to include new functions into that
  97     module.
  98
  99 4.  There are currently four methods of fixing a file:
 100
 101     1.  a series of sed expressions.  Each will be an individual
 102         "-e" argument to a single invocation of sed.
 103
 104     2.  a shell script.  These scripts are _required_ to read all
 105         of stdin in order to avoid pipe stalls.  They may choose to
 106         discard the input.
 107
 108     3.  Replacement text.  If the replacement is empty, then no
 109         fix is applied.  Otherwise, the replacement text is
 110         written to the output file and no further fixes are
 111         applied.  If you really want a no-op file, replace the
 112         file with a comment.
 113
 114         Replacement text "fixes" must be first in this file!!
 115
 116     4.  A C language subroutine method for both tests and fixes.
 117         See ``fixtests.c'' for instructions on writing C-language
 118         applicability tests and ``fixfixes.c'' for C-language fixing.
 119         These files also contain tables that describe the currently
 120         implemented fixes and tests.
 121
 122     If at all possible, you should try to use one of the C language
 123     fixes as it is far more efficient.  There are currently five
 124     such fixes, three of which are very special purpose:
 125
 126     i) char_macro_def - This function repairs the definition of an
 127         ioctl macro that presumes CPP macro substitution within
 128         pairs of single quote characters.
 129
 130     ii) char_macro_use - This function repairs the usage of ioctl
 131         macros that no longer can wrap an argument with single quotes.
 132
 133     iii) machine_name - This function will look at "#if", "#ifdef",
 134         "#ifndef" and "#elif" directive lines and replace the first
 135         occurrence of a non-reserved name that is traditionally
 136         pre-defined by the native compiler.
 137
 138     The next two are for general use:
 139
 140     iv) wrap - wraps the entire file with "#ifndef", "#define" and
 141         "#endif" self-exclusionary text.  It also, optionally, inserts
 142         a prolog after the "#define" and an epilog just before the
 143         "#endif".  You can use this for a fix as follows:
 144
 145             c_fix     = wrap;
 146             c_fix_arg = "/* prolog text */";
 147             c_fix_arg = "/* epilog text */";
 148
 149         If you want an epilog without a prolog, set the first "c_fix_arg"
 150         to the empty string.  Both or the second "c_fix_arg"s may be
 151         omitted and the file will still be wrapped.
 152
 153     v) format - Replaces text selected with a regular expression with
 154         a specialized formating string.  The formatting works as follows:
 155         The format text is copied to the output until a '%' character
 156         is found.  If the character after the '%' is another '%', then
 157         one '%' is output and processing continues.  If the following
 158         character is not a digit, then the '%' and that character are
 159         copied and processing continues.  Finally, if the '%' *is*
 160         followed by a digit, that digit is used as an index into the
 161         regmatch_t array to replace the two characters with the matched
 162         text.  i.e.: "%0" is replaced by the full matching text, "%1"
 163         is the first matching sub-expression, etc.
 164
 165         This is used as follows:
 166
 167             c_fix     = format;
 168             c_fix_arg = "#ifndef %1\n%0\n#endif";
 169             c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
 170
 171         This would wrap a traditional #define inside of a "#ifndef"/"#endif"
 172         pair.  The second "c_fix_arg" may be omitted *IF* there is
 173         a select clause and the first one matches the text you want
 174         replaced.  You may delete text by supplying an empty string for
 175         the format (the first "c_fix_arg").
 176
 177 EXAMPLES OF FIXES:
 178 ==================
 179
 180       hackname = AAA_ki_iface;
 181       replace; /* empty replacement -> no fixing the file */
 182
 183     When this ``fix'' is invoked, it will prevent any fixes
 184     from being applied.
 185
 186     ------------------
 187
 188       hackname = AAB_svr4_no_varargs;
 189       replace  = "/* This file was generated by fixincludes.  */\n"
 190                  "#ifndef _SYS_VARARGS_H\n"
 191                  "#define _SYS_VARARGS_H\n\n"
 192
 193                  "#ifdef __STDC__\n"
 194                  "#include <stdarg.h>\n"
 195                  "#else\n"
 196                  "#include <varargs.h>\n"
 197                  "#endif\n\n"
 198
 199                  "#endif  /* _SYS_VARARGS_H */\n";
 200
 201     When this ``fix'' is invoked, the replacement text will be
 202     emitted into the replacement include file.  No further fixes
 203     will be applied.
 204
 205     ------------------
 206
 207         hackname  = hpux11_fabsf;
 208         files     = math.h;
 209         select    = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
 210         bypass    = "__cplusplus";
 211
 212         c_fix     = format;
 213         c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
 214
 215         test_text =
 216         "#  define fabsf(x) ((float)fabs((double)(float)(x)))\n";
 217
 218     This fix will ensure that the #define for fabs is wrapped
 219     with C++ protection, providing the header is not already
 220     C++ aware.
 221
 222     ------------------
 223
 224 5.  Testing fixes.
 225
 226     The brute force method is, of course, to configure and build
 227     GCC.  But you can also:
 228
 229         cd ${top_builddir}/gcc
 230         rm -rf fixinc.sh include/ stmp-fixinc
 231         make stmp-fixinc
 232
 233     I would really recommend, however:
 234
 235         cd ${top_builddir}/gcc/fixinc
 236         make check
 237
 238     To do this, you *must* have autogen installed on your system.
 239     The "check" step will proceed to construct a shell script that
 240     will exercize all the fixes, using the sample test_text
 241     provided with each fix.  Once done, the changes made will
 242     be compared against the changes saved in the source directory.
 243     If you are changing the tests or fixes, the change will likely
 244     be highlighted.