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.cc lto/lto.cc 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.cc c/c-decl.cc 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.cc 71 tree-ssa.cc 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.cc 128 config/i386/i386.cc 129 config/rs6000/rs6000.cc 130 tree-loop-distribution.cc 131 tree-parloops.cc 132 tree-ssa-loop-ivopts.cc 133 tree-ssa-loop.cc 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 i686-mingw32crt i686-pc-msdosdjgpp mipsel-elf powerpc-eabisimaltivec rs6000-ibm-aix5.1.0 sh-superh-elf sparc64-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.cc 223 # This will attempt to remove all header files from tree-ssa-live.cc 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.cc.log: 244 245 Compilation failed: 246 for shrink-wrap.h: 247 248 ============================================ 249 /gcc/2015-09-09/gcc/gcc/ira.cc: In function bool split_live_ranges_for_shrink_wrap(): 250 /gcc/2015-09-09/gcc/gcc/ira.cc: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.cc 284
Indexes created Sat Aug 08 00:24:54 UTC 2026