1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/coreconf/mkdepend/mkdepend.man Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,382 @@
1.4 +.\" $Xorg: mkdepend.man,v 1.5 2001/02/09 02:03:16 xorgcvs Exp $
1.5 +.\" Copyright (c) 1993, 1994, 1998 The Open Group
1.6 +.\"
1.7 +.\" Permission to use, copy, modify, distribute, and sell this software and its
1.8 +.\" documentation for any purpose is hereby granted without fee, provided that
1.9 +.\" the above copyright notice appear in all copies and that both that
1.10 +.\" copyright notice and this permission notice appear in supporting
1.11 +.\" documentation.
1.12 +.\"
1.13 +.\" The above copyright notice and this permission notice shall be included in
1.14 +.\" all copies or substantial portions of the Software.
1.15 +.\"
1.16 +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1.17 +.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1.18 +.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
1.19 +.\" THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
1.20 +.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
1.21 +.\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1.22 +.\" SOFTWARE.
1.23 +.\"
1.24 +.\" Except as contained in this notice, the name of The Open Group shall not
1.25 +.\" be used in advertising or otherwise to promote the sale, use or other
1.26 +.\" dealing in this Software without prior written authorization from The
1.27 +.\" Open Group.
1.28 +.\"
1.29 +.\" $XFree86: xc/config/makedepend/mkdepend.man,v 1.7 2002/12/14 02:39:45 dawes Exp $
1.30 +.\"
1.31 +.TH MAKEDEPEND 1 __xorgversion__
1.32 +.UC 4
1.33 +.SH NAME
1.34 +makedepend \- create dependencies in makefiles
1.35 +.SH SYNOPSIS
1.36 +.B makedepend
1.37 +[
1.38 +.BI \-D name\fB=\fPdef
1.39 +] [
1.40 +.BI \-D name
1.41 +] [
1.42 +.BI \-I includedir
1.43 +] [
1.44 +.BI \-Y includedir
1.45 +] [
1.46 +.B \-a
1.47 +] [
1.48 +.BI \-f makefile
1.49 +] [
1.50 +.BI \-include \ file
1.51 +] [
1.52 +.BI \-o objsuffix
1.53 +] [
1.54 +.BI \-p objprefix
1.55 +] [
1.56 +.BI \-s string
1.57 +] [
1.58 +.BI \-w width
1.59 +] [
1.60 +.B \-v
1.61 +] [
1.62 +.B \-m
1.63 +] [
1.64 +\-\^\-
1.65 +.I otheroptions
1.66 +\-\^\-
1.67 +]
1.68 +.I sourcefile
1.69 +\&.\|.\|.
1.70 +.br
1.71 +.SH DESCRIPTION
1.72 +The
1.73 +.B makedepend
1.74 +program reads each
1.75 +.I sourcefile
1.76 +in sequence and parses it like a C-preprocessor,
1.77 +processing all
1.78 +.I #include,
1.79 +.I #define,
1.80 +.I #undef,
1.81 +.I #ifdef,
1.82 +.I #ifndef,
1.83 +.I #endif,
1.84 +.I #if,
1.85 +.I #elif
1.86 +and
1.87 +.I #else
1.88 +directives so that it can correctly tell which
1.89 +.I #include,
1.90 +directives would be used in a compilation.
1.91 +Any
1.92 +.I #include,
1.93 +directives can reference files having other
1.94 +.I #include
1.95 +directives, and parsing will occur in these files as well.
1.96 +.PP
1.97 +Every file that a
1.98 +.I sourcefile
1.99 +includes,
1.100 +directly or indirectly,
1.101 +is what
1.102 +.B makedepend
1.103 +calls a \fIdependency.\fP
1.104 +These dependencies are then written to a
1.105 +.I makefile
1.106 +in such a way that
1.107 +.B make(1)
1.108 +will know which object files must be recompiled when a dependency has changed.
1.109 +.PP
1.110 +By default,
1.111 +.B makedepend
1.112 +places its output in the file named
1.113 +.I makefile
1.114 +if it exists, otherwise
1.115 +.I Makefile.
1.116 +An alternate makefile may be specified with the
1.117 +.B \-f
1.118 +option.
1.119 +It first searches the makefile for
1.120 +the line
1.121 +.sp
1.122 +\& # DO NOT DELETE THIS LINE \-\^\- make depend depends on it.
1.123 +.sp
1.124 +or one provided with the
1.125 +.B \-s
1.126 +option,
1.127 +as a delimiter for the dependency output.
1.128 +If it finds it, it will delete everything
1.129 +following this to the end of the makefile
1.130 +and put the output after this line.
1.131 +If it doesn't find it, the program
1.132 +will append the string to the end of the makefile
1.133 +and place the output following that.
1.134 +For each
1.135 +.I sourcefile
1.136 +appearing on the command line,
1.137 +.B makedepend
1.138 +puts lines in the makefile of the form
1.139 +.sp
1.140 + sourcefile.o:\0dfile .\|.\|.
1.141 +.sp
1.142 +Where \fIsourcefile.o\fP is the name from the command
1.143 +line with its suffix replaced with ``.o'',
1.144 +and \fIdfile\fP is a dependency discovered in a
1.145 +.I #include
1.146 +directive while parsing
1.147 +.I sourcefile
1.148 +or one of the files it included.
1.149 +.SH EXAMPLE
1.150 +Normally,
1.151 +.B makedepend
1.152 +will be used in a makefile target so that typing ``make depend'' will
1.153 +bring the dependencies up to date for the makefile.
1.154 +For example,
1.155 +.nf
1.156 + SRCS\0=\0file1.c\0file2.c\0.\|.\|.
1.157 + CFLAGS\0=\0\-O\0\-DHACK\0\-I\^.\^.\^/foobar\0\-xyz
1.158 + depend:
1.159 + makedepend\0\-\^\-\0$(CFLAGS)\0\-\^\-\0$(SRCS)
1.160 +.fi
1.161 +.SH OPTIONS
1.162 +The program
1.163 +will ignore any option that it does not understand so that you may use
1.164 +the same arguments that you would for
1.165 +.B cc(1).
1.166 +.TP 5
1.167 +.B \-D\fIname\fP=\fIdef\fP \fRor\fP \-D\fIname\fP
1.168 +Define.
1.169 +This places a definition for
1.170 +.I name
1.171 +in
1.172 +.B makedepend's
1.173 +symbol table.
1.174 +Without
1.175 +.I =def\|
1.176 +the symbol becomes defined as ``1''.
1.177 +.TP 5
1.178 +.B \-I\fIincludedir\fP
1.179 +Include directory.
1.180 +This option tells
1.181 +.B makedepend
1.182 +to prepend
1.183 +.I includedir
1.184 +to its list of directories to search when it encounters
1.185 +a
1.186 +.I #include
1.187 +directive.
1.188 +By default,
1.189 +.B makedepend
1.190 +only searches the standard include directories (usually /usr/include
1.191 +and possibly a compiler-dependent directory).
1.192 +.TP 5
1.193 +.B \-Y\fIincludedir\fP
1.194 +Replace all of the standard include directories with the single specified
1.195 +include directory; you can omit the
1.196 +.I includedir
1.197 +to simply prevent searching the standard include directories.
1.198 +.TP 5
1.199 +.B \-a
1.200 +Append the dependencies to the end of the file instead of replacing them.
1.201 +.TP 5
1.202 +.B \-f\fImakefile\fP
1.203 +Filename.
1.204 +This allows you to specify an alternate makefile in which
1.205 +.B makedepend
1.206 +can place its output.
1.207 +Specifying ``\-'' as the file name (i.e., \fB\-f\-\fP) sends the
1.208 +output to standard output instead of modifying an existing file.
1.209 +.TP 5
1.210 +.B \-include \fIfile\fP
1.211 +Process file as input, and include all the resulting output
1.212 +before processing the regular input file. This has the same
1.213 +affect as if the specified file is an include statement that
1.214 +appears before the very first line of the regular input file.
1.215 +.TP 5
1.216 +.B \-o\fIobjsuffix\fP
1.217 +Object file suffix.
1.218 +Some systems may have object files whose suffix is something other
1.219 +than ``.o''.
1.220 +This option allows you to specify another suffix, such as
1.221 +``.b'' with
1.222 +.I \-o.b
1.223 +or ``:obj''
1.224 +with
1.225 +.I \-o:obj
1.226 +and so forth.
1.227 +.TP 5
1.228 +.B \-p\fIobjprefix\fP
1.229 +Object file prefix.
1.230 +The prefix is prepended to the name of the object file. This is
1.231 +usually used to designate a different directory for the object file.
1.232 +The default is the empty string.
1.233 +.TP 5
1.234 +.B \-s\fIstring\fP
1.235 +Starting string delimiter.
1.236 +This option permits you to specify
1.237 +a different string for
1.238 +.B makedepend
1.239 +to look for in the makefile.
1.240 +.TP 5
1.241 +.B \-w\fIwidth\fP
1.242 +Line width.
1.243 +Normally,
1.244 +.B makedepend
1.245 +will ensure that every output line that it writes will be no wider than
1.246 +78 characters for the sake of readability.
1.247 +This option enables you to change this width.
1.248 +.TP 5
1.249 +.B \-v
1.250 +Verbose operation.
1.251 +This option causes
1.252 +.B makedepend
1.253 +to emit the list of files included by each input file.
1.254 +.TP 5
1.255 +.B \-m
1.256 +Warn about multiple inclusion.
1.257 +This option causes
1.258 +.B makedepend
1.259 +to produce a warning if any input file includes another file more than
1.260 +once. In previous versions of
1.261 +.B makedepend
1.262 +this was the default behavior; the default has been changed to better
1.263 +match the behavior of the C compiler, which does not consider multiple
1.264 +inclusion to be an error. This option is provided for backward
1.265 +compatibility, and to aid in debugging problems related to multiple
1.266 +inclusion.
1.267 +.TP 5
1.268 +.B "\-\^\- \fIoptions\fP \-\^\-"
1.269 +If
1.270 +.B makedepend
1.271 +encounters a double hyphen (\-\^\-) in the argument list,
1.272 +then any unrecognized argument following it
1.273 +will be silently ignored; a second double hyphen terminates this
1.274 +special treatment.
1.275 +In this way,
1.276 +.B makedepend
1.277 +can be made to safely ignore esoteric compiler arguments that might
1.278 +normally be found in a CFLAGS
1.279 +.B make
1.280 +macro (see the
1.281 +.B EXAMPLE
1.282 +section above).
1.283 +All options that
1.284 +.B makedepend
1.285 +recognizes and appear between the pair of double hyphens
1.286 +are processed normally.
1.287 +.SH ALGORITHM
1.288 +The approach used in this program enables it to run an order of magnitude
1.289 +faster than any other ``dependency generator'' I have ever seen.
1.290 +Central to this performance are two assumptions:
1.291 +that all files compiled by a single
1.292 +makefile will be compiled with roughly the same
1.293 +.I \-I
1.294 +and
1.295 +.I \-D
1.296 +options;
1.297 +and that most files in a single directory will include largely the
1.298 +same files.
1.299 +.PP
1.300 +Given these assumptions,
1.301 +.B makedepend
1.302 +expects to be called once for each makefile, with
1.303 +all source files that are maintained by the
1.304 +makefile appearing on the command line.
1.305 +It parses each source and include
1.306 +file exactly once, maintaining an internal symbol table
1.307 +for each.
1.308 +Thus, the first file on the command line will take an amount of time
1.309 +proportional to the amount of time that a normal C preprocessor takes.
1.310 +But on subsequent files, if it encounters an include file
1.311 +that it has already parsed, it does not parse it again.
1.312 +.PP
1.313 +For example,
1.314 +imagine you are compiling two files,
1.315 +.I file1.c
1.316 +and
1.317 +.I file2.c,
1.318 +they each include the header file
1.319 +.I header.h,
1.320 +and the file
1.321 +.I header.h
1.322 +in turn includes the files
1.323 +.I def1.h
1.324 +and
1.325 +.I def2.h.
1.326 +When you run the command
1.327 +.sp
1.328 + makedepend\0file1.c\0file2.c
1.329 +.sp
1.330 +.B makedepend
1.331 +will parse
1.332 +.I file1.c
1.333 +and consequently,
1.334 +.I header.h
1.335 +and then
1.336 +.I def1.h
1.337 +and
1.338 +.I def2.h.
1.339 +It then decides that the dependencies for this file are
1.340 +.sp
1.341 + file1.o:\0header.h\0def1.h\0def2.h
1.342 +.sp
1.343 +But when the program parses
1.344 +.I file2.c
1.345 +and discovers that it, too, includes
1.346 +.I header.h,
1.347 +it does not parse the file,
1.348 +but simply adds
1.349 +.I header.h,
1.350 +.I def1.h
1.351 +and
1.352 +.I def2.h
1.353 +to the list of dependencies for
1.354 +.I file2.o.
1.355 +.SH "SEE ALSO"
1.356 +cc(1), make(1)
1.357 +.SH BUGS
1.358 +.B makedepend
1.359 +parses, but does not currently evaluate, the SVR4 #predicate(token-list)
1.360 +preprocessor expression; such expressions are simply assumed to be true.
1.361 +This may cause the wrong
1.362 +.I #include
1.363 +directives to be evaluated.
1.364 +.PP
1.365 +Imagine you are parsing two files,
1.366 +say
1.367 +.I file1.c
1.368 +and
1.369 +.I file2.c,
1.370 +each includes the file
1.371 +.I def.h.
1.372 +The list of files that
1.373 +.I def.h
1.374 +includes might truly be different when
1.375 +.I def.h
1.376 +is included by
1.377 +.I file1.c
1.378 +than when it is included by
1.379 +.I file2.c.
1.380 +But once
1.381 +.B makedepend
1.382 +arrives at a list of dependencies for a file,
1.383 +it is cast in concrete.
1.384 +.SH AUTHOR
1.385 +Todd Brunhoff, Tektronix, Inc. and MIT Project Athena
