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 fixincludes/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 fixincludes 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, synchronize 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, then
  73     identify the files with "files = " entries.  If you use fnmatch(3C)
  74     wild card characters in a "files" entry, be certain that the first
  75     "files" entry has no such character.  Otherwise, the "make check"
  76     machinery will attempt to create files with those characters in the
  77     name.  That is inconvenient.
  78
  79 3.  It is relatively expensive to fire off a process to fix a source
  80     file, therefore write apply tests to avoid unnecessary fix
  81     processes.  The preferred apply tests are "select", "bypass", "mach"
  82     and "c-test" because they are performed internally:
  83
  84     * select - Run a regex on the contents of the file being considered.
  85                All such regex-es must match.  Matching is done with
  86                extended regular expressions.
  87
  88     * bypass - Run a regex on the contents of the file being considered.
  89                No such regex may match.
  90
  91     * c_test - call a function in fixtests.c.  See that file.
  92
  93     * files  - the "fnmatch" pattern of the file(s) to examine for
  94                the issue.  There may be several copies of this attribute.
  95                If the header lives in a /usr/include subdirectory, be
  96                sure to include that subdirectory in the name. e.g. net/if.h
  97
  98     * mach   - Match the output of config.guess against a series of fnmatch
  99                patterns.  It must match at least one of the patterns, unless
 100                "not-machine" has also been specified.  In that case, the
 101                config.guess output must not match any of the patterns.
 102
 103     The next test is relatively slow because it must be handled in a
 104     separate shell process.  Some platforms do not support server shells,
 105     so the whole process is even slower and more cumbersome there.
 106
 107     * test   - These should be arguments to the program, "/bin/test".
 108                You may perform multiple commands, if you enclose them
 109                in backquotes and echo out valid test arguments.  For
 110                example, you might echo out '0 -eq 1' if you want a false
 111                result, or '0 -eq 0' for a true result.
 112
 113     These tests are required to:
 114
 115     1.  Be positive for all header files that require the fix.
 116
 117     It is desirable to:
 118
 119     2.  Be negative as often as possible whenever the fix is not
 120         required, avoiding the process overhead.
 121
 122     It is nice if:
 123
 124     3.  The expression is as simple as possible to both
 125         process and understand by people.  :-)
 126
 127         Please take advantage of the fact AutoGen will glue
 128         together string fragments.  It helps.  Also take note
 129         that double quote strings and single quote strings have
 130         different formation rules.  Double quote strings are a
 131         tiny superset of ANSI-C string syntax.  Single quote
 132         strings follow shell single quote string formation
 133         rules, except that the backslash is processed before
 134         '\\', '\'' and '#' characters (using C character syntax).
 135
 136     Each test must pass or the fix is not applied.  For example,
 137     all "select" expressions must be found and not one "bypass"
 138     selection may be found.
 139
 140     Examples of test specifications:
 141
 142       hackname = broken_assert_stdio;
 143       files    = assert.h;
 144       select   = stderr;
 145       bypass   = "include.*stdio.h";
 146
 147     The ``broken_assert_stdio'' fix will be applied only to a file
 148     named "assert.h" if it contains the string "stderr" _and_ it
 149     does _not_ contain the expression "include.*stdio.h".
 150
 151       hackname = no_double_slash;
 152       c_test   = "double_slash";
 153
 154     The ``no_double_slash'' fix will be applied if the
 155     ``double_slash_test()'' function says to.  See ``fixtests.c''
 156     for documentation on how to include new functions into that
 157     module.
 158
 159 4.  There are currently four methods of fixing a file:
 160
 161     1.  a series of sed expressions.  Each will be an individual
 162         "-e" argument to a single invocation of sed.
 163
 164     2.  a shell script.  These scripts are _required_ to read all
 165         of stdin in order to avoid pipe stalls.  They may choose to
 166         discard the input.
 167
 168     3.  Replacement text.  If the replacement is empty, then no
 169         fix is applied.  Otherwise, the replacement text is
 170         written to the output file and no further fixes are
 171         applied.  If you really want a no-op file, replace the
 172         file with a comment.
 173
 174         Replacement text "fixes" must be first in this file!!
 175
 176     4.  A C language subroutine method for both tests and fixes.
 177         See ``fixtests.c'' for instructions on writing C-language
 178         applicability tests and ``fixfixes.c'' for C-language fixing.
 179         These files also contain tables that describe the currently
 180         implemented fixes and tests.
 181
 182     If at all possible, you should try to use one of the C language
 183     fixes as it is far more efficient.  There are currently five
 184     such fixes, three of which are very special purpose:
 185
 186     i) char_macro_def - This function repairs the definition of an
 187         ioctl macro that presumes CPP macro substitution within
 188         pairs of single quote characters.
 189
 190     ii) char_macro_use - This function repairs the usage of ioctl
 191         macros that no longer can wrap an argument with single quotes.
 192
 193     iii) machine_name - This function will look at "#if", "#ifdef",
 194         "#ifndef" and "#elif" directive lines and replace the first
 195         occurrence of a non-reserved name that is traditionally
 196         pre-defined by the native compiler.
 197
 198     The next two are for general use:
 199
 200     iv) wrap - wraps the entire file with "#ifndef", "#define" and
 201         "#endif" self-exclusionary text.  It also, optionally, inserts
 202         a prolog after the "#define" and an epilog just before the
 203         "#endif".  You can use this for a fix as follows:
 204
 205             c_fix     = wrap;
 206             c_fix_arg = "/* prolog text */";
 207             c_fix_arg = "/* epilog text */";
 208
 209         If you want an epilog without a prolog, set the first "c_fix_arg"
 210         to the empty string.  Both or the second "c_fix_arg"s may be
 211         omitted and the file will still be wrapped.
 212
 213         THERE IS A SPECIAL EXCEPTION TO THIS, HOWEVER:
 214
 215         If the regular expression '#if.*__need' is found, then it is
 216         assumed that the file needs to be read and interpreted more
 217         than once.  However, the prolog and epilog text (if any) will
 218         be inserted.
 219
 220     v) format - Replaces text selected with a regular expression with
 221         a specialized formating string.  The formatting works as follows:
 222         The format text is copied to the output until a '%' character
 223         is found.  If the character after the '%' is another '%', then
 224         one '%' is output and processing continues.  If the following
 225         character is not a digit, then the '%' and that character are
 226         copied and processing continues.  Finally, if the '%' *is*
 227         followed by a digit, that digit is used as an index into the
 228         regmatch_t array to replace the two characters with the matched
 229         text.  i.e.: "%0" is replaced by the full matching text, "%1"
 230         is the first matching sub-expression, etc.
 231
 232         This is used as follows:
 233
 234             c_fix     = format;
 235             c_fix_arg = "#ifndef %1\n%0\n#endif";
 236             c_fix_arg = "#define[ \t]+([A-Z][A-Z0-9a-z_]*).*";
 237
 238         This would wrap a one line #define inside of a "#ifndef"/"#endif"
 239         pair.  The second "c_fix_arg" may be omitted *IF* there is at least
 240         one select clause and the first one identifies the text you wish to
 241         reformat.  It will then be used as the second "c_fix_arg".  You may
 242         delete the selected text by supplying an empty string for the
 243         replacement format (the first "c_fix_arg").
 244
 245         Note: In general, a format c_fix may be used in place of one
 246         sed expression.  However, it will need to be rewritten by
 247         hand.  For example:
 248
 249         sed = 's@^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$'
 250                '@& || __GNUC__ >= 3@';
 251
 252         may be rewritten using a format c_fix as:
 253
 254         c_fix     = format;
 255         c_fix_arg = '%0 || __GNUC__ >= 3';
 256         c_fix_arg = '^#if __GNUC__ == 2 && __GNUC_MINOR__ >= 7$';
 257
 258         Multiple sed substitution expressions probably ought to remain sed
 259         expressions in order to maintain clarity.  Also note that if the
 260         second sed expression is the same as the first select expression,
 261         then you may omit the second c_fix_arg.  The select expression will
 262         be picked up and used in its absence.
 263
 264 EXAMPLES OF FIXES:
 265 ==================
 266
 267       hackname = AAA_ki_iface;
 268       replace; /* empty replacement -> no fixing the file */
 269
 270     When this ``fix'' is invoked, it will prevent any fixes
 271     from being applied.
 272
 273     ------------------
 274
 275       hackname = AAB_svr4_no_varargs;
 276       replace  = "/* This file was generated by fixincludes.  */\n"
 277                  "#ifndef _SYS_VARARGS_H\n"
 278                  "#define _SYS_VARARGS_H\n\n"
 279
 280                  "#ifdef __STDC__\n"
 281                  "#include <stdarg.h>\n"
 282                  "#else\n"
 283                  "#include <varargs.h>\n"
 284                  "#endif\n\n"
 285
 286                  "#endif  /* _SYS_VARARGS_H */\n";
 287
 288     When this ``fix'' is invoked, the replacement text will be
 289     emitted into the replacement include file.  No further fixes
 290     will be applied.
 291
 292     ------------------
 293
 294         hackname  = hpux11_fabsf;
 295         files     = math.h;
 296         select    = "^[ \t]*#[ \t]*define[ \t]+fabsf\\(.*";
 297         bypass    = "__cplusplus";
 298
 299         c_fix     = format;
 300         c_fix_arg = "#ifndef __cplusplus\n%0\n#endif";
 301
 302         test_text =
 303         "#  define fabsf(x) ((float)fabs((double)(float)(x)))\n";
 304
 305     This fix will ensure that the #define for fabs is wrapped
 306     with C++ protection, providing the header is not already
 307     C++ aware.
 308
 309     ------------------
 310
 311 5.  Testing fixes.
 312
 313     The brute force method is, of course, to configure and build
 314     GCC.  But you can also:
 315
 316         cd ${top_builddir}/gcc
 317         rm -rf fixinc.sh include/ stmp-fixinc
 318         make stmp-fixinc
 319
 320     I would really recommend, however:
 321
 322         cd ${top_builddir}/fixincludes
 323         make check
 324
 325     To do this, you *must* have autogen installed on your system.
 326     The "check" step will proceed to construct a shell script that
 327     will exercise all the fixes, using the sample test_text
 328     provided with each fix.  Once done, the changes made will
 329     be compared against the changes saved in the source directory.
 330     If you are changing the tests or fixes, the change will likely
 331     be highlighted.