nucleus/tools/dependency_tool/makedepend.man

   1 .\" $XConsortium: mkdepend.man,v 1.15 94/04/17 20:10:37 gildea Exp $
   2 .\" Copyright (c) 1993, 1994  X Consortium
   3 .\"
   4 .\" Permission is hereby granted, free of charge, to any person obtaining a
   5 .\" copy of this software and associated documentation files (the "Software"),
   6 .\" to deal in the Software without restriction, including without limitation
   7 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8 .\" and/or sell copies of the Software, and to permit persons to whom the
   9 .\" Software furnished to do so, subject to the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice shall be included in
  12 .\" all copies or substantial portions of the Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  17 .\" THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  18 .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  19 .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  20 .\" SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of the X Consortium shall not
  23 .\" be used in advertising or otherwise to promote the sale, use or other
  24 .\" dealing in this Software without prior written authorization from the
  25 .\" X Consortium.
  26 .TH MAKEDEPEND 1 "Release 6" "X Version 11"
  27 .UC 4
  28 .SH NAME
  29 makedepend \- create dependencies in makefiles
  30 .SH SYNOPSIS
  31 .B makedepend
  32 [
  33 .B \-Dname=def
  34 ] [
  35 .B \-Dname
  36 ] [
  37 .B \-Iincludedir
  38 ] [
  39 .B \-Yincludedir
  40 ] [
  41 .B \-a
  42 ] [
  43 .B \-fmakefile
  44 ] [
  45 .B \-oobjsuffix
  46 ] [
  47 .B \-pobjprefix
  48 ] [
  49 .B \-sstring
  50 ] [
  51 .B \-wwidth
  52 ] [
  53 .B \-v
  54 ] [
  55 .B \-m
  56 ] [
  57 \-\^\-
  58 .B otheroptions
  59 \-\^\-
  60 ]
  61 sourcefile .\|.\|.
  62 .br
  63 .SH DESCRIPTION
  64 .B Makedepend
  65 reads each
  66 .I sourcefile
  67 in sequence and parses it like a C-preprocessor,
  68 processing all
  69 .I #include,
  70 .I #define,
  71 .I #undef,
  72 .I #ifdef,
  73 .I #ifndef,
  74 .I #endif,
  75 .I #if
  76 and
  77 .I #else
  78 directives so that it can correctly tell which
  79 .I #include,
  80 directives would be used in a compilation.
  81 Any
  82 .I #include,
  83 directives can reference files having other
  84 .I #include
  85 directives, and parsing will occur in these files as well.
  86 .PP
  87 Every file that a
  88 .I sourcefile
  89 includes,
  90 directly or indirectly,
  91 is what
  92 .B makedepend
  93 calls a "dependency".
  94 These dependencies are then written to a
  95 .I makefile
  96 in such a way that
  97 .B make(1)
  98 will know which object files must be recompiled when a dependency has changed.
  99 .PP
 100 By default,
 101 .B makedepend
 102 places its output in the file named
 103 .I makefile
 104 if it exists, otherwise
 105 .I Makefile.
 106 An alternate makefile may be specified with the
 107 .B \-f
 108 option.
 109 It first searches the makefile for
 110 the line
 111 .sp
 112     # DO NOT DELETE THIS LINE \-\^\- make depend depends on it.
 113 .sp
 114 or one provided with the
 115 .B \-s
 116 option,
 117 as a delimiter for the dependency output.
 118 If it finds it, it will delete everything
 119 following this to the end of the makefile
 120 and put the output after this line.
 121 If it doesn't find it, the program
 122 will append the string to the end of the makefile
 123 and place the output following that.
 124 For each
 125 .I sourcefile
 126 appearing on the command line,
 127 .B makedepend
 128 puts lines in the makefile of the form
 129 .sp
 130      sourcefile.o:\0dfile .\|.\|.
 131 .sp
 132 Where "sourcefile.o" is the name from the command
 133 line with its suffix replaced with ".o",
 134 and "dfile" is a dependency discovered in a
 135 .I #include
 136 directive while parsing
 137 .I sourcefile
 138 or one of the files it included.
 139 .SH EXAMPLE
 140 Normally,
 141 .B makedepend
 142 will be used in a makefile target so that typing "make depend" will
 143 bring the dependencies up to date for the makefile.
 144 For example,
 145 .nf
 146     SRCS\0=\0file1.c\0file2.c\0.\|.\|.
 147     CFLAGS\0=\0\-O\0\-DHACK\0\-I\^.\^.\^/foobar\0\-xyz
 148     depend:
 149             makedepend\0\-\^\-\0$(CFLAGS)\0\-\^\-\0$(SRCS)
 150 .fi
 151 .SH OPTIONS
 152 .B Makedepend
 153 will ignore any option that it does not understand so that you may use
 154 the same arguments that you would for
 155 .B cc(1).
 156 .TP 5
 157 .B \-Dname=def or \-Dname
 158 Define.
 159 This places a definition for
 160 .I name
 161 in
 162 .B makedepend's
 163 symbol table.
 164 Without
 165 .I =def
 166 the symbol becomes defined as "1".
 167 .TP 5
 168 .B \-Iincludedir
 169 Include directory.
 170 This option tells
 171 .B makedepend
 172 to prepend
 173 .I includedir
 174 to its list of directories to search when it encounters
 175 a
 176 .I #include
 177 directive.
 178 By default,
 179 .B makedepend
 180 only searches the standard include directories (usually /usr/include
 181 and possibly a compiler-dependent directory).
 182 .TP 5
 183 .B \-Yincludedir
 184 Replace all of the standard include directories with the single specified
 185 include directory; you can omit the
 186 .I includedir
 187 to simply prevent searching the standard include directories.
 188 .TP 5
 189 .B \-a
 190 Append the dependencies to the end of the file instead of replacing them.
 191 .TP 5
 192 .B \-fmakefile
 193 Filename.
 194 This allows you to specify an alternate makefile in which
 195 .B makedepend
 196 can place its output.
 197 .TP 5
 198 .B \-oobjsuffix
 199 Object file suffix.
 200 Some systems may have object files whose suffix is something other
 201 than ".o".
 202 This option allows you to specify another suffix, such as
 203 ".b" with
 204 .I -o.b
 205 or ":obj"
 206 with
 207 .I -o:obj
 208 and so forth.
 209 .TP 5
 210 .B \-pobjprefix
 211 Object file prefix.
 212 The prefix is prepended to the name of the object file. This is
 213 usually used to designate a different directory for the object file.
 214 The default is the empty string.
 215 .TP 5
 216 .B \-sstring
 217 Starting string delimiter.
 218 This option permits you to specify
 219 a different string for
 220 .B makedepend
 221 to look for in the makefile.
 222 .TP 5
 223 .B \-wwidth
 224 Line width.
 225 Normally,
 226 .B makedepend
 227 will ensure that every output line that it writes will be no wider than
 228 78 characters for the sake of readability.
 229 This option enables you to change this width.
 230 .TP 5
 231 .B \-v
 232 Verbose operation.
 233 This option causes
 234 .B makedepend
 235 to emit the list of files included by each input file on standard output.
 236 .TP 5
 237 .B \-m
 238 Warn about multiple inclusion.
 239 This option causes
 240 .B makedepend
 241 to produce a warning if any input file includes another file more than
 242 once.  In previous versions of
 243 .B makedepend
 244 this was the default behavior; the default has been changed to better
 245 match the behavior of the C compiler, which does not consider multiple
 246 inclusion to be an error.  This option is provided for backward
 247 compatibility, and to aid in debugging problems related to multiple
 248 inclusion.
 249 .TP 5
 250 .B "\-\^\- options \-\^\-"
 251 If
 252 .B makedepend
 253 encounters a double hyphen (\-\^\-) in the argument list,
 254 then any unrecognized argument following it
 255 will be silently ignored; a second double hyphen terminates this
 256 special treatment.
 257 In this way,
 258 .B makedepend
 259 can be made to safely ignore esoteric compiler arguments that might
 260 normally be found in a CFLAGS
 261 .B make
 262 macro (see the
 263 .B EXAMPLE
 264 section above).
 265 All options that
 266 .B makedepend
 267 recognizes and appear between the pair of double hyphens
 268 are processed normally.
 269 .SH ALGORITHM
 270 The approach used in this program enables it to run an order of magnitude
 271 faster than any other "dependency generator" I have ever seen.
 272 Central to this performance are two assumptions:
 273 that all files compiled by a single
 274 makefile will be compiled with roughly the same
 275 .I -I
 276 and
 277 .I -D
 278 options;
 279 and that most files in a single directory will include largely the
 280 same files.
 281 .PP
 282 Given these assumptions,
 283 .B makedepend
 284 expects to be called once for each makefile, with
 285 all source files that are maintained by the
 286 makefile appearing on the command line.
 287 It parses each source and include
 288 file exactly once, maintaining an internal symbol table
 289 for each.
 290 Thus, the first file on the command line will take an amount of time
 291 proportional to the amount of time that a normal C preprocessor takes.
 292 But on subsequent files, if it encounter's an include file
 293 that it has already parsed, it does not parse it again.
 294 .PP
 295 For example,
 296 imagine you are compiling two files,
 297 .I file1.c
 298 and
 299 .I file2.c,
 300 they each include the header file
 301 .I header.h,
 302 and the file
 303 .I header.h
 304 in turn includes the files
 305 .I def1.h
 306 and
 307 .I def2.h.
 308 When you run the command
 309 .sp
 310     makedepend\0file1.c\0file2.c
 311 .sp
 312 .B makedepend
 313 will parse
 314 .I file1.c
 315 and consequently,
 316 .I header.h
 317 and then
 318 .I def1.h
 319 and
 320 .I def2.h.
 321 It then decides that the dependencies for this file are
 322 .sp
 323     file1.o:\0header.h\0def1.h\0def2.h
 324 .sp
 325 But when the program parses
 326 .I file2.c
 327 and discovers that it, too, includes
 328 .I header.h,
 329 it does not parse the file,
 330 but simply adds
 331 .I header.h,
 332 .I def1.h
 333 and
 334 .I def2.h
 335 to the list of dependencies for
 336 .I file2.o.
 337 .SH "SEE ALSO"
 338 cc(1), make(1)
 339 .SH BUGS
 340 .B makedepend
 341 parses, but does not currently evaluate, the SVR4
 342 #predicate(token-list) preprocessor expression;
 343 such expressions are simply assumed to be true.
 344 This may cause the wrong
 345 .I #include
 346 directives to be evaluated.
 347 .PP
 348 Imagine you are parsing two files,
 349 say
 350 .I file1.c
 351 and
 352 .I file2.c,
 353 each includes the file
 354 .I def.h.
 355 The list of files that
 356 .I def.h
 357 includes might truly be different when
 358 .I def.h
 359 is included by
 360 .I file1.c
 361 than when it is included by
 362 .I file2.c.
 363 But once
 364 .B makedepend
 365 arrives at a list of dependencies for a file,
 366 it is cast in concrete.
 367 .SH AUTHOR
 368 Todd Brunhoff, Tektronix, Inc. and MIT Project Athena