123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283 |
- 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 hppa2.0-hpux10.1 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
|