155714SkrisQuick start documentation for the header file utilities. 255714Skris 355714SkrisThis isn't a full breakdown of the tools, just they typical use scenarios. 455714Skris 555714Skris- Each tool accepts -h to show it's usage. Usually no parameters will also 655714Skristrigger the help message. Help may specify additional functionality to what is 755714Skrislisted here. 8296341Sdelphij 955714Skris- For all tools, option format for specifying filenames must have no spaces 1055714Skrisbetween the option and filename. 1155714Skrisie.: tool -lfilename.h target.h 1255714Skris 1355714Skris- Many of the tools are required to be run from the core gcc source directory 1455714Skriscontaining coretypes.h. Typically that is in gcc/gcc from a source checkout. 15296341SdelphijFor these tools to work on files not in this directory, their path needs to be 1655714Skrisspecified on the command line. 1755714Skrisie.: tool c/c-decl.c lto/lto.c 1855714Skris 1955714Skris- options can be intermixed with filenames anywhere on the command line 2055714Skrisie. tool ssa.h rtl.h -a is equivalent to 2155714Skris tool ssa.h -a rtl.h 22296341Sdelphij 2355714Skris 2455714Skris 2555714Skris 2655714Skris 2755714Skrisgcc-order-headers 2855714Skris----------------- 2955714Skris This will reorder any primary backend headers files known to the tool into a 3055714Skris canonical order which will resolve any hidden dependencies they may have. 3155714Skris Any unknown headers will simply be placed after the recognized files, and 3255714Skris retain the same relative ordering they had. 3355714Skris 3455714Skris This tool must be run in the core gcc source directory. 3555714Skris 3655714Skris Simply execute the command listing any files you wish to process on the 37296341Sdelphij command line. 3855714Skris 3955714Skris Any files which are changed are output, and the original is saved with a 40296341Sdelphij .bak extention. 4155714Skris 4255714Skris ex.: gcc-order-headers tree-ssa.c c/c-decl.c 4355714Skris 4455714Skris -s will list all of the known headers in their canonical order. It does not 4555714Skris show which of those headers include other headers, just the final canonical 4655714Skris ordering. 4755714Skris 4855714Skris if any header files are included within a conditional code block, the tool 4955714Skris will issue a message and not change the file. When this happens, you can 5055714Skris manually inspect the file to determine if reordering it is actually OK. Then 5155714Skris rerun the command with the -i option. This will ignore the conditional error 52296341Sdelphij condition and perform the re-ordering anyway. 5355714Skris 5455714Skris If any #include line has the beginning of a multi-line comment, it will also 5555714Skris refuse to process the file until that is resolved by terminating the comment 5655714Skris on the same line, or removing it. 5755714Skris 5855714Skris 5955714Skrisshow-headers 6055714Skris------------ 6155714Skris This will show the include structure for any given file. Each level of nesting 6255714Skris is indented, and when any duplicate headers are seen, they have their 6355714Skris duplicate number shown 6455714Skris 6555714Skris -i may be used to specify additional search directories for headers to parse. 6655714Skris -s specifies headers to look for and emphasize in the output. 67296341Sdelphij 68296341Sdelphij This tool must be run in the core gcc source directory. 69296341Sdelphij 70296341Sdelphij ex.: show-headers -sansidecl.h tree-ssa.c 71296341Sdelphij tree-ssa.c 72296341Sdelphij config.h 73296341Sdelphij auto-host.h 74296341Sdelphij ansidecl.h (1) <<------- 7555714Skris system.h 76296341Sdelphij safe-ctype.h 77296341Sdelphij filenames.h 7855714Skris hashtab.h (1) 79296341Sdelphij ansidecl.h (2) <<------- 8055714Skris libiberty.h 81296341Sdelphij ansidecl.h (3) <<------- 82296341Sdelphij hwint.h 83296341Sdelphij coretypes.h 84296341Sdelphij machmode.h (1) 85296341Sdelphij insn-modes.h (1) 86296341Sdelphij signop.h 87296341Sdelphij <...> 88296341Sdelphij 89296341Sdelphij 90296341Sdelphij 91296341Sdelphij 92296341Sdelphijcount-headers 93296341Sdelphij------------- 94296341Sdelphij simply count all the headers found in the specified files. A summary is 95296341Sdelphij printed showing occurrences from high to low. 96296341Sdelphij 97296341Sdelphij ex.: count-headers tree*.c 98296341Sdelphij 86 : coretypes.h 99296341Sdelphij 86 : config.h 100296341Sdelphij 86 : system.h 101296341Sdelphij 86 : tree.h 102296341Sdelphij 82 : backend.h 103296341Sdelphij 80 : gimple.h 104296341Sdelphij 72 : gimple-iterator.h 105296341Sdelphij 70 : ssa.h 106296341Sdelphij 68 : fold-const.h 107296341Sdelphij <...> 108296341Sdelphij 109296341Sdelphij 110296341Sdelphij 111296341Sdelphijincluded-by 112296341Sdelphij----------- 113296341Sdelphij This tool will search all the .c,.cc and .h files and output a list of files 114296341Sdelphij which include the specified header(s). 115296341Sdelphij 116296341Sdelphij A 4 level deep 'find' of all source files is performed from the current 117296341Sdelphij directory and each of those is inspected for a #include of the specified 118296341Sdelphij headers. So expect a little bit of slowness. 119296341Sdelphij 120296341Sdelphij -i limits the search to only other header files. 121296341Sdelphij -c limits the search to .c and .cc files. 122296341Sdelphij -a shows only source files which include all specified headers. 123296341Sdelphij -f allows you to specify a file which contains a list of source files to 124296341Sdelphij check rather than performing the much slower find command. 125296341Sdelphij 126296341Sdelphij ex: included-by tree-vectorizer.h 127296341Sdelphij config/aarch64/aarch64.c 128296341Sdelphij config/i386/i386.c 129296341Sdelphij config/rs6000/rs6000.c 130296341Sdelphij tree-loop-distribution.c 131296341Sdelphij tree-parloops.c 132296341Sdelphij tree-ssa-loop-ivopts.c 133296341Sdelphij tree-ssa-loop.c 134296341Sdelphij 135296341Sdelphij 136296341Sdelphij 137296341Sdelphij 138296341Sdelphijreplace-header 139296341Sdelphij-------------- 140109998Smarkm This tool simply replaces a single header file with one or more other headers. 141296341Sdelphij -r specifies the include to replace, and one or more -f options specify the 142296341Sdelphij replacement headers, in the order they occur. 14355714Skris 144296341Sdelphij This is commonly used in conjunction with 'included-by' to change all 145296341Sdelphij 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 156reduce-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" 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 243a sample output from ira.c.log: 244 245Compilation 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 256the same message would be put into shrink-wrap.h.log. 257 258 259 260graph-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 276graph-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 284