cde/config/makedepend/mkdepend.man

   1 .\" $TOG: mkdepend.man /main/20 1998/02/06 11:10:18 kaleb $
   2 .\" Copyright (c) 1993, 1994, 1998 The Open Group
   3 .\"
   4 .\" All Rights Reserved.
   5 .\"
   6 .\" The above copyright notice and this permission notice shall be included in
   7 .\" all copies or substantial portions of the Software.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  10 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  11 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  12 .\" THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  13 .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  14 .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  15 .\" SOFTWARE.
  16 .\"
  17 .\" Except as contained in this notice, the name of The Open Group shall not
  18 .\" be used in advertising or otherwise to promote the sale, use or other
  19 .\" dealing in this Software without prior written authorization from The
  20 .\" Open Group.
  21 .TH MAKEDEPEND 1 "Release 6.4" "X Version 11"
  22 .UC 4
  23 .SH NAME
  24 makedepend \- create dependencies in makefiles
  25 .SH SYNOPSIS
  26 .B makedepend
  27 [
  28 .BI \-D name\fB=\fPdef
  29 ] [
  30 .BI \-D name
  31 ] [
  32 .BI \-I includedir
  33 ] [
  34 .BI \-Y includedir
  35 ] [
  36 .B \-a
  37 ] [
  38 .BI \-f makefile
  39 ] [
  40 .BI \-o objsuffix
  41 ] [
  42 .BI \-p objprefix
  43 ] [
  44 .BI \-s string
  45 ] [
  46 .BI \-w width
  47 ] [
  48 .B \-v
  49 ] [
  50 .B \-m
  51 ] [
  52 \-\^\-
  53 .I otheroptions
  54 \-\^\-
  55 ]
  56 .I sourcefile
  57 \&.\|.\|.
  58 .br
  59 .SH DESCRIPTION
  60 The
  61 .B makedepend
  62 program reads each
  63 .I sourcefile
  64 in sequence and parses it like a C-preprocessor,
  65 processing all
  66 .I #include,
  67 .I #define,
  68 .I #undef,
  69 .I #ifdef,
  70 .I #ifndef,
  71 .I #endif,
  72 .I #if,
  73 .I #elif
  74 and
  75 .I #else
  76 directives so that it can correctly tell which
  77 .I #include,
  78 directives would be used in a compilation.
  79 Any
  80 .I #include,
  81 directives can reference files having other
  82 .I #include
  83 directives, and parsing will occur in these files as well.
  84 .PP
  85 Every file that a
  86 .I sourcefile
  87 includes,
  88 directly or indirectly,
  89 is what
  90 .B makedepend
  91 calls a \fIdependency.\fP
  92 These dependencies are then written to a
  93 .I makefile
  94 in such a way that
  95 .B make(1)
  96 will know which object files must be recompiled when a dependency has changed.
  97 .PP
  98 By default,
  99 .B makedepend
 100 places its output in the file named
 101 .I makefile
 102 if it exists, otherwise
 103 .I Makefile.
 104 An alternate makefile may be specified with the
 105 .B \-f
 106 option.
 107 It first searches the makefile for
 108 the line
 109 .sp
 110     # DO NOT DELETE THIS LINE \-\^\- make depend depends on it.
 111 .sp
 112 or one provided with the
 113 .B \-s
 114 option,
 115 as a delimiter for the dependency output.
 116 If it finds it, it will delete everything
 117 following this to the end of the makefile
 118 and put the output after this line.
 119 If it doesn't find it, the program
 120 will append the string to the end of the makefile
 121 and place the output following that.
 122 For each
 123 .I sourcefile
 124 appearing on the command line,
 125 .B makedepend
 126 puts lines in the makefile of the form
 127 .sp
 128      sourcefile.o:\0dfile .\|.\|.
 129 .sp
 130 Where \fIsourcefile.o\fP is the name from the command
 131 line with its suffix replaced with ``.o'',
 132 and \fIdfile\fP is a dependency discovered in a
 133 .I #include
 134 directive while parsing
 135 .I sourcefile
 136 or one of the files it included.
 137 .SH EXAMPLE
 138 Normally,
 139 .B makedepend
 140 will be used in a makefile target so that typing ``make depend'' will
 141 bring the dependencies up to date for the makefile.
 142 For example,
 143 .nf
 144     SRCS\0=\0file1.c\0file2.c\0.\|.\|.
 145     CFLAGS\0=\0\-O\0\-DHACK\0\-I\^.\^.\^/foobar\0\-xyz
 146     depend:
 147             makedepend\0\-\^\-\0$(CFLAGS)\0\-\^\-\0$(SRCS)
 148 .fi
 149 .SH OPTIONS
 150 The program
 151 will ignore any option that it does not understand so that you may use
 152 the same arguments that you would for
 153 .B cc(1).
 154 .TP 5
 155 .B \-D\fIname\fP=\fIdef\fP \fRor\fP \-D\fIname\fP
 156 Define.
 157 This places a definition for
 158 .I name
 159 in
 160 .B makedepend's
 161 symbol table.
 162 Without
 163 .I =def\|
 164 the symbol becomes defined as ``1''.
 165 .TP 5
 166 .B \-I\fIincludedir\fP
 167 Include directory.
 168 This option tells
 169 .B makedepend
 170 to prepend
 171 .I includedir
 172 to its list of directories to search when it encounters
 173 a
 174 .I #include
 175 directive.
 176 By default,
 177 .B makedepend
 178 only searches the standard include directories (usually /usr/include
 179 and possibly a compiler-dependent directory).
 180 .TP 5
 181 .B \-Y\fIincludedir\fP
 182 Replace all of the standard include directories with the single specified
 183 include directory; you can omit the
 184 .I includedir
 185 to simply prevent searching the standard include directories.
 186 .TP 5
 187 .B \-a
 188 Append the dependencies to the end of the file instead of replacing them.
 189 .TP 5
 190 .B \-f\fImakefile\fP
 191 Filename.
 192 This allows you to specify an alternate makefile in which
 193 .B makedepend
 194 can place its output.
 195 Specifying ``\-'' as the file name (i.e., \fB\-f\-\fP) sends the
 196 output to standard output instead of modifying an existing file.
 197 .TP 5
 198 .B \-o\fIobjsuffix\fP
 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 \-p\fIobjprefix\fP
 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 \-s\fIstring\fP
 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 \-w\fIwidth\fP
 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 "\-\^\- \fIoptions\fP \-\^\-"
 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 encounters 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