XREF(1ONBLD) illumos Build Tools XREF(1ONBLD)

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

-c
Clobber (rather than build) cross-references.
-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.
-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.
-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.

August 10, 2009