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:  autogen@linuxbox.com.
  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 uderstand 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.  A C language subroutine method for both tests and fixes.
 110         See ``fixtests.c'' for instructions on writing C-language
 111         applicability tests and ``fixfixes.c'' for C-language fixing.
 112
 113     4.  Replacement text.  If the replacement is empty, then no
 114         fix is applied.  Otherwise, the replacement text is
 115         written to the output file and no further fixes are
 116         applied.  If you really want a no-op file, replace the
 117         file with a comment.
 118
 119         Replacement text "fixes" must be first in this file!!
 120
 121     Examples of fixes:
 122     ------------------
 123
 124       hackname = AAA_ki_iface;
 125       replace; /* empty replacement -> no fixing the file */
 126
 127     When this ``fix'' is invoked, it will prevent any fixes
 128     from being applied.
 129
 130     ------------------
 131
 132       hackname = AAB_svr4_no_varargs;
 133       replace  = "/* This file was generated by fixincludes.  */\n"
 134                  "#ifndef _SYS_VARARGS_H\n"
 135                  "#define _SYS_VARARGS_H\n\n"
 136
 137                  "#ifdef __STDC__\n"
 138                  "#include <stdarg.h>\n"
 139                  "#else\n"
 140                  "#include <varargs.h>\n"
 141                  "#endif\n\n"
 142
 143                  "#endif  /* _SYS_VARARGS_H */\n";
 144
 145     When this ``fix'' is invoked, the replacement text will be
 146     emitted into the replacement include file.  No further fixes
 147     will be applied.
 148
 149     ------------------
 150
 151       hackname = dec_intern_asm;
 152       files    = c_asm.h;
 153       sed = "/^[ \t]*float[ \t]*fasm/i\\\n#ifdef __DECC\n";
 154       sed = "/^[ \t]*#[ \t]*pragma[ \t]*intrinsic([ \t]*dasm/a\\\n"
 155             "#endif\n";
 156
 157     When this ``fix'' is invoked, sed will be run on the original
 158     file with two "-e" arguments.  Since these arguments have double
 159     quoted string values, the strings actually passed to ``sed''
 160     will have been processed in the same fashion that the C compiler
 161     processes its string specifications.  Including the concatenation
 162     of the two pieces of the second sed "-e" argument.
 163
 164     ------------------
 165
 166       hackname = m88k_multi_incl;
 167       shell    =
 168         "echo Fixing $file, to protect against multiple inclusion. >&2
 169         cpp_wrapper=`echo $file | sed -e 's,\\.,_,g' -e 's,/,_,g'`
 170         echo \"#ifndef __GCC_GOT_${cpp_wrapper}_\"
 171         echo \"#define __GCC_GOT_${cpp_wrapper}_\"
 172         cat
 173         echo \"#endif /* ! __GCC_GOT_${cpp_wrapper}_ */\"";
 174
 175     This is a shell script fix.  Note the ``cat'' without any arguments.
 176     This will drain stdin.  If the contents of the file were to be
 177     discarded, you would have to have something like ``cat > /dev/null''
 178     in the script.
 179
 180     ------------------
 181
 182       hackname = no_double_slash;
 183       c_fix    = "no_double_slash";
 184
 185     This specifies a fix to be supplied via a hand coded internal
 186     function named ``no_double_slash_fix()''.  See ``fixfixes.c''
 187     for documentation on how to include new functions into that
 188     module.
 189
 190 5.  Testing fixes.
 191
 192     The brute force method is, of course, to configure and build
 193     GCC.  There are easier ways, too.  You can run the compiled
 194     binaries in isolation.  ``c_tests'' can be tested with
 195     ``fixtests'', ``c_fixes'' with ``fixfixes'' and any fix or
 196     test can be tested with ``fixincl''.
 197
 198     ``fixtests'' is invoked as follows:
 199
 200         fixtests filename.h your_test_name
 201         if [ $? -ne 0 ]
 202         then echo do not apply your_fix_name
 203         else echo APPLY your_fix_name ; fi
 204
 205     and ``fixfixes'' is invoked thus:
 206
 207         fixfixes filename.h your_fix_name < filename.h > /tmp/fixed
 208
 209     The file name argument is required, but is only used as a hint
 210     for use by ``your_fix_name'', it is not used for obtaining the
 211     data.  Also, ``your_fix_name'' and ``your_test_name'' may be
 212     the same, since fix names and test names are in different
 213     "name spaces."
 214
 215     The ``fixincl'' program is a little harder to work with  :-}.
 216     It was written with the expectation that it would be run
 217     inside of the fixincl.sh script that handles everything.
 218
 219     Run it with no arguments to get usage hints, but here is what
 220     you will need to do (approximately):
 221
 222         FI=${top_builddir}/gcc/fixinc/fixincl
 223         TARGET_MACHINE=`sh ${top_srcdir}/config.guess`
 224         SRCDIR=/usr/include
 225         DESTDIR=/tmp/fixtest
 226         VERBOSE=4
 227         FIND_BASE="."
 228         export TARGET_MACHINE SRCDIR DESTDIR VERBOSE FIND_BASE
 229         rm -rf ${DESTDIR}
 230         mkdir -p ${DESTDIR}
 231         cd ${SRCDIR}
 232         find * -follow -type f -name '*.h' > ${DESTDIR}/LIST
 233         # you may edit this to the list you want
 234         ${FI} ${DESTDIR}/LIST > /dev/null 2> ${DESTDIR}/LOG
 235
 236     Check your results in ${DESTDIR}/LOG.  The stdout output
 237     is merely some shell commands that are relevant only to
 238     the fixincl.sh shell script.