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