tools/scripts/xref.1onbld

         " CDDL HEADER START
 "
 " The contents of this file are subject to the terms of the
 " Common Development and Distribution License (the "License").
 " You may not use this file except in compliance with the License.
 "
 " You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 " or http://www.opensolaris.org/os/licensing.
 " See the License for the specific language governing permissions
 " and limitations under the License.
 "
 " When distributing Covered Code, include this CDDL HEADER in each
 " file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 " If applicable, add the following below this CDDL HEADER, with the
 " fields enclosed by brackets "[]" replaced with your own identifying
 " information: Portions Copyright [yyyy] [name of copyright owner]
 "
 " CDDL HEADER END
 "
 "Copyright 2009 Sun Microsystems, Inc. All rights reserved."
 "Use is subject to license terms."
 XREF 1ONBLD "Aug 10, 2009"
 NAME
 xref - build and maintain source cross-references
 SYNOPSIS
xref [-cfp] [-m <makefile>] [-x cscope|ctags|etags[,...]] [<subtree> ...]
 DESCRIPTION

 xref is a simple tool for building and maintaining source cross-references for
subtrees of a workspace. By default, xref builds cscope-fast, ctags, and
etags (if available; see NOTES) source cross-references for all of the
eligible files underneath each named subtree, plus any additional eligible
files reported by flg.flp(1ONBLD). File eligibility is determined by pattern
matching -- by default, files matching the following patterns are
eligible:

 *.[Ccdshlxy] Makefile* *.il* *.cc llib-* *.xml *.dtd.* *.ndl


However, this default behavior can be changed, either through command-line
options or by setting the cross-reference customization macros (see
CUSTOMIZATION MACROS) in the Makefile rooted at each specified
subtree.

Any number of subtrees can be specified; if no subtrees are specified,
then the current working directory is assumed. Relative subtrees are
assumed to be relative to the current working directory.
 OPTIONS
 10
 -c Clobber (rather than build) cross-references.
 10
 -f Do not use flg.flp(1ONBLD) to locate additional related files. This option is
ignored if -c is specified.

 -m makefile Use the customization macros specified in makefile when building the
cross-reference, rather than those in Makefile. If no Makefile exists
or no customizations are desired, then /dev/null may be used.
 10
 -p Remove any proto-area include directories from the include path list when
building the cross-reference. This is chiefly useful when the built
cross-reference will be shared with others that either cannot or should
not access the proto areas associated with the workspace used to construct
the cross-reference. This option is ignored if -c is specified.
 10
 -x cscope|tags|etags Operate on only the specified cross-references. More than one
cross-reference can be operated on by specifying a comma-separated list
(see EXAMPLES). By default, all supported cross-references are
operated on.
 CUSTOMIZATION MACROS
The xref tool uses a private Makefile, xref.mk, to perform the actual
construction and maintenance of each cross-reference. While the logic in
xref.mk is sufficient for most situations, some subtrees of a workspace
may require additional fine-tuning (e.g., to exclude machine-generated
source files, or to include source files with unusual filenames). To
accomodate this, xref.mk itself includes the the file named
Makefile (or the filename specified via -m) at the root of each
specified subtree. This Makefile in turn may customize the
cross-reference by setting any of the following macros:

 XRDIRS
The list of directories to build the cross-reference over; defaults to
`.'. Directories containing source files most likely to be of interest to
those using the cross-reference should be listed earlier.


 XRPRUNE
The list of directories to prune out.


 XRADD
The list of additional filename patterns to include.


 XRDEL
The list of additional filename patterns to exclude.


XRINCDIRS

The list of additional include paths, in "foo bar" format.


 XRINCS
The list of additional include paths, in "-Ifoo -Ibar" format.

 EXAMPLES
Build cscope-fast, ctags, and etags cross-references for the subtree
rooted at the current working directory:

$ xref

Build cscope-fast, ctags, and etags cross-references for $SRC/cmd/agents:

$ xref $SRC/cmd/agents

Build just the cscope-fast cross-reference for $SRC, and do not use
flg.flp(1ONBLD) (since there are no additional source files to find):

$ xref -f -x cscope $SRC

Build just the standard cscope cross-reference for $SRC/uts:

$ CSCOPE=cscope CSFLAGS=-b xref -x cscope $SRC/uts

Build a cscope database containing just the ZFS source:

$ cd $SRC
$ cat > /tmp/zfs.mk
XRDIRS=uts/common/fs/zfs common/zfs lib/libzfs cmd/zfs cmd/zpool

$ xref -f -x cscope -m /tmp/zfs.mk
 ENVIRONMENT VARIABLES
Because xref uses xref.mk to carry out the requested operations and
invokes make(1) with the -e option, the value of any macros used by
xref.mk can be overridden through environment variables. This is
chiefly useful for customizing the programs used to build the cross
references; see EXAMPLES.
 SEE ALSO

 make(1),  bringover(1ONBLD)  flg.flp(1ONBLD)  NOTES
The etags utility is no longer bundled with the Sun Studio, which
means it may not be available on all developer systems. If xref cannot
locate the etags utility and the -x option has not been specified, then
xref will silently not build etags.

The ETAGS environment variable can be used to specify an alternate
path to the etags utility. For instance, to use the one included with
SUNWgnu-emacs, set ETAGS to /usr/gnu/bin/etags prior to invoking xref.