1 xref(1) User Commands xref(1)
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(1). 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(1) to locate additional related files.
36 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
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(1) (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(1), flg.flp(1)
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(1)
|
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
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)
|