ident "%Z%%M% %I% %E% SMI"
" CDDL HEADER START
"
" The contents of this file are subject to the terms of the
" Common Development and Distribution License, Version 1.0 only
" (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 2003 Sun Microsystems, Inc. All rights reserved."
"Use is subject to license terms."
xref - build and maintain source cross-references xref [-cfp] [-m <makefile>] [-x cscope|ctags|etags[,...]] [<subtree> ...]

"OS-Net build tools" "xref" "" "xref"

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(1). File eligibility is determined by pattern matching -- by default, files matching the following patterns are eligible: *.[Ccshlxy] Makefile* *.il* *.cc *.adb llib-* 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.

10 -c Clobber (rather than build) cross-references.

10 -f Do not use flg.flp(1) 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.

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

XRPRUNE

XRADD

XRDEL

XRINCDIRS

XRINCS

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(1) (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

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.

make(1), bringover(1), flg.flp(1)

The etags utility is no longer bundled with the Sun ONE 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 packaged with Sun Freeware, set ETAGS to /opt/sfw/bin/etags prior to invoking xref.