fixincludes/README

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