makedepend/makedepend.man

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