| 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.cc lto/lto.cc | |
| - 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.cc c/c-decl.cc | |
| -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.cc | |
| tree-ssa.cc | |
| 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.cc | |
| config/i386/i386.cc | |
| config/rs6000/rs6000.cc | |
| tree-loop-distribution.cc | |
| tree-parloops.cc | |
| tree-ssa-loop-ivopts.cc | |
| tree-ssa-loop.cc | |
| 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 i686-mingw32crt i686-pc-msdosdjgpp mipsel-elf powerpc-eabisimaltivec rs6000-ibm-aix5.1.0 sh-superh-elf sparc64-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.cc | |
| # This will attempt to remove all header files from tree-ssa-live.cc | |
| 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.cc.log: | |
| Compilation failed: | |
| for shrink-wrap.h: | |
| ============================================ | |
| /gcc/2015-09-09/gcc/gcc/ira.cc: In function ‘bool split_live_ranges_for_shrink_wrap()’: | |
| /gcc/2015-09-09/gcc/gcc/ira.cc: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.cc |