|
111
|
1 Quick start documentation for the header file utilities.
|
|
|
2
|
|
|
3 This isn't a full breakdown of the tools, just they typical use scenarios.
|
|
|
4
|
|
|
5 - Each tool accepts -h to show it's usage. Usually no parameters will also
|
|
|
6 trigger the help message. Help may specify additional functionality to what is
|
|
|
7 listed here.
|
|
|
8
|
|
|
9 - For all tools, option format for specifying filenames must have no spaces
|
|
|
10 between the option and filename.
|
|
|
11 ie.: tool -lfilename.h target.h
|
|
|
12
|
|
|
13 - Many of the tools are required to be run from the core gcc source directory
|
|
|
14 containing coretypes.h. Typically that is in gcc/gcc from a source checkout.
|
|
|
15 For these tools to work on files not in this directory, their path needs to be
|
|
|
16 specified on the command line.
|
|
|
17 ie.: tool c/c-decl.c lto/lto.c
|
|
|
18
|
|
|
19 - options can be intermixed with filenames anywhere on the command line
|
|
|
20 ie. tool ssa.h rtl.h -a is equivalent to
|
|
|
21 tool ssa.h -a rtl.h
|
|
|
22
|
|
|
23
|
|
|
24
|
|
|
25
|
|
|
26
|
|
|
27 gcc-order-headers
|
|
|
28 -----------------
|
|
|
29 This will reorder any primary backend headers files known to the tool into a
|
|
|
30 canonical order which will resolve any hidden dependencies they may have.
|
|
|
31 Any unknown headers will simply be placed after the recognized files, and
|
|
|
32 retain the same relative ordering they had.
|
|
|
33
|
|
|
34 This tool must be run in the core gcc source directory.
|
|
|
35
|
|
|
36 Simply execute the command listing any files you wish to process on the
|
|
|
37 command line.
|
|
|
38
|
|
|
39 Any files which are changed are output, and the original is saved with a
|
|
|
40 .bak extention.
|
|
|
41
|
|
|
42 ex.: gcc-order-headers tree-ssa.c c/c-decl.c
|
|
|
43
|
|
|
44 -s will list all of the known headers in their canonical order. It does not
|
|
|
45 show which of those headers include other headers, just the final canonical
|
|
|
46 ordering.
|
|
|
47
|
|
|
48 if any header files are included within a conditional code block, the tool
|
|
|
49 will issue a message and not change the file. When this happens, you can
|
|
|
50 manually inspect the file to determine if reordering it is actually OK. Then
|
|
|
51 rerun the command with the -i option. This will ignore the conditional error
|
|
|
52 condition and perform the re-ordering anyway.
|
|
|
53
|
|
|
54 If any #include line has the beginning of a multi-line comment, it will also
|
|
|
55 refuse to process the file until that is resolved by terminating the comment
|
|
|
56 on the same line, or removing it.
|
|
|
57
|
|
|
58
|
|
|
59 show-headers
|
|
|
60 ------------
|
|
|
61 This will show the include structure for any given file. Each level of nesting
|
|
|
62 is indented, and when any duplicate headers are seen, they have their
|
|
|
63 duplicate number shown
|
|
|
64
|
|
|
65 -i may be used to specify additional search directories for headers to parse.
|
|
|
66 -s specifies headers to look for and emphasize in the output.
|
|
|
67
|
|
|
68 This tool must be run in the core gcc source directory.
|
|
|
69
|
|
|
70 ex.: show-headers -sansidecl.h tree-ssa.c
|
|
|
71 tree-ssa.c
|
|
|
72 config.h
|
|
|
73 auto-host.h
|
|
|
74 ansidecl.h (1) <<-------
|
|
|
75 system.h
|
|
|
76 safe-ctype.h
|
|
|
77 filenames.h
|
|
|
78 hashtab.h (1)
|
|
|
79 ansidecl.h (2) <<-------
|
|
|
80 libiberty.h
|
|
|
81 ansidecl.h (3) <<-------
|
|
|
82 hwint.h
|
|
|
83 coretypes.h
|
|
|
84 machmode.h (1)
|
|
|
85 insn-modes.h (1)
|
|
|
86 signop.h
|
|
|
87 <...>
|
|
|
88
|
|
|
89
|
|
|
90
|
|
|
91
|
|
|
92 count-headers
|
|
|
93 -------------
|
|
|
94 simply count all the headers found in the specified files. A summary is
|
|
|
95 printed showing occurrences from high to low.
|
|
|
96
|
|
|
97 ex.: count-headers tree*.c
|
|
|
98 86 : coretypes.h
|
|
|
99 86 : config.h
|
|
|
100 86 : system.h
|
|
|
101 86 : tree.h
|
|
|
102 82 : backend.h
|
|
|
103 80 : gimple.h
|
|
|
104 72 : gimple-iterator.h
|
|
|
105 70 : ssa.h
|
|
|
106 68 : fold-const.h
|
|
|
107 <...>
|
|
|
108
|
|
|
109
|
|
|
110
|
|
|
111 included-by
|
|
|
112 -----------
|
|
|
113 This tool will search all the .c,.cc and .h files and output a list of files
|
|
|
114 which include the specified header(s).
|
|
|
115
|
|
|
116 A 4 level deep 'find' of all source files is performed from the current
|
|
|
117 directory and each of those is inspected for a #include of the specified
|
|
|
118 headers. So expect a little bit of slowness.
|
|
|
119
|
|
|
120 -i limits the search to only other header files.
|
|
|
121 -c limits the search to .c and .cc files.
|
|
|
122 -a shows only source files which include all specified headers.
|
|
|
123 -f allows you to specify a file which contains a list of source files to
|
|
|
124 check rather than performing the much slower find command.
|
|
|
125
|
|
|
126 ex: included-by tree-vectorizer.h
|
|
|
127 config/aarch64/aarch64.c
|
|
|
128 config/i386/i386.c
|
|
|
129 config/rs6000/rs6000.c
|
|
|
130 tree-loop-distribution.c
|
|
|
131 tree-parloops.c
|
|
|
132 tree-ssa-loop-ivopts.c
|
|
|
133 tree-ssa-loop.c
|
|
|
134
|
|
|
135
|
|
|
136
|
|
|
137
|
|
|
138 replace-header
|
|
|
139 --------------
|
|
|
140 This tool simply replaces a single header file with one or more other headers.
|
|
|
141 -r specifies the include to replace, and one or more -f options specify the
|
|
|
142 replacement headers, in the order they occur.
|
|
|
143
|
|
|
144 This is commonly used in conjunction with 'included-by' to change all
|
|
|
145 occurrences of a header file to something else, or to insert new headers
|
|
|
146 before or after.
|
|
|
147
|
|
|
148 ex: to insert #include "before.h" before every occurence of tree.h in all
|
|
|
149 .c and .cc source files:
|
|
|
150
|
|
|
151 replace-header -rtree.h -fbefore.h -ftree.h `included-by -c tree.h`
|
|
|
152
|
|
|
153
|
|
|
154
|
|
|
155
|
|
|
156 reduce-headers
|
|
|
157 --------------
|
|
|
158
|
|
|
159 This tool removes any header files which are not needed from a source file.
|
|
|
160
|
|
|
161 This tool must be run for the core gcc source directory, and requires either
|
|
|
162 a native build and sometimes target builds, depending on what you are trying
|
|
|
163 to reduce.
|
|
|
164
|
|
|
165 it is good practice to run 'gcc-order-headers' on a source file before trying
|
|
|
166 to reduce it. This removes duplicates and performs some simplifications
|
|
|
167 which reduce the chances of the reduction tool missing things.
|
|
|
168
|
|
|
169 start with a completely bootstrapped native compiler.
|
|
|
170
|
|
|
171 Any desired target builds should be built in one directory using a modified
|
|
|
172 config-list.mk file which does not delete the build directory when it is done.
|
|
|
173 any target directories which do not successfully complete a 'make all-gcc'
|
|
|
174 may cause the tool to not reduce anything.
|
|
|
175 (todo - provide a config-list.mk that leaves successful target builds, but
|
|
|
176 deletes ones which do not compile)
|
|
|
177
|
|
|
178 The tool will examine all the target builds to determine which targets build
|
|
|
179 the file, and include those targets in the testing.
|
|
|
180
|
|
|
181
|
|
|
182
|
|
|
183 The tool will analyze a source file and attempt to remove each non-conditional
|
|
|
184 header from last to first in the file.:
|
|
|
185 It will first attempt to build the native all-gcc target.
|
|
|
186 If that succeeds, it will attempt to build any target build .o files
|
|
|
187 If that succeeds, it will check to see if there are any conditional
|
|
|
188 compilation dependencies between this header file and the source file or
|
|
|
189 any header which have already been determined as non-removable.
|
|
|
190 If all these tests are passed, the header file is determined to be removable
|
|
|
191 and is removed from the source file.
|
|
|
192 This continues until all headers have been checked.
|
|
|
193 At this point, a bootstrap is attempted in the native build, and if that
|
|
|
194 passes the file is considered reduced.
|
|
|
195
|
|
|
196 Any files from the config subdirectory require target builds to be present
|
|
|
197 in order to proceed.
|
|
|
198
|
|
|
199 A small subset of targets has been determined to provide excellent coverage,
|
|
|
200 at least as of Aug 31/15 . They were found by reducing all the files
|
|
|
201 contained in libbackend.a oer a full set of targets(207). All conditions
|
|
|
202 which disallowed removal of a header file were triggered by one or more of
|
|
|
203 these targets. They are also known to the tool. When building targets it
|
|
|
204 will check those targets before the rest.
|
|
|
205 This coverage can be achieved by building config-list.mk with :
|
|
|
206 LIST="aarch64-linux-gnu arm-netbsdelf c6x-elf epiphany-elf hppa2.0-hpux10.1 i686-mingw32crt i686-pc-msdosdjgpp mipsel-elf powerpc-eabisimaltivec rs6000-ibm-aix5.1.0 sh-superh-elf sparc64-elf spu-elf"
|
|
|
207
|
|
|
208 -b specifies the native bootstrapped build root directory
|
|
|
209 -t specifies a target build root directory that config-list.mk was run from
|
|
|
210 -f is used to limit the headers for consideration.
|
|
|
211
|
|
|
212 example:
|
|
|
213
|
|
|
214 mkdir gcc // checkout gcc in subdir gcc
|
|
|
215 mdsir build // boostrap gcc in subdir build
|
|
|
216 mkdir target // create target directory and run config-list.mk
|
|
|
217 cd gcc/gcc
|
|
|
218
|
|
|
219 reduce-headers -b../../build -t../../targets -falias.h -fexpr.h tree*.c (1)
|
|
|
220 # This will attempt to remove only alias.h and expr.h from tree*.c
|
|
|
221
|
|
|
222 reduce-headers -b../../build -t../../targets tree-ssa-live.c
|
|
|
223 # This will attempt to remove all header files from tree-ssa-live.c
|
|
|
224
|
|
|
225
|
|
|
226 the tool will generate a number of log files:
|
|
|
227
|
|
|
228 reduce-headers.log : All compilation failures from attempted reductions.
|
|
|
229 reduce-headers.sum : One line summary of what happened to each source file.
|
|
|
230
|
|
|
231 (All the remaining logs are appended to, so if the tool is run multiple times
|
|
|
232 these files are just added to. You must physically remove them yourself in
|
|
|
233 order to reset the logs.)
|
|
|
234
|
|
|
235 reduce-headers-kept.log: List of all the successful compiles that were
|
|
|
236 ignored because of conditional macro dependencies
|
|
|
237 and why it thinks that is the case
|
|
|
238 $src.c.log : for each failed header removal, the compilation
|
|
|
239 messages as to why it failed.
|
|
|
240 $header.h.log: The same log is put into the relevant header log as well.
|
|
|
241
|
|
|
242
|
|
|
243 a sample output from ira.c.log:
|
|
|
244
|
|
|
245 Compilation failed:
|
|
|
246 for shrink-wrap.h:
|
|
|
247
|
|
|
248 ============================================
|
|
|
249 /gcc/2015-09-09/gcc/gcc/ira.c: In function ‘bool split_live_ranges_for_shrink_wrap()’:
|
|
|
250 /gcc/2015-09-09/gcc/gcc/ira.c:4839:8: error: ‘SHRINK_WRAPPING_ENABLED’ was not declared in this scope
|
|
|
251 if (!SHRINK_WRAPPING_ENABLED)
|
|
|
252 ^
|
|
|
253 make: *** [ira.o] Error 1
|
|
|
254
|
|
|
255
|
|
|
256 the same message would be put into shrink-wrap.h.log.
|
|
|
257
|
|
|
258
|
|
|
259
|
|
|
260 graph-header-logs
|
|
|
261 -----------------
|
|
|
262 This tool will parse all the messages from the .C files, looking for failures
|
|
|
263 that show up in other headers... meaning there is a compilation dependency
|
|
|
264 between the 2 header files.
|
|
|
265
|
|
|
266 The tool will aggregate all these and generate a graph of the dependencies
|
|
|
267 exposed during compilation. Red lines indicate dependencies that are
|
|
|
268 present because a header file physically includes another file. Black lines
|
|
|
269 represent data dependencies causing compilation failures if the header is
|
|
|
270 not present.
|
|
|
271
|
|
|
272 ex.: graph-header-logs *.c.log
|
|
|
273
|
|
|
274
|
|
|
275
|
|
|
276 graph-include-web
|
|
|
277 -----------------
|
|
|
278 This tool can be used to visualize the include structure in files. It is
|
|
|
279 rapidly turned useless if you specify too many things, but it can be
|
|
|
280 useful for finding cycles and redundancies, or simply to see what a single
|
|
|
281 file looks like.
|
|
|
282
|
|
|
283 ex.: graph-include-web tree.c
|
