1 XREF(1ONBLD)                  illumos Build Tools                 XREF(1ONBLD)
   2 
   3 
   4 
   5 NAME
   6        xref - build and maintain source cross-references
   7 
   8 SYNOPSIS
   9        xref [-cfp] [-m <makefile>] [-x cscope|ctags|etags[,...]] [<subtree>
  10        ...]
  11 
  12 DESCRIPTION
  13        xref is a simple tool for building and maintaining source cross-
  14        references for subtrees of a workspace.  By default, xref builds
  15        cscope-fast, ctags, and etags (if available; see NOTES) source cross-
  16        references for all of the eligible files underneath each named subtree,
  17        plus any additional eligible files reported by flg.flp(1ONBLD).  File
  18        eligibility is determined by pattern matching -- by default, files
  19        matching the following patterns are eligible:
  20 
  21             *.[Ccdshlxy] Makefile* *.il* *.cc llib-* *.xml *.dtd.* *.ndl
  22 
  23        However, this default behavior can be changed, either through command-
  24        line options or by setting the cross-reference customization macros
  25        (see CUSTOMIZATION MACROS) in the Makefile rooted at each specified
  26        subtree.
  27 
  28        Any number of subtrees can be specified; if no subtrees are specified,
  29        then the current working directory is assumed.  Relative subtrees are
  30        assumed to be relative to the current working directory.
  31 
  32 OPTIONS
  33        -c        Clobber (rather than build) cross-references.
  34 
  35        -f        Do not use flg.flp(1ONBLD) to locate additional related
  36                  files.  This option is ignored if -c is specified.
  37 
  38        -m makefile
  39                  Use the customization macros specified in makefile when
  40                  building the cross-reference, rather than those in Makefile.
  41                  If no Makefile exists or no customizations are desired, then
  42                  /dev/null may be used.
  43 
  44        -p        Remove any proto-area include directories from the include
  45                  path list when building the cross-reference.  This is chiefly
  46                  useful when the built cross-reference will be shared with
  47                  others that either cannot or should not access the proto
  48                  areas associated with the workspace used to construct the
  49                  cross-reference. This option is ignored if -c is specified.
  50 
  51        -x cscope|tags|etags
  52                  Operate on only the specified cross-references.  More than
  53                  one cross-reference can be operated on by specifying a comma-
  54                  separated list (see EXAMPLES).  By default, all supported
  55                  cross-references are operated on.
  56 
  57 CUSTOMIZATION MACROS
  58        The xref tool uses a private Makefile, xref.mk, to perform the actual
  59        construction and maintenance of each cross-reference.  While the logic
  60        in xref.mk is sufficient for most situations, some subtrees of a
  61        workspace may require additional fine-tuning (e.g., to exclude machine-
  62        generated source files, or to include source files with unusual
  63        filenames).  To accomodate this, xref.mk itself includes the the file
  64        named Makefile (or the filename specified via -m) at the root of each
  65        specified subtree.  This Makefile in turn may customize the cross-
  66        reference by setting any of the following macros:
  67 
  68        XRDIRS
  69            The list of directories to build the cross-reference over; defaults
  70            to `.'.  Directories containing source files most likely to be of
  71            interest to those using the cross-reference should be listed
  72            earlier.
  73 
  74        XRPRUNE
  75            The list of directories to prune out.
  76 
  77        XRADD
  78            The list of additional filename patterns to include.
  79 
  80        XRDEL
  81            The list of additional filename patterns to exclude.
  82 
  83        XRINCDIRS
  84            The list of additional include paths, in "foo bar" format.
  85 
  86        XRINCS
  87            The list of additional include paths, in "-Ifoo -Ibar" format.
  88 
  89 EXAMPLES
  90        Build cscope-fast, ctags, and etags cross-references for the subtree
  91        rooted at the current working directory:
  92 
  93        $ xref
  94 
  95        Build cscope-fast, ctags, and etags cross-references for
  96        $SRC/cmd/agents:
  97 
  98        $ xref $SRC/cmd/agents
  99 
 100        Build just the cscope-fast cross-reference for $SRC, and do not use
 101        flg.flp(1ONBLD) (since there are no additional source files to find):
 102 
 103        $ xref -f -x cscope $SRC
 104 
 105        Build just the standard cscope cross-reference for $SRC/uts:
 106 
 107        $ CSCOPE=cscope CSFLAGS=-b xref -x cscope $SRC/uts
 108 
 109        Build a cscope database containing just the ZFS source:
 110 
 111        $ cd $SRC
 112        $ cat > /tmp/zfs.mk
 113        XRDIRS=uts/common/fs/zfs common/zfs lib/libzfs cmd/zfs cmd/zpool
 114        $ xref -f -x cscope -m /tmp/zfs.mk
 115 
 116 ENVIRONMENT VARIABLES
 117        Because xref uses xref.mk to carry out the requested operations and
 118        invokes make(1) with the -e option, the value of any macros used by
 119        xref.mk can be overridden through environment variables.  This is
 120        chiefly useful for customizing the programs used to build the cross
 121        references; see EXAMPLES.
 122 
 123 SEE ALSO
 124        make(1), bringover(1ONBLD) flg.flp(1ONBLD)
 125 
 126 NOTES
 127        The etags utility is no longer bundled with the Sun Studio, which means
 128        it may not be available on all developer systems.  If xref cannot
 129        locate the etags utility and the -x option has not been specified, then
 130        xref will silently not build etags.
 131 
 132        The ETAGS environment variable can be used to specify an alternate path
 133        to the etags utility.  For instance, to use the one included with
 134        SUNWgnu-emacs, set ETAGS to /usr/gnu/bin/etags prior to invoking xref.
 135 
 136 
 137 
 138                                 August 10, 2009                   XREF(1ONBLD)