contrib/header-tools/README

   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.c  lto/lto.c
  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.c c/c-decl.c
  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.c
  71         tree-ssa.c
  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.c
 128         config/i386/i386.c
 129         config/rs6000/rs6000.c
 130         tree-loop-distribution.c
 131         tree-parloops.c
 132         tree-ssa-loop-ivopts.c
 133         tree-ssa-loop.c
 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 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"
 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
 243 a sample output from ira.c.log:
 244
 245 Compilation 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
 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.c