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