bringing in testkit tools

[feisty_meow.git] / nucleus / tools / dependency_tool / makedepend.txt

User Commands                                       MAKEDEPEND(1)



N\bNA\bAM\bME\bE
     makedepend - create dependencies in makefiles

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
     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 ] [
     -\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-
     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-
     e\ber\bro\bop\bpt\bti\bio\bon\bns\bs -- ] sourcefile ...

D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
     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
     like  a  C-preprocessor,  processing  all _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be_\b, _\b#_\bd_\be_\bf_\bi_\bn_\be_\b,
     _\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
     that  it can correctly tell which _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be_\b, directives would
     be used in a compilation.  Any _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be_\b, directives can ref-
     erence  files  having other _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be directives, and parsing
     will occur in these files as well.

     Every file that a _\bs_\bo_\bu_\br_\bc_\be_\bf_\bi_\bl_\be  includes,  directly  or  indi-
     rectly,  is  what  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  calls  a "dependency".  These
     dependencies are then written to a _\bm_\ba_\bk_\be_\bf_\bi_\bl_\be in  such  a  way
     that m\bma\bak\bke\be(\b(1\b1)\b) will know which object files must be recompiled
     when a dependency has changed.

     By default, m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd places its output in the  file  named
     _\bm_\ba_\bk_\be_\bf_\bi_\bl_\be  if  it  exists,  otherwise _\bM_\ba_\bk_\be_\bf_\bi_\bl_\be_\b.  An alternate
     makefile may be specified with  the  -\b-f\bf  option.   It  first
     searches the makefile for the line

         #  DO NOT DELETE THIS LINE -- make depend depends on it.

     or one provided with the -\b-s\bs option, as a delimiter  for  the
     dependency  output.   If  it finds it, it will delete every-
     thing following this to the end of the makefile and put  the
     output  after this line.  If it doesn't find it, the program
     will append the string to the end of the makefile and  place
     the output following that.  For each _\bs_\bo_\bu_\br_\bc_\be_\bf_\bi_\bl_\be appearing on
     the command line, m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd puts lines in the  makefile  of
     the form

          sourcefile.o: dfile ...

     Where  "sourcefile.o" is the name from the command line with
     its suffix replaced with ".o", and "dfile" is  a  dependency
     discovered  in a _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be directive while parsing _\bs_\bo_\bu_\br_\bc_\be_\bf_\bi_\bl_\be
     or one of the files it included.

E\bEX\bXA\bAM\bMP\bPL\bLE\bE
     Normally, m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd will be used in a  makefile  target  so
     that  typing "make depend" will bring the dependencies up to
     date for the makefile.  For example,
         SRCS = file1.c file2.c ...



X Version 11          Last change: Release 6                    1






User Commands                                       MAKEDEPEND(1)



         CFLAGS = -O -DHACK -I../foobar -xyz
         depend:
                 makedepend -- $(CFLAGS) -- $(SRCS)

O\bOP\bPT\bTI\bIO\bON\bNS\bS
     M\bMa\bak\bke\bed\bde\bep\bpe\ben\bnd\bd will ignore any option that it  does  not  under-
     stand  so that you may use the same arguments that you would
     for c\bcc\bc(\b(1\b1)\b).\b.

     -\b-D\bDn\bna\bam\bme\be=\b=d\bde\bef\bf o\bor\br -\b-D\bDn\bna\bam\bme\be
          Define.  This places a definition for _\bn_\ba_\bm_\be  in  m\bma\bak\bke\bed\bde\be-\b-
          p\bpe\ben\bnd\bd'\b's\bs  symbol  table.  Without _\b=_\bd_\be_\bf the symbol becomes
          defined as "1".

     -\b-I\bIi\bin\bnc\bcl\blu\bud\bde\bed\bdi\bir\br
          Include directory.  This  option  tells  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  to
          prepend _\bi_\bn_\bc_\bl_\bu_\bd_\be_\bd_\bi_\br to its list of directories to search
          when it encounters a _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be directive.   By  default,
          m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  only searches the standard include directo-
          ries (usually /usr/include  and  possibly  a  compiler-
          dependent directory).

     -\b-Y\bYi\bin\bnc\bcl\blu\bud\bde\bed\bdi\bir\br
          Replace  all  of  the standard include directories with
          the single specified include directory;  you  can  omit
          the _\bi_\bn_\bc_\bl_\bu_\bd_\be_\bd_\bi_\br to simply prevent searching the standard
          include directories.

     -\b-a\ba   Append the dependencies to the end of the file  instead
          of replacing them.

     -\b-f\bfm\bma\bak\bke\bef\bfi\bil\ble\be
          Filename.   This  allows  you  to  specify an alternate
          makefile in which m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd can place its output.

     -\b-o\boo\bob\bbj\bjs\bsu\buf\bff\bfi\bix\bx
          Object file suffix.  Some systems may have object files
          whose suffix is something other than ".o".  This option
          allows you to specify another suffix, such as ".b" with
          _\b-_\bo_\b._\bb or ":obj" with _\b-_\bo_\b:_\bo_\bb_\bj and so forth.

     -\b-p\bpo\bob\bbj\bjp\bpr\bre\bef\bfi\bix\bx
          Object  file  prefix.   The  prefix is prepended to the
          name of the object file. This is usually used to desig-
          nate  a  different  directory for the object file.  The
          default is the empty string.

     -\b-s\bss\bst\btr\bri\bin\bng\bg
          Starting string delimiter.  This option permits you  to
          specify  a  different string for m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd to look for
          in the makefile.




X Version 11          Last change: Release 6                    2






User Commands                                       MAKEDEPEND(1)



     -\b-w\bww\bwi\bid\bdt\bth\bh
          Line width.   Normally,  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  will  ensure  that
          every  output line that it writes will be no wider than
          78 characters for the sake of readability.  This option
          enables you to change this width.

     -\b-v\bv   Verbose  operation.   This  option causes m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd to
          emit the list of files included by each input  file  on
          standard output.

     -\b-m\bm   Warn  about  multiple  inclusion.   This  option causes
          m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd to produce  a  warning  if  any  input  file
          includes another file more than once.  In previous ver-
          sions of m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd this was the default behavior;  the
          default  has  been changed to better match the behavior
          of the C compiler, which  does  not  consider  multiple
          inclusion  to be an error.  This option is provided for
          backward compatibility, and to aid in  debugging  prob-
          lems related to multiple inclusion.

     -\b--\b- o\bop\bpt\bti\bio\bon\bns\bs -\b--\b-
          If  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  encounters  a double hyphen (--) in the
          argument list, then any unrecognized argument following
          it  will  be  silently  ignored; a second double hyphen
          terminates  this  special  treatment.   In  this   way,
          m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  can  be made to safely ignore esoteric com-
          piler arguments that  might  normally  be  found  in  a
          CFLAGS m\bma\bak\bke\be macro (see the E\bEX\bXA\bAM\bMP\bPL\bLE\bE section above).  All
          options that m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd recognizes and  appear  between
          the pair of double hyphens are processed normally.

A\bAL\bLG\bGO\bOR\bRI\bIT\bTH\bHM\bM
     The approach used in this program enables it to run an order
     of magnitude faster than any other "dependency generator"  I
     have ever seen.  Central to this performance are two assump-
     tions: that all files compiled by a single makefile will  be
     compiled  with  roughly the same _\b-_\bI and _\b-_\bD options; and that
     most files in a single directory will  include  largely  the
     same files.

     Given  these  assumptions,  m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd  expects to be called
     once for each makefile, with all source files that are main-
     tained  by  the  makefile appearing on the command line.  It
     parses each source and include file exactly once,  maintain-
     ing an internal symbol table for each.  Thus, the first file
     on the command line will take an amount of time proportional
     to  the  amount  of time that a normal C preprocessor takes.
     But on subsequent files, if it encounter's an  include  file
     that it has already parsed, it does not parse it again.

     For  example,  imagine  you are compiling two files, _\bf_\bi_\bl_\be_\b1_\b._\bc
     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



X Version 11          Last change: Release 6                    3






User Commands                                       MAKEDEPEND(1)



     the  file  _\bh_\be_\ba_\bd_\be_\br_\b._\bh  in  turn  includes the files _\bd_\be_\bf_\b1_\b._\bh and
     _\bd_\be_\bf_\b2_\b._\bh_\b.  When you run the command

         makedepend file1.c file2.c

     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
     then  _\bd_\be_\bf_\b1_\b._\bh and _\bd_\be_\bf_\b2_\b._\bh_\b.  It then decides that the dependen-
     cies for this file are

         file1.o: header.h def1.h def2.h

     But when the program parses _\bf_\bi_\bl_\be_\b2_\b._\bc and discovers  that  it,
     too, includes _\bh_\be_\ba_\bd_\be_\br_\b._\bh_\b, it does not parse the file, but sim-
     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-
     dencies for _\bf_\bi_\bl_\be_\b2_\b._\bo_\b.

S\bSE\bEE\bE A\bAL\bLS\bSO\bO
     cc(1), make(1)

B\bBU\bUG\bGS\bS
     m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd parses, but does not currently evaluate, the SVR4
     #predicate(token-list) preprocessor expression; such expres-
     sions  are  simply  assumed  to be true.  This may cause the
     wrong _\b#_\bi_\bn_\bc_\bl_\bu_\bd_\be directives to be evaluated.

     Imagine you are parsing two files, say _\bf_\bi_\bl_\be_\b1_\b._\bc and  _\bf_\bi_\bl_\be_\b2_\b._\bc_\b,
     each  includes the file _\bd_\be_\bf_\b._\bh_\b.  The list of files that _\bd_\be_\bf_\b._\bh
     includes might truly be different when _\bd_\be_\bf_\b._\bh is included  by
     _\bf_\bi_\bl_\be_\b1_\b._\bc  than  when  it  is  included  by _\bf_\bi_\bl_\be_\b2_\b._\bc_\b.  But once
     m\bma\bak\bke\bed\bde\bep\bpe\ben\bnd\bd arrives at a list of dependencies for a file,  it
     is cast in concrete.

A\bAU\bUT\bTH\bHO\bOR\bR
     Todd Brunhoff, Tektronix, Inc. and MIT Project Athena





















X Version 11          Last change: Release 6                    4