OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-dev/] [or1k-gcc/] [fixincludes/] [README] - Blame information for rev 733

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 724 jeremybenn
 
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 
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 \n"
282
                 "#else\n"
283
                 "#include \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.

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.