| blob | 9c3cdccd988c38c8a03526adb8ff1cfe4f3673ca |
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