js/src/config/mkdepend/mkdepend.man

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