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 |