gcc/fixinc/README

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