/js/lib/Socket.IO-node/support/expresso/deps/jscoverage/js/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
 31makedepend \- 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
 69The
 70.B makedepend
 71program reads each
 72.I sourcefile
 73in sequence and parses it like a C-preprocessor,
 74processing 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
 83and
 84.I #else
 85directives so that it can correctly tell which
 86.I #include,
 87directives would be used in a compilation.
 88Any
 89.I #include,
 90directives can reference files having other
 91.I #include
 92directives, and parsing will occur in these files as well.
 93.PP
 94Every file that a
 95.I sourcefile
 96includes,
 97directly or indirectly,
 98is what
 99.B makedepend
100calls a \fIdependency.\fP
101These dependencies are then written to a
102.I makefile
103in such a way that
104.B make(1)
105will know which object files must be recompiled when a dependency has changed.
106.PP
107By default,
108.B makedepend
109places its output in the file named
110.I makefile
111if it exists, otherwise
112.I Makefile.
113An alternate makefile may be specified with the
114.B \-f
115option.
116It first searches the makefile for
117the line
118.sp
119\&    # DO NOT DELETE THIS LINE \-\^\- make depend depends on it.
120.sp
121or one provided with the
122.B \-s
123option,
124as a delimiter for the dependency output.
125If it finds it, it will delete everything
126following this to the end of the makefile
127and put the output after this line.
128If it doesn't find it, the program
129will append the string to the end of the makefile
130and place the output following that.
131For each
132.I sourcefile
133appearing on the command line,
134.B makedepend
135puts lines in the makefile of the form
136.sp
137     sourcefile.o:\0dfile .\|.\|.
138.sp
139Where \fIsourcefile.o\fP is the name from the command
140line with its suffix replaced with ``.o'',
141and \fIdfile\fP is a dependency discovered in a
142.I #include
143directive while parsing
144.I sourcefile
145or one of the files it included.
146.SH EXAMPLE
147Normally,
148.B makedepend
149will be used in a makefile target so that typing ``make depend'' will
150bring the dependencies up to date for the makefile.
151For 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
159The program
160will ignore any option that it does not understand so that you may use
161the 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
165Define.
166This places a definition for
167.I name
168in
169.B makedepend's
170symbol table.
171Without 
172.I =def\|
173the symbol becomes defined as ``1''.
174.TP 5
175.B \-I\fIincludedir\fP
176Include directory.
177This option tells
178.B makedepend
179to prepend
180.I includedir
181to its list of directories to search when it encounters
182a
183.I #include
184directive.
185By default,
186.B makedepend
187only searches the standard include directories (usually /usr/include
188and possibly a compiler-dependent directory).
189.TP 5
190.B \-Y\fIincludedir\fP
191Replace all of the standard include directories with the single specified
192include directory; you can omit the
193.I includedir
194to simply prevent searching the standard include directories.
195.TP 5
196.B \-a
197Append the dependencies to the end of the file instead of replacing them. 
198.TP 5
199.B \-f\fImakefile\fP
200Filename.
201This allows you to specify an alternate makefile in which
202.B makedepend
203can place its output.
204Specifying ``\-'' as the file name (i.e., \fB\-f\-\fP) sends the
205output to standard output instead of modifying an existing file.
206.TP 5
207.B \-include \fIfile\fP
208Process file as input, and include all the resulting output
209before processing the regular input file. This has the same
210affect as if the specified file is an include statement that
211appears before the very first line of the regular input file.
212.TP 5
213.B \-o\fIobjsuffix\fP
214Object file suffix.
215Some systems may have object files whose suffix is something other
216than ``.o''.
217This option allows you to specify another suffix, such as
218``.b'' with
219.I \-o.b
220or ``:obj''
221with
222.I \-o:obj
223and so forth.
224.TP 5
225.B \-p\fIobjprefix\fP
226Object file prefix.
227The prefix is prepended to the name of the object file. This is
228usually used to designate a different directory for the object file.
229The default is the empty string.
230.TP 5
231.B \-s\fIstring\fP
232Starting string delimiter.
233This option permits you to specify
234a different string for
235.B makedepend
236to look for in the makefile.
237.TP 5
238.B \-w\fIwidth\fP
239Line width.
240Normally,
241.B makedepend
242will ensure that every output line that it writes will be no wider than
24378 characters for the sake of readability.
244This option enables you to change this width.
245.TP 5
246.B \-v
247Verbose operation.
248This option causes 
249.B makedepend
250to emit the list of files included by each input file.
251.TP 5
252.B \-m
253Warn about multiple inclusion.
254This option causes 
255.B makedepend
256to produce a warning if any input file includes another file more than
257once.  In previous versions of 
258.B makedepend
259this was the default behavior; the default has been changed to better
260match the behavior of the C compiler, which does not consider multiple
261inclusion to be an error.  This option is provided for backward 
262compatibility, and to aid in debugging problems related to multiple
263inclusion.
264.TP 5
265.B "\-\^\- \fIoptions\fP \-\^\-"
266If
267.B makedepend
268encounters a double hyphen (\-\^\-) in the argument list,
269then any unrecognized argument following it
270will be silently ignored; a second double hyphen terminates this
271special treatment.
272In this way,
273.B makedepend
274can be made to safely ignore esoteric compiler arguments that might
275normally be found in a CFLAGS
276.B make
277macro (see the
278.B EXAMPLE
279section above).
280All options that
281.B makedepend
282recognizes and appear between the pair of double hyphens
283are processed normally.
284.SH ALGORITHM
285The approach used in this program enables it to run an order of magnitude
286faster than any other ``dependency generator'' I have ever seen.
287Central to this performance are two assumptions:
288that all files compiled by a single
289makefile will be compiled with roughly the same
290.I \-I
291and
292.I \-D
293options;
294and that most files in a single directory will include largely the
295same files.
296.PP
297Given these assumptions,
298.B makedepend
299expects to be called once for each makefile, with
300all source files that are maintained by the
301makefile appearing on the command line.
302It parses each source and include
303file exactly once, maintaining an internal symbol table
304for each.
305Thus, the first file on the command line will take an amount of time
306proportional to the amount of time that a normal C preprocessor takes.
307But on subsequent files, if it encounters an include file
308that it has already parsed, it does not parse it again.
309.PP
310For example,
311imagine you are compiling two files,
312.I file1.c
313and
314.I file2.c,
315they each include the header file
316.I header.h,
317and the file
318.I header.h
319in turn includes the files
320.I def1.h
321and
322.I def2.h.
323When you run the command
324.sp
325    makedepend\0file1.c\0file2.c
326.sp
327.B makedepend
328will parse
329.I file1.c
330and consequently,
331.I header.h
332and then
333.I def1.h
334and
335.I def2.h.
336It then decides that the dependencies for this file are
337.sp
338    file1.o:\0header.h\0def1.h\0def2.h
339.sp
340But when the program parses
341.I file2.c
342and discovers that it, too, includes
343.I header.h,
344it does not parse the file,
345but simply adds
346.I header.h,
347.I def1.h
348and
349.I def2.h
350to the list of dependencies for
351.I file2.o.
352.SH "SEE ALSO"
353cc(1), make(1)
354.SH BUGS
355.B makedepend
356parses, but does not currently evaluate, the SVR4 #predicate(token-list)
357preprocessor expression; such expressions are simply assumed to be true.
358This may cause the wrong
359.I #include
360directives to be evaluated.
361.PP
362Imagine you are parsing two files,
363say
364.I file1.c
365and
366.I file2.c,
367each includes the file
368.I def.h.
369The list of files that
370.I def.h
371includes might truly be different when
372.I def.h
373is included by
374.I file1.c
375than when it is included by
376.I file2.c.
377But once
378.B makedepend
379arrives at a list of dependencies for a file,
380it is cast in concrete.
381.SH AUTHOR
382Todd Brunhoff, Tektronix, Inc. and MIT Project Athena