bringing in testkit tools
[feisty_meow.git] / nucleus / tools / dependency_tool / makedepend.txt
1
2
3
4 User Commands                                       MAKEDEPEND(1)
5
6
7
8 N\bNA\bAM\bME\bE
9      makedepend - create dependencies in makefiles
10
11 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
12      m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  [  -\b-D\bDn\bna\bam\bme\be=\b=d\bde\bef\bf  ]  [  -\b-D\bDn\bna\bam\bme\be ] [ -\b-I\bIi\bin\bnc\bcl\blu\bud\bde\bed\bdi\bir\br ] [
13      -\b-Y\bYi\bin\bnc\bcl\blu\bud\bde\bed\bdi\bir\br ] [ -\b-a\ba ] [ -\b-f\bfm\bma\bak\bke\bef\bfi\bil\ble\be ] [ -\b-o\boo\bob\bbj\bjs\bsu\buf\bff\bfi\bix\bx ] [ -\b-p\bpo\bob\bb-\b-
14      j\bjp\bpr\bre\bef\bfi\bix\bx  ]  [ -\b-s\bss\bst\btr\bri\bin\bng\bg ] [ -\b-w\bww\bwi\bid\bdt\bth\bh ] [ -\b-v\bv ] [ -\b-m\bm ] [ -- o\bot\bth\bh-\b-
15      e\ber\bro\bop\bpt\bti\bio\bon\bns\bs -- ] sourcefile ...
16
17 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
18      M\bMa\bak\bke\bed\bde\bep\bpe\ben\bnd\bd reads each _\bs_\bo_\bu_\br_\bc_\be_\bf_\bi_\bl_\be in sequence and  parses  it
19      like  a  C-preprocessor,  processing  all _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be_\b, _\b#_\bd_\be_\bf_\bi_\bn_\be_\b,
20      _\b#_\bu_\bn_\bd_\be_\bf_\b, _\b#_\bi_\bf_\bd_\be_\bf_\b, _\b#_\bi_\bf_\bn_\bd_\be_\bf_\b, _\b#_\be_\bn_\bd_\bi_\bf_\b, _\b#_\bi_\bf and _\b#_\be_\bl_\bs_\be directives so
21      that  it can correctly tell which _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be_\b, directives would
22      be used in a compilation.  Any _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be_\b, directives can ref-
23      erence  files  having other _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be directives, and parsing
24      will occur in these files as well.
25
26      Every file that a _\bs_\bo_\bu_\br_\bc_\be_\bf_\bi_\bl_\be  includes,  directly  or  indi-
27      rectly,  is  what  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  calls  a "dependency".  These
28      dependencies are then written to a _\bm_\ba_\bk_\be_\bf_\bi_\bl_\be in  such  a  way
29      that m\bma\bak\bke\be(\b(1\b1)\b) will know which object files must be recompiled
30      when a dependency has changed.
31
32      By default, m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd places its output in the  file  named
33      _\bm_\ba_\bk_\be_\bf_\bi_\bl_\be  if  it  exists,  otherwise _\bM_\ba_\bk_\be_\bf_\bi_\bl_\be_\b.  An alternate
34      makefile may be specified with  the  -\b-f\bf  option.   It  first
35      searches the makefile for the line
36
37          #  DO NOT DELETE THIS LINE -- make depend depends on it.
38
39      or one provided with the -\b-s\bs option, as a delimiter  for  the
40      dependency  output.   If  it finds it, it will delete every-
41      thing following this to the end of the makefile and put  the
42      output  after this line.  If it doesn't find it, the program
43      will append the string to the end of the makefile and  place
44      the output following that.  For each _\bs_\bo_\bu_\br_\bc_\be_\bf_\bi_\bl_\be appearing on
45      the command line, m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd puts lines in the  makefile  of
46      the form
47
48           sourcefile.o: dfile ...
49
50      Where  "sourcefile.o" is the name from the command line with
51      its suffix replaced with ".o", and "dfile" is  a  dependency
52      discovered  in a _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be directive while parsing _\bs_\bo_\bu_\br_\bc_\be_\bf_\bi_\bl_\be
53      or one of the files it included.
54
55 E\bEX\bXA\bAM\bMP\bPL\bLE\bE
56      Normally, m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd will be used in a  makefile  target  so
57      that  typing "make depend" will bring the dependencies up to
58      date for the makefile.  For example,
59          SRCS = file1.c file2.c ...
60
61
62
63 X Version 11          Last change: Release 6                    1
64
65
66
67
68
69
70 User Commands                                       MAKEDEPEND(1)
71
72
73
74          CFLAGS = -O -DHACK -I../foobar -xyz
75          depend:
76                  makedepend -- $(CFLAGS) -- $(SRCS)
77
78 O\bOP\bPT\bTI\bIO\bON\bNS\bS
79      M\bMa\bak\bke\bed\bde\bep\bpe\ben\bnd\bd will ignore any option that it  does  not  under-
80      stand  so that you may use the same arguments that you would
81      for c\bcc\bc(\b(1\b1)\b).\b.
82
83      -\b-D\bDn\bna\bam\bme\be=\b=d\bde\bef\bf o\bor\br -\b-D\bDn\bna\bam\bme\be
84           Define.  This places a definition for _\bn_\ba_\bm_\be  in  m\bma\bak\bke\bed\bde\be-\b-
85           p\bpe\ben\bnd\bd'\b's\bs  symbol  table.  Without _\b=_\bd_\be_\bf the symbol becomes
86           defined as "1".
87
88      -\b-I\bIi\bin\bnc\bcl\blu\bud\bde\bed\bdi\bir\br
89           Include directory.  This  option  tells  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  to
90           prepend _\bi_\bn_\bc_\bl_\bu_\bd_\be_\bd_\bi_\br to its list of directories to search
91           when it encounters a _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be directive.   By  default,
92           m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  only searches the standard include directo-
93           ries (usually /usr/include  and  possibly  a  compiler-
94           dependent directory).
95
96      -\b-Y\bYi\bin\bnc\bcl\blu\bud\bde\bed\bdi\bir\br
97           Replace  all  of  the standard include directories with
98           the single specified include directory;  you  can  omit
99           the _\bi_\bn_\bc_\bl_\bu_\bd_\be_\bd_\bi_\br to simply prevent searching the standard
100           include directories.
101
102      -\b-a\ba   Append the dependencies to the end of the file  instead
103           of replacing them.
104
105      -\b-f\bfm\bma\bak\bke\bef\bfi\bil\ble\be
106           Filename.   This  allows  you  to  specify an alternate
107           makefile in which m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd can place its output.
108
109      -\b-o\boo\bob\bbj\bjs\bsu\buf\bff\bfi\bix\bx
110           Object file suffix.  Some systems may have object files
111           whose suffix is something other than ".o".  This option
112           allows you to specify another suffix, such as ".b" with
113           _\b-_\bo_\b._\bb or ":obj" with _\b-_\bo_\b:_\bo_\bb_\bj and so forth.
114
115      -\b-p\bpo\bob\bbj\bjp\bpr\bre\bef\bfi\bix\bx
116           Object  file  prefix.   The  prefix is prepended to the
117           name of the object file. This is usually used to desig-
118           nate  a  different  directory for the object file.  The
119           default is the empty string.
120
121      -\b-s\bss\bst\btr\bri\bin\bng\bg
122           Starting string delimiter.  This option permits you  to
123           specify  a  different string for m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd to look for
124           in the makefile.
125
126
127
128
129 X Version 11          Last change: Release 6                    2
130
131
132
133
134
135
136 User Commands                                       MAKEDEPEND(1)
137
138
139
140      -\b-w\bww\bwi\bid\bdt\bth\bh
141           Line width.   Normally,  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  will  ensure  that
142           every  output line that it writes will be no wider than
143           78 characters for the sake of readability.  This option
144           enables you to change this width.
145
146      -\b-v\bv   Verbose  operation.   This  option causes m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd to
147           emit the list of files included by each input  file  on
148           standard output.
149
150      -\b-m\bm   Warn  about  multiple  inclusion.   This  option causes
151           m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd to produce  a  warning  if  any  input  file
152           includes another file more than once.  In previous ver-
153           sions of m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd this was the default behavior;  the
154           default  has  been changed to better match the behavior
155           of the C compiler, which  does  not  consider  multiple
156           inclusion  to be an error.  This option is provided for
157           backward compatibility, and to aid in  debugging  prob-
158           lems related to multiple inclusion.
159
160      -\b--\b- o\bop\bpt\bti\bio\bon\bns\bs -\b--\b-
161           If  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  encounters  a double hyphen (--) in the
162           argument list, then any unrecognized argument following
163           it  will  be  silently  ignored; a second double hyphen
164           terminates  this  special  treatment.   In  this   way,
165           m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  can  be made to safely ignore esoteric com-
166           piler arguments that  might  normally  be  found  in  a
167           CFLAGS m\bma\bak\bke\be macro (see the E\bEX\bXA\bAM\bMP\bPL\bLE\bE section above).  All
168           options that m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd recognizes and  appear  between
169           the pair of double hyphens are processed normally.
170
171 A\bAL\bLG\bGO\bOR\bRI\bIT\bTH\bHM\bM
172      The approach used in this program enables it to run an order
173      of magnitude faster than any other "dependency generator"  I
174      have ever seen.  Central to this performance are two assump-
175      tions: that all files compiled by a single makefile will  be
176      compiled  with  roughly the same _\b-_\bI and _\b-_\bD options; and that
177      most files in a single directory will  include  largely  the
178      same files.
179
180      Given  these  assumptions,  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  expects to be called
181      once for each makefile, with all source files that are main-
182      tained  by  the  makefile appearing on the command line.  It
183      parses each source and include file exactly once,  maintain-
184      ing an internal symbol table for each.  Thus, the first file
185      on the command line will take an amount of time proportional
186      to  the  amount  of time that a normal C preprocessor takes.
187      But on subsequent files, if it encounter's an  include  file
188      that it has already parsed, it does not parse it again.
189
190      For  example,  imagine  you are compiling two files, _\bf_\bi_\bl_\be_\b1_\b._\bc
191      and _\bf_\bi_\bl_\be_\b2_\b._\bc_\b, they each include the header file _\bh_\be_\ba_\bd_\be_\br_\b._\bh_\b, and
192
193
194
195 X Version 11          Last change: Release 6                    3
196
197
198
199
200
201
202 User Commands                                       MAKEDEPEND(1)
203
204
205
206      the  file  _\bh_\be_\ba_\bd_\be_\br_\b._\bh  in  turn  includes the files _\bd_\be_\bf_\b1_\b._\bh and
207      _\bd_\be_\bf_\b2_\b._\bh_\b.  When you run the command
208
209          makedepend file1.c file2.c
210
211      m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd will parse _\bf_\bi_\bl_\be_\b1_\b._\bc and consequently, _\bh_\be_\ba_\bd_\be_\br_\b._\bh and
212      then  _\bd_\be_\bf_\b1_\b._\bh and _\bd_\be_\bf_\b2_\b._\bh_\b.  It then decides that the dependen-
213      cies for this file are
214
215          file1.o: header.h def1.h def2.h
216
217      But when the program parses _\bf_\bi_\bl_\be_\b2_\b._\bc and discovers  that  it,
218      too, includes _\bh_\be_\ba_\bd_\be_\br_\b._\bh_\b, it does not parse the file, but sim-
219      ply adds _\bh_\be_\ba_\bd_\be_\br_\b._\bh_\b, _\bd_\be_\bf_\b1_\b._\bh and _\bd_\be_\bf_\b2_\b._\bh to the list  of  depen-
220      dencies for _\bf_\bi_\bl_\be_\b2_\b._\bo_\b.
221
222 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
223      cc(1), make(1)
224
225 B\bBU\bUG\bGS\bS
226      m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd parses, but does not currently evaluate, the SVR4
227      #predicate(token-list) preprocessor expression; such expres-
228      sions  are  simply  assumed  to be true.  This may cause the
229      wrong _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be directives to be evaluated.
230
231      Imagine you are parsing two files, say _\bf_\bi_\bl_\be_\b1_\b._\bc and  _\bf_\bi_\bl_\be_\b2_\b._\bc_\b,
232      each  includes the file _\bd_\be_\bf_\b._\bh_\b.  The list of files that _\bd_\be_\bf_\b._\bh
233      includes might truly be different when _\bd_\be_\bf_\b._\bh is included  by
234      _\bf_\bi_\bl_\be_\b1_\b._\bc  than  when  it  is  included  by _\bf_\bi_\bl_\be_\b2_\b._\bc_\b.  But once
235      m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd arrives at a list of dependencies for a file,  it
236      is cast in concrete.
237
238 A\bAU\bUT\bTH\bHO\bOR\bR
239      Todd Brunhoff, Tektronix, Inc. and MIT Project Athena
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261 X Version 11          Last change: Release 6                    4
262
263
264