1 xref(1ONBLD) illumos Build Tools xref(1ONBLD) 2 3 4 5 NAME 6 xref - build and maintain source cross-references 7 8 SYNOPSIS 9 xref [-cfp] [-m <makefile>] [-x cscope|ctags|etags[,...]] [<subtree> 10 ...] 11 12 DESCRIPTION 13 xref is a simple tool for building and maintaining source cross- 14 references for subtrees of a workspace. By default, xref builds 15 cscope-fast, ctags, and etags (if available; see NOTES) source cross- 16 references for all of the eligible files underneath each named subtree, 17 plus any additional eligible files reported by flg.flp(1ONBLD). File 18 eligibility is determined by pattern matching -- by default, files 19 matching the following patterns are eligible: 20 21 *.[Ccdshlxy] Makefile* *.il* *.cc llib-* *.xml *.dtd.* *.ndl 22 23 However, this default behavior can be changed, either through command- 24 line options or by setting the cross-reference customization macros 25 (see CUSTOMIZATION MACROS) in the Makefile rooted at each specified 26 subtree. 27 28 Any number of subtrees can be specified; if no subtrees are specified, 29 then the current working directory is assumed. Relative subtrees are 30 assumed to be relative to the current working directory. 31 32 OPTIONS 33 -c Clobber (rather than build) cross-references. 34 35 -f Do not use flg.flp(1ONBLD) to locate additional related 36 files. This option is ignored if -c is specified. 37 38 -m makefile 39 Use the customization macros specified in makefile when 40 building the cross-reference, rather than those in Makefile. 41 If no Makefile exists or no customizations are desired, then 42 /dev/null may be used. 43 44 -p Remove any proto-area include directories from the include 45 path list when building the cross-reference. This is chiefly 46 useful when the built cross-reference will be shared with 47 others that either cannot or should not access the proto 48 areas associated with the workspace used to construct the 49 cross-reference. This option is ignored if -c is specified. 50 51 -x cscope|tags|etags 52 Operate on only the specified cross-references. More than 53 one cross-reference can be operated on by specifying a comma- 54 separated list (see EXAMPLES). By default, all supported 55 cross-references are operated on. 56 57 CUSTOMIZATION MACROS 58 The xref tool uses a private Makefile, xref.mk, to perform the actual 59 construction and maintenance of each cross-reference. While the logic 60 in xref.mk is sufficient for most situations, some subtrees of a 61 workspace may require additional fine-tuning (e.g., to exclude machine- 62 generated source files, or to include source files with unusual 63 filenames). To accomodate this, xref.mk itself includes the the file 64 named Makefile (or the filename specified via -m) at the root of each 65 specified subtree. This Makefile in turn may customize the cross- 66 reference by setting any of the following macros: 67 68 XRDIRS 69 The list of directories to build the cross-reference over; defaults 70 to `.'. Directories containing source files most likely to be of 71 interest to those using the cross-reference should be listed 72 earlier. 73 74 XRPRUNE 75 The list of directories to prune out. 76 77 XRADD 78 The list of additional filename patterns to include. 79 80 XRDEL 81 The list of additional filename patterns to exclude. 82 83 XRINCDIRS 84 The list of additional include paths, in "foo bar" format. 85 86 XRINCS 87 The list of additional include paths, in "-Ifoo -Ibar" format. 88 89 EXAMPLES 90 Build cscope-fast, ctags, and etags cross-references for the subtree 91 rooted at the current working directory: 92 93 $ xref 94 95 Build cscope-fast, ctags, and etags cross-references for 96 $SRC/cmd/agents: 97 98 $ xref $SRC/cmd/agents 99 100 Build just the cscope-fast cross-reference for $SRC, and do not use 101 flg.flp(1ONBLD) (since there are no additional source files to find): 102 103 $ xref -f -x cscope $SRC 104 105 Build just the standard cscope cross-reference for $SRC/uts: 106 107 $ CSCOPE=cscope CSFLAGS=-b xref -x cscope $SRC/uts 108 109 Build a cscope database containing just the ZFS source: 110 111 $ cd $SRC 112 $ cat > /tmp/zfs.mk 113 XRDIRS=uts/common/fs/zfs common/zfs lib/libzfs cmd/zfs cmd/zpool 114 $ xref -f -x cscope -m /tmp/zfs.mk 115 116 ENVIRONMENT VARIABLES 117 Because xref uses xref.mk to carry out the requested operations and 118 invokes make(1) with the -e option, the value of any macros used by 119 xref.mk can be overridden through environment variables. This is 120 chiefly useful for customizing the programs used to build the cross 121 references; see EXAMPLES. 122 123 SEE ALSO 124 make(1), bringover(1ONBLD) flg.flp(1ONBLD) 125 126 NOTES 127 The etags utility is no longer bundled with the Sun Studio, which means 128 it may not be available on all developer systems. If xref cannot 129 locate the etags utility and the -x option has not been specified, then 130 xref will silently not build etags. 131 132 The ETAGS environment variable can be used to specify an alternate path 133 to the etags utility. For instance, to use the one included with 134 SUNWgnu-emacs, set ETAGS to /usr/gnu/bin/etags prior to invoking xref. 135 136 137 138 10 Aug 2009 xref(1ONBLD)