1 .\" " CDDL HEADER START
   2 .\" "
   3 .\" " The contents of this file are subject to the terms of the
   4 .\" " Common Development and Distribution License (the "License").
   5 .\" " You may not use this file except in compliance with the License.
   6 .\" "
   7 .\" " You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   8 .\" " or http://www.opensolaris.org/os/licensing.
   9 .\" " See the License for the specific language governing permissions
  10 .\" " and limitations under the License.
  11 .\" "
  12 .\" " When distributing Covered Code, include this CDDL HEADER in each
  13 .\" " file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  14 .\" " If applicable, add the following below this CDDL HEADER, with the
  15 .\" " fields enclosed by brackets "[]" replaced with your own identifying
  16 .\" " information: Portions Copyright [yyyy] [name of copyright owner]
  17 .\" "
  18 .\" " CDDL HEADER END
  19 .\" "
  20 .\" "Copyright 2009 Sun Microsystems, Inc.  All rights reserved."
  21 .\" "Use is subject to license terms."
  22 .TH xref 1 "10 Aug 2009"
  23 .SH NAME
  24 .I xref
  25 \- build and maintain source cross-references
  26 .SH SYNOPSIS
  27 \fBxref [-cfp] [-m <makefile>] [-x cscope|ctags|etags[,...]] [<subtree> ...]\fP
  28 .LP
  29 .SH DESCRIPTION
  30 .IX "OS-Net build tools" "xref" "" "\fBxref\fP"
  31 .LP
  32 .I xref
  33 is a simple tool for building and maintaining source cross-references for
  34 subtrees of a workspace.  By default, xref builds cscope-fast, ctags, and
  35 etags (if available; see NOTES) source cross-references for all of the
  36 eligible files underneath each named subtree, plus any additional eligible
  37 files reported by flg.flp(1).  File eligibility is determined by pattern
  38 matching -- by default, files matching the following patterns are
  39 eligible:
  40 
  41         *.[Ccdshlxy] Makefile* *.il* *.cc llib-* *.xml *.dtd.* *.ndl
  42 
  43 However, this default behavior can be changed, either through command-line
  44 options or by setting the cross-reference customization macros (see
  45 \fICUSTOMIZATION MACROS\fP) in the Makefile rooted at each specified
  46 subtree.
  47 .LP
  48 Any number of subtrees can be specified; if no subtrees are specified,
  49 then the current working directory is assumed.  Relative subtrees are
  50 assumed to be relative to the current working directory.
  51 .SH OPTIONS
  52 .TP 10
  53 .B -c
  54 Clobber (rather than build) cross-references.
  55 .TP 10
  56 .B -f
  57 Do not use flg.flp(1) to locate additional related files.  This option is
  58 ignored if \fB-c\fP is specified.
  59 .TP
  60 .B -m \fImakefile\fP
  61 Use the customization macros specified in \fImakefile\fP when building the
  62 cross-reference, rather than those in Makefile.  If no Makefile exists
  63 or no customizations are desired, then /dev/null may be used.
  64 .TP 10
  65 .B -p
  66 Remove any proto-area include directories from the include path list when
  67 building the cross-reference.  This is chiefly useful when the built
  68 cross-reference will be shared with others that either cannot or should
  69 not access the proto areas associated with the workspace used to construct
  70 the cross-reference. This option is ignored if \fB-c\fP is specified.
  71 .TP 10
  72 .B -x cscope|tags|etags
  73 Operate on only the specified cross-references.  More than one
  74 cross-reference can be operated on by specifying a comma-separated list
  75 (see \fIEXAMPLES\fP).  By default, all supported cross-references are
  76 operated on.
  77 .SH CUSTOMIZATION MACROS
  78 The xref tool uses a private Makefile, xref.mk, to perform the actual
  79 construction and maintenance of each cross-reference.  While the logic in
  80 xref.mk is sufficient for most situations, some subtrees of a workspace
  81 may require additional fine-tuning (e.g., to exclude machine-generated
  82 source files, or to include source files with unusual filenames).  To
  83 accomodate this, xref.mk itself \fBincludes\fP the the file named
  84 \fIMakefile\fP (or the filename specified via -m) at the root of each
  85 specified subtree.  This Makefile in turn may customize the
  86 cross-reference by setting any of the following macros:
  87 .LP
  88 .B XRDIRS
  89 .RS 4
  90 The list of directories to build the cross-reference over; defaults to
  91 `.'.  Directories containing source files most likely to be of interest to
  92 those using the cross-reference should be listed earlier.
  93 .RE
  94 .LP
  95 .B XRPRUNE
  96 .RS 4
  97 The list of directories to prune out.
  98 .RE
  99 .LP
 100 .B XRADD
 101 .RS 4
 102 The list of additional filename patterns to include.
 103 .RE
 104 .LP
 105 .B XRDEL
 106 .RS 4
 107 The list of additional filename patterns to exclude.
 108 .RE
 109 .LP
 110 XRINCDIRS
 111 .RS 4
 112 The list of additional include paths, in "foo bar" format.
 113 .RE
 114 .LP
 115 .B XRINCS
 116 .RS 4
 117 The list of additional include paths, in "-Ifoo -Ibar" format.
 118 .RE
 119 .SH EXAMPLES
 120 Build cscope-fast, ctags, and etags cross-references for the subtree
 121 rooted at the current working directory:
 122 .LP
 123 $ xref
 124 .LP
 125 Build cscope-fast, ctags, and etags cross-references for $SRC/cmd/agents:
 126 .LP
 127 $ xref $SRC/cmd/agents
 128 .LP
 129 Build just the cscope-fast cross-reference for $SRC, and do not use
 130 flg.flp(1) (since there are no additional source files to find):
 131 .LP
 132 $ xref -f -x cscope $SRC
 133 .LP
 134 Build just the standard cscope cross-reference for $SRC/uts:
 135 .LP
 136 $ CSCOPE=cscope CSFLAGS=-b xref -x cscope $SRC/uts
 137 .LP
 138 Build a cscope database containing just the ZFS source:
 139 .LP
 140 .nf
 141 $ cd $SRC
 142 $ cat > /tmp/zfs.mk
 143 XRDIRS=uts/common/fs/zfs common/zfs lib/libzfs cmd/zfs cmd/zpool
 144 .fi
 145 $ xref -f -x cscope -m /tmp/zfs.mk
 146 .LP
 147 .SH ENVIRONMENT VARIABLES
 148 Because xref uses xref.mk to carry out the requested operations and
 149 invokes make(1) with the -e option, the value of any macros used by
 150 xref.mk can be overridden through environment variables.  This is 
 151 chiefly useful for customizing the programs used to build the cross
 152 references; see \fIEXAMPLES\fP.
 153 .LP
 154 .SH SEE ALSO
 155 .LP
 156 .IR make(1),
 157 .IR bringover(1),
 158 .IR flg.flp(1)
 159 .SH NOTES
 160 The etags utility is no longer bundled with the Sun Studio, which
 161 means it may not be available on all developer systems.  If xref cannot
 162 locate the etags utility and the -x option has not been specified, then
 163 xref will silently not build etags.
 164 .LP
 165 The ETAGS environment variable can be used to specify an alternate
 166 path to the etags utility.  For instance, to use the one included with
 167 SUNWgnu-emacs, set ETAGS to /usr/gnu/bin/etags prior to invoking xref.