]>
Commit | Line | Data |
---|---|---|
bd94906f AM |
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 : | |
2f2aeda9 | 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" |
bd94906f AM |
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 |