Quick start documentation for the header file utilities. This isn't a full breakdown of the tools, just they typical use scenarios. - Each tool accepts -h to show it's usage. Usually no parameters will also trigger the help message. Help may specify additional functionality to what is listed here. - For all tools, option format for specifying filenames must have no spaces between the option and filename. ie.: tool -lfilename.h target.h - Many of the tools are required to be run from the core gcc source directory containing coretypes.h. Typically that is in gcc/gcc from a source checkout. For these tools to work on files not in this directory, their path needs to be specified on the command line. ie.: tool c/c-decl.c lto/lto.c - options can be intermixed with filenames anywhere on the command line ie. tool ssa.h rtl.h -a is equivalent to tool ssa.h -a rtl.h gcc-order-headers ----------------- This will reorder any primary backend headers files known to the tool into a canonical order which will resolve any hidden dependencies they may have. Any unknown headers will simply be placed after the recognized files, and retain the same relative ordering they had. This tool must be run in the core gcc source directory. Simply execute the command listing any files you wish to process on the command line. Any files which are changed are output, and the original is saved with a .bak extention. ex.: gcc-order-headers tree-ssa.c c/c-decl.c -s will list all of the known headers in their canonical order. It does not show which of those headers include other headers, just the final canonical ordering. if any header files are included within a conditional code block, the tool will issue a message and not change the file. When this happens, you can manually inspect the file to determine if reordering it is actually OK. Then rerun the command with the -i option. This will ignore the conditional error condition and perform the re-ordering anyway. If any #include line has the beginning of a multi-line comment, it will also refuse to process the file until that is resolved by terminating the comment on the same line, or removing it. show-headers ------------ This will show the include structure for any given file. Each level of nesting is indented, and when any duplicate headers are seen, they have their duplicate number shown -i may be used to specify additional search directories for headers to parse. -s specifies headers to look for and emphasize in the output. This tool must be run in the core gcc source directory. ex.: show-headers -sansidecl.h tree-ssa.c tree-ssa.c config.h auto-host.h ansidecl.h (1) <<------- system.h safe-ctype.h filenames.h hashtab.h (1) ansidecl.h (2) <<------- libiberty.h ansidecl.h (3) <<------- hwint.h coretypes.h machmode.h (1) insn-modes.h (1) signop.h <...> count-headers ------------- simply count all the headers found in the specified files. A summary is printed showing occurrences from high to low. ex.: count-headers tree*.c 86 : coretypes.h 86 : config.h 86 : system.h 86 : tree.h 82 : backend.h 80 : gimple.h 72 : gimple-iterator.h 70 : ssa.h 68 : fold-const.h <...> included-by ----------- This tool will search all the .c,.cc and .h files and output a list of files which include the specified header(s). A 4 level deep 'find' of all source files is performed from the current directory and each of those is inspected for a #include of the specified headers. So expect a little bit of slowness. -i limits the search to only other header files. -c limits the search to .c and .cc files. -a shows only source files which include all specified headers. -f allows you to specify a file which contains a list of source files to check rather than performing the much slower find command. ex: included-by tree-vectorizer.h config/aarch64/aarch64.c config/i386/i386.c config/rs6000/rs6000.c tree-loop-distribution.c tree-parloops.c tree-ssa-loop-ivopts.c tree-ssa-loop.c replace-header -------------- This tool simply replaces a single header file with one or more other headers. -r specifies the include to replace, and one or more -f options specify the replacement headers, in the order they occur. This is commonly used in conjunction with 'included-by' to change all occurrences of a header file to something else, or to insert new headers before or after. ex: to insert #include "before.h" before every occurence of tree.h in all .c and .cc source files: replace-header -rtree.h -fbefore.h -ftree.h `included-by -c tree.h` reduce-headers -------------- This tool removes any header files which are not needed from a source file. This tool must be run for the core gcc source directory, and requires either a native build and sometimes target builds, depending on what you are trying to reduce. it is good practice to run 'gcc-order-headers' on a source file before trying to reduce it. This removes duplicates and performs some simplifications which reduce the chances of the reduction tool missing things. start with a completely bootstrapped native compiler. Any desired target builds should be built in one directory using a modified config-list.mk file which does not delete the build directory when it is done. any target directories which do not successfully complete a 'make all-gcc' may cause the tool to not reduce anything. (todo - provide a config-list.mk that leaves successful target builds, but deletes ones which do not compile) The tool will examine all the target builds to determine which targets build the file, and include those targets in the testing. The tool will analyze a source file and attempt to remove each non-conditional header from last to first in the file.: It will first attempt to build the native all-gcc target. If that succeeds, it will attempt to build any target build .o files If that succeeds, it will check to see if there are any conditional compilation dependencies between this header file and the source file or any header which have already been determined as non-removable. If all these tests are passed, the header file is determined to be removable and is removed from the source file. This continues until all headers have been checked. At this point, a bootstrap is attempted in the native build, and if that passes the file is considered reduced. Any files from the config subdirectory require target builds to be present in order to proceed. A small subset of targets has been determined to provide excellent coverage, at least as of Aug 31/15 . They were found by reducing all the files contained in libbackend.a oer a full set of targets(207). All conditions which disallowed removal of a header file were triggered by one or more of these targets. They are also known to the tool. When building targets it will check those targets before the rest. This coverage can be achieved by building config-list.mk with : 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" -b specifies the native bootstrapped build root directory -t specifies a target build root directory that config-list.mk was run from -f is used to limit the headers for consideration. example: mkdir gcc // checkout gcc in subdir gcc mdsir build // boostrap gcc in subdir build mkdir target // create target directory and run config-list.mk cd gcc/gcc reduce-headers -b../../build -t../../targets -falias.h -fexpr.h tree*.c (1) # This will attempt to remove only alias.h and expr.h from tree*.c reduce-headers -b../../build -t../../targets tree-ssa-live.c # This will attempt to remove all header files from tree-ssa-live.c the tool will generate a number of log files: reduce-headers.log : All compilation failures from attempted reductions. reduce-headers.sum : One line summary of what happened to each source file. (All the remaining logs are appended to, so if the tool is run multiple times these files are just added to. You must physically remove them yourself in order to reset the logs.) reduce-headers-kept.log: List of all the successful compiles that were ignored because of conditional macro dependencies and why it thinks that is the case $src.c.log : for each failed header removal, the compilation messages as to why it failed. $header.h.log: The same log is put into the relevant header log as well. a sample output from ira.c.log: Compilation failed: for shrink-wrap.h: ============================================ /gcc/2015-09-09/gcc/gcc/ira.c: In function ‘bool split_live_ranges_for_shrink_wrap()’: /gcc/2015-09-09/gcc/gcc/ira.c:4839:8: error: ‘SHRINK_WRAPPING_ENABLED’ was not declared in this scope if (!SHRINK_WRAPPING_ENABLED) ^ make: *** [ira.o] Error 1 the same message would be put into shrink-wrap.h.log. graph-header-logs ----------------- This tool will parse all the messages from the .C files, looking for failures that show up in other headers... meaning there is a compilation dependency between the 2 header files. The tool will aggregate all these and generate a graph of the dependencies exposed during compilation. Red lines indicate dependencies that are present because a header file physically includes another file. Black lines represent data dependencies causing compilation failures if the header is not present. ex.: graph-header-logs *.c.log graph-include-web ----------------- This tool can be used to visualize the include structure in files. It is rapidly turned useless if you specify too many things, but it can be useful for finding cycles and redundancies, or simply to see what a single file looks like. ex.: graph-include-web tree.c