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