util/makedepend/mkdepend.man

   1 .TH MAKEDEPEND 1 "26 October 1988" "X Version 11"
   2 .UC 4
   3 .SH NAME
   4 makedepend \- create dependencies in makefiles
   5 .SH SYNOPSIS
   6 .B makedepend
   7 [
   8 .B \-Dname=def
   9 ] [
  10 .B \-Dname
  11 ] [
  12 .B \-Iincludedir
  13 ] [
  14 .B \-fmakefile
  15 ] [
  16 .B \-oobjsuffix
  17 ] [
  18 .B \-sstring
  19 ] [
  20 .B \-wwidth
  21 ] [
  22 \-\ \-
  23 .B otheroptions
  24 \-\ \-
  25 ]
  26 sourcefile ...
  27 .br
  28 .SH DESCRIPTION
  29 .B Makedepend
  30 reads each
  31 .I sourcefile
  32 in sequence and parses it like a C-preprocessor,
  33 processing all
  34 .I #include,
  35 .I #define,
  36 .I #undef,
  37 .I #ifdef,
  38 .I #ifndef,
  39 .I #endif,
  40 .I #if
  41 and
  42 .I #else
  43 directives so that it can correctly tell which
  44 .I #include,
  45 directives would be used in a compilation.
  46 Any
  47 .I #include,
  48 directives can reference files having other
  49 .I #include
  50 directives, and parsing will occur in these files as well.
  51 .PP
  52 Every file that a
  53 .I sourcefile
  54 includes,
  55 directly or indirectly,
  56 is what
  57 .B makedepend
  58 calls a "dependency".
  59 These dependencies are then written to a
  60 .I makefile
  61 in such a way that
  62 .B make(1)
  63 will know which object files must be recompiled when a dependency has changed.
  64 .PP
  65 By default,
  66 .B makedepend
  67 places its output in the file named
  68 .I makefile
  69 if it exists, otherwise
  70 .I Makefile.
  71 An alternate makefile may be specified with the
  72 .I -f
  73 option.
  74 It first searches the makefile for
  75 the line
  76 .sp
  77     # DO NOT DELETE THIS LINE -- make depend depends on it.
  78 .sp
  79 or one provided with the
  80 .I -s
  81 option,
  82 as a delimiter for the dependency output.
  83 If it finds it, it will delete everything
  84 following this to the end of the makefile
  85 and put the output after this line.
  86 If it doesn't find it, the program
  87 will append the string to the end of the makefile
  88 and place the output following that.
  89 For each
  90 .I sourcefile
  91 appearing on the command line,
  92 .B makedepend
  93 puts lines in the makefile of the form
  94 .sp
  95      sourcefile.o: dfile ...
  96 .sp
  97 Where "sourcefile.o" is the name from the command
  98 line with its suffix replaced with ".o",
  99 and "dfile" is a dependency discovered in a
 100 .I #include
 101 directive while parsing
 102 .I sourcefile
 103 or one of the files it included.
 104 .SH EXAMPLE
 105 Normally,
 106 .B makedepend
 107 will be used in a makefile target so that typing "make depend" will
 108 bring the dependencies up to date for the makefile.
 109 For example,
 110 .nf
 111     SRCS = file1.c file2.c ...
 112     CFLAGS = -O -DHACK -I../foobar -xyz
 113     depend:
 114             makedepend -- $(CFLAGS) -- $(SRCS)
 115 .fi
 116 .SH OPTIONS
 117 .B Makedepend
 118 will ignore any option that it does not understand so that you may use
 119 the same arguments that you would for
 120 .B cc(1).
 121 .TP 5
 122 .B \-Dname=def or \-Dname
 123 Define.
 124 This places a definition for
 125 .I name
 126 in
 127 .B makedepend's
 128 symbol table.
 129 Without
 130 .I =def
 131 the symbol becomes defined as "1".
 132 .TP 5
 133 .B \-Iincludedir
 134 Include directory.
 135 This option tells
 136 .B makedepend
 137 to prepend
 138 .I includedir
 139 to its list of directories to search when it encounters
 140 a
 141 .I #include
 142 directive.
 143 By default,
 144 .B makedepend
 145 only searches /usr/include.
 146 .TP 5
 147 .B \-fmakefile
 148 Filename.
 149 This allows you to specify an alternate makefile in which
 150 .B makedepend
 151 can place its output.
 152 .TP 5
 153 .B \-oobjsuffix
 154 Object file suffix.
 155 Some systems may have object files whose suffix is something other
 156 than ".o".
 157 This option allows you to specify another suffix, such as
 158 ".b" with
 159 .I -o.b
 160 or ":obj"
 161 with
 162 .I -o:obj
 163 and so forth.
 164 .TP 5
 165 .B \-sstring
 166 Starting string delimiter.
 167 This option permits you to specify
 168 a different string for
 169 .B makedepend
 170 to look for in the makefile.
 171 .TP 5
 172 .B \-wwidth
 173 Line width.
 174 Normally,
 175 .B makedepend
 176 will ensure that every output line that it writes will be no wider than
 177 78 characters for the sake of readability.
 178 This option enables you to change this width.
 179 .TP 5
 180 .B "\-\ \- options \-\ \-"
 181 If
 182 .B makedepend
 183 encounters a double hyphen (\-\ \-) in the argument list,
 184 then any unrecognized argument following it
 185 will be silently ignored; a second double hyphen terminates this
 186 special treatment.
 187 In this way,
 188 .B makedepend
 189 can be made to safely ignore esoteric compiler arguments that might
 190 normally be found in a CFLAGS
 191 .B make
 192 macro (see the
 193 .B EXAMPLE
 194 section above).
 195 All options that
 196 .B makedepend
 197 recognizes and appear between the pair of double hyphens
 198 are processed normally.
 199 .SH ALGORITHM
 200 The approach used in this program enables it to run an order of magnitude
 201 faster than any other "dependency generator" I have ever seen.
 202 Central to this performance are two assumptions:
 203 that all files compiled by a single
 204 makefile will be compiled with roughly the same
 205 .I -I
 206 and
 207 .I -D
 208 options;
 209 and that most files in a single directory will include largely the
 210 same files.
 211 .PP
 212 Given these assumptions,
 213 .B makedepend
 214 expects to be called once for each makefile, with
 215 all source files that are maintained by the
 216 makefile appearing on the command line.
 217 It parses each source and include
 218 file exactly once, maintaining an internal symbol table
 219 for each.
 220 Thus, the first file on the command line will take an amount of time
 221 proportional to the amount of time that a normal C preprocessor takes.
 222 But on subsequent files, if it encounter's an include file
 223 that it has already parsed, it does not parse it again.
 224 .PP
 225 For example,
 226 imagine you are compiling two files,
 227 .I file1.c
 228 and
 229 .I file2.c,
 230 they each include the header file
 231 .I header.h,
 232 and the file
 233 .I header.h
 234 in turn includes the files
 235 .I def1.h
 236 and
 237 .I def2.h.
 238 When you run the command
 239 .sp
 240     makedepend file1.c file2.c
 241 .sp
 242 .B makedepend
 243 will parse
 244 .I file1.c
 245 and consequently,
 246 .I header.h
 247 and then
 248 .I def1.h
 249 and
 250 .I def2.h.
 251 It then decides that the dependencies for this file are
 252 .sp
 253     file1.o: header.h def1.h def2.h
 254 .sp
 255 But when the program parses
 256 .I file2.c
 257 and discovers that it, too, includes
 258 .I header.h,
 259 it does not parse the file,
 260 but simply adds
 261 .I header.h,
 262 .I def1.h
 263 and
 264 .I def2.h
 265 to the list of dependencies for
 266 .I file2.o.
 267 .SH "SEE ALSO"
 268 cc(1), make(1)
 269 .SH BUGS
 270 If you do not have the source for cpp, the Berkeley Unix C preprocessor,
 271 then
 272 .B makedepend
 273 will be compiled in such a way that all
 274 .I #if
 275 directives will evaluate to "true" regardless of their actual value.
 276 This may cause the wrong
 277 .I #include
 278 directives to be evaluated.
 279 .B Makedepend
 280 should simply have its own parser written for
 281 .I #if
 282 expressions.
 283 .PP
 284 Imagine you are parsing two files,
 285 say
 286 .I file1.c
 287 and
 288 .I file2.c,
 289 each includes the file
 290 .I def.h.
 291 The list of files that
 292 .I def.h
 293 includes might truly be different when
 294 .I def.h
 295 is included by
 296 .I file1.c
 297 than when it is included by
 298 .I file2.c.
 299 But once
 300 .B makedepend
 301 arrives at a list of dependencies for a file,
 302 it is cast in concrete.
 303 .SH AUTHOR
 304 Todd Brunhoff, Tektronix, Inc. and MIT Project Athena