incl [ -e ][ .BR -i draw ][ .BR -l level ][ .BR -r draw ][ -F ][ .BR -G xsize,ysize ] [ .BR -I ] [ .BR -R xsize,ysize ] [ .BR -S "file,..." ][files]

Given a set of .c or .A files, incl analyzes, for each file, the relationships among all files that are included directly or indirectly using the #include directive of the C preprocessor. Options are provided to output various textual lists or graphic drawings that show unnecessary include files and relationships among files in the same include hierarchy. incl performs the analysis by using the file inclusion and entity reference relationships stored in the CIA database (see .IR cia (1)). For example, let x.c be a source file that includes x.h and, in turn, x.h includes y.h and z.h. This simple include hierarchy can be shown in a textual form:

  .ft CW
          x.c
                x.h
                  y.h
                  z.h        
  .ft R
  

• -e Output an ed script (file.e), which can be used to remove unnecessary #include statements from the original source file. The files to be removed are also output to stderr.
• .BR -i [draw] If either -G or -R is turned on, in the DOT description output, edges that represent only reference relationships are either (1) drawn invisibly if draw=1 or not specified or (2) not drawn if draw=0. This option helps reduce the complexity of large incl pictures.
• .BR -l [level] Output #include files up to the maximum level. If level is non-positive, all levels are output. This option can help manage the complexity of large incl hierarchies. When not used along with the -G or -R option, this option prints the include hierarchy in a textual form. Each file name is indented by its level in the #include hierarchy. Unnecessary files are marked with ~ at the end of their names and on-path files are marked with +.
• .BR -r [draw] Similar to -i but for edges that represent only #include relations. This option also helps reduce the complexity of large incl pictures.
• -u Output the list of unnecessary include files to file.u, which can be used to instruct Glenn Fowler's .IR cpp (1) to skip those files during C preprocessing. See the example in the EXAMPLES section.
• -F Generate the DOT (see .IR dot (1)) directive .BR ratio=fill . It forces dot to draw the picture using the aspect ratio specified by the width and height. Without this option, the "natural" aspect ratio determined by dot will be used and a page may be left partially filled.
• .BR -G [xsize,ysize] Output a DOT description of the directed graph of #include files. The arguments, xsize and ysize, if given, define the dimension of the output page. Default values for xsize and ysize are 7 and 9 inches. For each input .c or .A file, a graph is written to a .d file. The following drawing conventions are observed. A box node denotes a file that must be included because it contains definitions that are used elsewhere. An oval node denotes an #include file that is irrelevant. A dotted edge denotes that the tail file directly includes the head file, but does not use any references in the head file. A dashed edge denotes that the tail file does not directly include the head file, but it contains references to definitions in the head file. Finally, a solid edge indicates that the tail file both directly includes and makes use of definitions in the head file.
• .BR -I Create an incl database file. Currently, .IR idb (1) must be called to attach a .IR cql (1) virtual directory at the end.
• .BR -R [xsize,ysize] This is similar to the -G option but the graph is rotated. This option is preferred for most include hierarchies.
• .BR -S name1[,name2,...] Specify a collection of roots from which the incl picture will be created. The graph generated is usually a subset of the complete incl graph. This option helps manage the complexity of large include hierarchies.

Files given to incl must have suffices .c (C source code) or .A (CIA data). If the files reside in a directory other than the current directory, the respective directory should be given in the environment variable CIAODBDIR. The analysis done by incl is consistent with the conditional compilation flags given to cia during the construction of database files. If any of the flags is changed, then the analysis should be redone.

List unnecessary files included directly or indirectly by ciafan.c:

  .ft CW
  \$ incl ciafan.A
  ciafan.A :
          /usr/include/sys/stdtypes.h
          /usr/include/sys/sysmacros.h
          /usr/include/sys/types.h
          libpdb/buffer.h
          libpdb/pathmap.h
          libpdb/view.h
          user_format.h
  .ft R
  

  .ft CW
  \$ incl -l util.c
  util.c
          incl.h
                  ../../../include/libcia/ciastream.h+
                          /usr/add-on/ast/include/ast/stdio.h
                                  /usr/add-on/ast/include/ast/sfio.h
                  tree.h~
          tree.h~
  .ft R
  

  .ft CW
  \$ incl -e ciafan.A
  \$ cat ciafan.e
  10d
  w
  \$ cp ciafan.c ciafan-new.c
  \$ ed ciafan-new.c < ciafan.e
  4574
  4549
  .ft R
  

  .ft CW
  \$ incl -R ciafan.A
  \$ sed -e 's,../../../include,INC,g' ciafan.d | dot -Tps > ciafan-1.ps
  \$ lpr ciafan-1.ps
  .ft R
  

  .ft CW
  \$ incl -R7.5,6 -l1 ciafan.A
  \$ dot -Tps ciafan.d > ciafan-2.ps
  \$ lpr ciafan-2.ps
  .ft R
  

  .ft CW
  \$ incl -R -i0 -f ciafan.A
  \$ dot -Tps ciafan.d > ciafan-3.ps
  \$ lpr ciafan-3.ps
  .ft R
  

  .ft CW
  \$ incl -R -Sciafan.h,../../../include/libpdb/infoview.h -i0 -f ciafan.A
  \$ dot -Tps ciafan.d > ciafan-4.ps
  \$ lpr ciafan-4.ps
  .ft R
  

  .ft CW
  \$ incl -u ciafan.A
  \$ cc -Qpath /usr/local/lib -I../../../include -I-I-.u -c ciafan.c
  .ft R