|
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.