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 1ONBLD "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(1ONBLD). 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(1ONBLD) 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
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(1ONBLD) (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(1ONBLD)
158 .IR flg.flp(1ONBLD)
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.
|
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 1ONBLD "Aug 10, 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 .SH DESCRIPTION
29 .LP
30 .I xref
31 is a simple tool for building and maintaining source cross-references for
32 subtrees of a workspace. By default, xref builds cscope-fast, ctags, and
33 etags (if available; see NOTES) source cross-references for all of the
34 eligible files underneath each named subtree, plus any additional eligible
35 files reported by flg.flp(1ONBLD). File eligibility is determined by pattern
36 matching -- by default, files matching the following patterns are
37 eligible:
38
39 .nf
40 *.[Ccdshlxy] Makefile* *.il* *.cc llib-* *.xml *.dtd.* *.ndl
41 .fi
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(1ONBLD) 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
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(1ONBLD) (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 .SH ENVIRONMENT VARIABLES
147 Because xref uses xref.mk to carry out the requested operations and
148 invokes make(1) with the -e option, the value of any macros used by
149 xref.mk can be overridden through environment variables. This is
150 chiefly useful for customizing the programs used to build the cross
151 references; see \fIEXAMPLES\fP.
152 .SH SEE ALSO
153 .LP
154 .IR make(1),
155 .IR bringover(1ONBLD)
156 .IR flg.flp(1ONBLD)
157 .SH NOTES
158 The etags utility is no longer bundled with the Sun Studio, which
159 means it may not be available on all developer systems. If xref cannot
160 locate the etags utility and the -x option has not been specified, then
161 xref will silently not build etags.
162 .LP
163 The ETAGS environment variable can be used to specify an alternate
164 path to the etags utility. For instance, to use the one included with
165 SUNWgnu-emacs, set ETAGS to /usr/gnu/bin/etags prior to invoking xref.
|