michael@0: .\" $Xorg: mkdepend.man,v 1.5 2001/02/09 02:03:16 xorgcvs Exp $
michael@0: .\" Copyright (c) 1993, 1994, 1998 The Open Group
michael@0: .\" 
michael@0: .\" Permission to use, copy, modify, distribute, and sell this software and its
michael@0: .\" documentation for any purpose is hereby granted without fee, provided that
michael@0: .\" the above copyright notice appear in all copies and that both that
michael@0: .\" copyright notice and this permission notice appear in supporting
michael@0: .\" documentation.
michael@0: .\" 
michael@0: .\" The above copyright notice and this permission notice shall be included in
michael@0: .\" all copies or substantial portions of the Software.
michael@0: .\" 
michael@0: .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
michael@0: .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
michael@0: .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL 
michael@0: .\" THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
michael@0: .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF 
michael@0: .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
michael@0: .\" SOFTWARE.
michael@0: .\" 
michael@0: .\" Except as contained in this notice, the name of The Open Group shall not 
michael@0: .\" be used in advertising or otherwise to promote the sale, use or other 
michael@0: .\" dealing in this Software without prior written authorization from The
michael@0: .\" Open Group.
michael@0: .\"
michael@0: .\" $XFree86: xc/config/makedepend/mkdepend.man,v 1.7 2002/12/14 02:39:45 dawes Exp $
michael@0: .\"
michael@0: .TH MAKEDEPEND 1 __xorgversion__
michael@0: .UC 4
michael@0: .SH NAME
michael@0: makedepend \- create dependencies in makefiles
michael@0: .SH SYNOPSIS
michael@0: .B makedepend
michael@0: [
michael@0: .BI \-D name\fB=\fPdef
michael@0: ] [
michael@0: .BI \-D name
michael@0: ] [
michael@0: .BI \-I includedir
michael@0: ] [
michael@0: .BI \-Y includedir
michael@0: ] [
michael@0: .B \-a
michael@0: ] [
michael@0: .BI \-f makefile
michael@0: ] [
michael@0: .BI \-include \ file
michael@0: ] [
michael@0: .BI \-o objsuffix
michael@0: ] [
michael@0: .BI \-p objprefix
michael@0: ] [
michael@0: .BI \-s string
michael@0: ] [
michael@0: .BI \-w width
michael@0: ] [
michael@0: .B \-v
michael@0: ] [
michael@0: .B \-m
michael@0: ] [
michael@0: \-\^\-
michael@0: .I otheroptions
michael@0: \-\^\-
michael@0: ]
michael@0: .I sourcefile
michael@0: \&.\|.\|.
michael@0: .br
michael@0: .SH DESCRIPTION
michael@0: The
michael@0: .B makedepend
michael@0: program reads each
michael@0: .I sourcefile
michael@0: in sequence and parses it like a C-preprocessor,
michael@0: processing all
michael@0: .I #include,
michael@0: .I #define,
michael@0: .I #undef,
michael@0: .I #ifdef,
michael@0: .I #ifndef,
michael@0: .I #endif,
michael@0: .I #if,
michael@0: .I #elif
michael@0: and
michael@0: .I #else
michael@0: directives so that it can correctly tell which
michael@0: .I #include,
michael@0: directives would be used in a compilation.
michael@0: Any
michael@0: .I #include,
michael@0: directives can reference files having other
michael@0: .I #include
michael@0: directives, and parsing will occur in these files as well.
michael@0: .PP
michael@0: Every file that a
michael@0: .I sourcefile
michael@0: includes,
michael@0: directly or indirectly,
michael@0: is what
michael@0: .B makedepend
michael@0: calls a \fIdependency.\fP
michael@0: These dependencies are then written to a
michael@0: .I makefile
michael@0: in such a way that
michael@0: .B make(1)
michael@0: will know which object files must be recompiled when a dependency has changed.
michael@0: .PP
michael@0: By default,
michael@0: .B makedepend
michael@0: places its output in the file named
michael@0: .I makefile
michael@0: if it exists, otherwise
michael@0: .I Makefile.
michael@0: An alternate makefile may be specified with the
michael@0: .B \-f
michael@0: option.
michael@0: It first searches the makefile for
michael@0: the line
michael@0: .sp
michael@0: \&    # DO NOT DELETE THIS LINE \-\^\- make depend depends on it.
michael@0: .sp
michael@0: or one provided with the
michael@0: .B \-s
michael@0: option,
michael@0: as a delimiter for the dependency output.
michael@0: If it finds it, it will delete everything
michael@0: following this to the end of the makefile
michael@0: and put the output after this line.
michael@0: If it doesn't find it, the program
michael@0: will append the string to the end of the makefile
michael@0: and place the output following that.
michael@0: For each
michael@0: .I sourcefile
michael@0: appearing on the command line,
michael@0: .B makedepend
michael@0: puts lines in the makefile of the form
michael@0: .sp
michael@0:      sourcefile.o:\0dfile .\|.\|.
michael@0: .sp
michael@0: Where \fIsourcefile.o\fP is the name from the command
michael@0: line with its suffix replaced with ``.o'',
michael@0: and \fIdfile\fP is a dependency discovered in a
michael@0: .I #include
michael@0: directive while parsing
michael@0: .I sourcefile
michael@0: or one of the files it included.
michael@0: .SH EXAMPLE
michael@0: Normally,
michael@0: .B makedepend
michael@0: will be used in a makefile target so that typing ``make depend'' will
michael@0: bring the dependencies up to date for the makefile.
michael@0: For example,
michael@0: .nf
michael@0:     SRCS\0=\0file1.c\0file2.c\0.\|.\|.
michael@0:     CFLAGS\0=\0\-O\0\-DHACK\0\-I\^.\^.\^/foobar\0\-xyz
michael@0:     depend:
michael@0:             makedepend\0\-\^\-\0$(CFLAGS)\0\-\^\-\0$(SRCS)
michael@0: .fi
michael@0: .SH OPTIONS
michael@0: The program
michael@0: will ignore any option that it does not understand so that you may use
michael@0: the same arguments that you would for
michael@0: .B cc(1).
michael@0: .TP 5
michael@0: .B \-D\fIname\fP=\fIdef\fP \fRor\fP \-D\fIname\fP
michael@0: Define.
michael@0: This places a definition for
michael@0: .I name
michael@0: in
michael@0: .B makedepend's
michael@0: symbol table.
michael@0: Without 
michael@0: .I =def\|
michael@0: the symbol becomes defined as ``1''.
michael@0: .TP 5
michael@0: .B \-I\fIincludedir\fP
michael@0: Include directory.
michael@0: This option tells
michael@0: .B makedepend
michael@0: to prepend
michael@0: .I includedir
michael@0: to its list of directories to search when it encounters
michael@0: a
michael@0: .I #include
michael@0: directive.
michael@0: By default,
michael@0: .B makedepend
michael@0: only searches the standard include directories (usually /usr/include
michael@0: and possibly a compiler-dependent directory).
michael@0: .TP 5
michael@0: .B \-Y\fIincludedir\fP
michael@0: Replace all of the standard include directories with the single specified
michael@0: include directory; you can omit the
michael@0: .I includedir
michael@0: to simply prevent searching the standard include directories.
michael@0: .TP 5
michael@0: .B \-a
michael@0: Append the dependencies to the end of the file instead of replacing them. 
michael@0: .TP 5
michael@0: .B \-f\fImakefile\fP
michael@0: Filename.
michael@0: This allows you to specify an alternate makefile in which
michael@0: .B makedepend
michael@0: can place its output.
michael@0: Specifying ``\-'' as the file name (i.e., \fB\-f\-\fP) sends the
michael@0: output to standard output instead of modifying an existing file.
michael@0: .TP 5
michael@0: .B \-include \fIfile\fP
michael@0: Process file as input, and include all the resulting output
michael@0: before processing the regular input file. This has the same
michael@0: affect as if the specified file is an include statement that
michael@0: appears before the very first line of the regular input file.
michael@0: .TP 5
michael@0: .B \-o\fIobjsuffix\fP
michael@0: Object file suffix.
michael@0: Some systems may have object files whose suffix is something other
michael@0: than ``.o''.
michael@0: This option allows you to specify another suffix, such as
michael@0: ``.b'' with
michael@0: .I \-o.b
michael@0: or ``:obj''
michael@0: with
michael@0: .I \-o:obj
michael@0: and so forth.
michael@0: .TP 5
michael@0: .B \-p\fIobjprefix\fP
michael@0: Object file prefix.
michael@0: The prefix is prepended to the name of the object file. This is
michael@0: usually used to designate a different directory for the object file.
michael@0: The default is the empty string.
michael@0: .TP 5
michael@0: .B \-s\fIstring\fP
michael@0: Starting string delimiter.
michael@0: This option permits you to specify
michael@0: a different string for
michael@0: .B makedepend
michael@0: to look for in the makefile.
michael@0: .TP 5
michael@0: .B \-w\fIwidth\fP
michael@0: Line width.
michael@0: Normally,
michael@0: .B makedepend
michael@0: will ensure that every output line that it writes will be no wider than
michael@0: 78 characters for the sake of readability.
michael@0: This option enables you to change this width.
michael@0: .TP 5
michael@0: .B \-v
michael@0: Verbose operation.
michael@0: This option causes 
michael@0: .B makedepend
michael@0: to emit the list of files included by each input file.
michael@0: .TP 5
michael@0: .B \-m
michael@0: Warn about multiple inclusion.
michael@0: This option causes 
michael@0: .B makedepend
michael@0: to produce a warning if any input file includes another file more than
michael@0: once.  In previous versions of 
michael@0: .B makedepend
michael@0: this was the default behavior; the default has been changed to better
michael@0: match the behavior of the C compiler, which does not consider multiple
michael@0: inclusion to be an error.  This option is provided for backward 
michael@0: compatibility, and to aid in debugging problems related to multiple
michael@0: inclusion.
michael@0: .TP 5
michael@0: .B "\-\^\- \fIoptions\fP \-\^\-"
michael@0: If
michael@0: .B makedepend
michael@0: encounters a double hyphen (\-\^\-) in the argument list,
michael@0: then any unrecognized argument following it
michael@0: will be silently ignored; a second double hyphen terminates this
michael@0: special treatment.
michael@0: In this way,
michael@0: .B makedepend
michael@0: can be made to safely ignore esoteric compiler arguments that might
michael@0: normally be found in a CFLAGS
michael@0: .B make
michael@0: macro (see the
michael@0: .B EXAMPLE
michael@0: section above).
michael@0: All options that
michael@0: .B makedepend
michael@0: recognizes and appear between the pair of double hyphens
michael@0: are processed normally.
michael@0: .SH ALGORITHM
michael@0: The approach used in this program enables it to run an order of magnitude
michael@0: faster than any other ``dependency generator'' I have ever seen.
michael@0: Central to this performance are two assumptions:
michael@0: that all files compiled by a single
michael@0: makefile will be compiled with roughly the same
michael@0: .I \-I
michael@0: and
michael@0: .I \-D
michael@0: options;
michael@0: and that most files in a single directory will include largely the
michael@0: same files.
michael@0: .PP
michael@0: Given these assumptions,
michael@0: .B makedepend
michael@0: expects to be called once for each makefile, with
michael@0: all source files that are maintained by the
michael@0: makefile appearing on the command line.
michael@0: It parses each source and include
michael@0: file exactly once, maintaining an internal symbol table
michael@0: for each.
michael@0: Thus, the first file on the command line will take an amount of time
michael@0: proportional to the amount of time that a normal C preprocessor takes.
michael@0: But on subsequent files, if it encounters an include file
michael@0: that it has already parsed, it does not parse it again.
michael@0: .PP
michael@0: For example,
michael@0: imagine you are compiling two files,
michael@0: .I file1.c
michael@0: and
michael@0: .I file2.c,
michael@0: they each include the header file
michael@0: .I header.h,
michael@0: and the file
michael@0: .I header.h
michael@0: in turn includes the files
michael@0: .I def1.h
michael@0: and
michael@0: .I def2.h.
michael@0: When you run the command
michael@0: .sp
michael@0:     makedepend\0file1.c\0file2.c
michael@0: .sp
michael@0: .B makedepend
michael@0: will parse
michael@0: .I file1.c
michael@0: and consequently,
michael@0: .I header.h
michael@0: and then
michael@0: .I def1.h
michael@0: and
michael@0: .I def2.h.
michael@0: It then decides that the dependencies for this file are
michael@0: .sp
michael@0:     file1.o:\0header.h\0def1.h\0def2.h
michael@0: .sp
michael@0: But when the program parses
michael@0: .I file2.c
michael@0: and discovers that it, too, includes
michael@0: .I header.h,
michael@0: it does not parse the file,
michael@0: but simply adds
michael@0: .I header.h,
michael@0: .I def1.h
michael@0: and
michael@0: .I def2.h
michael@0: to the list of dependencies for
michael@0: .I file2.o.
michael@0: .SH "SEE ALSO"
michael@0: cc(1), make(1)
michael@0: .SH BUGS
michael@0: .B makedepend
michael@0: parses, but does not currently evaluate, the SVR4 #predicate(token-list)
michael@0: preprocessor expression; such expressions are simply assumed to be true.
michael@0: This may cause the wrong
michael@0: .I #include
michael@0: directives to be evaluated.
michael@0: .PP
michael@0: Imagine you are parsing two files,
michael@0: say
michael@0: .I file1.c
michael@0: and
michael@0: .I file2.c,
michael@0: each includes the file
michael@0: .I def.h.
michael@0: The list of files that
michael@0: .I def.h
michael@0: includes might truly be different when
michael@0: .I def.h
michael@0: is included by
michael@0: .I file1.c
michael@0: than when it is included by
michael@0: .I file2.c.
michael@0: But once
michael@0: .B makedepend
michael@0: arrives at a list of dependencies for a file,
michael@0: it is cast in concrete.
michael@0: .SH AUTHOR
michael@0: Todd Brunhoff, Tektronix, Inc. and MIT Project Athena