xref: /netbsd-src/external/bsd/nvi/docs/internals/cscope.NOTES (revision 4391d5e9d4f291db41e3b3ba26a01b5e51364aae)
1*4391d5e9SchristosCscope Notes:
2*4391d5e9Schristos
3*4391d5e9SchristosThe nvi tags structure has been reworked to handle the notion of multiple
4*4391d5e9Schristoslocations per tag.  This supports cscope, which returns multiple locations
5*4391d5e9Schristosper query.  It will hopefully support ctags programs that create databases
6*4391d5e9Schristoswith multiple locations per tag as well.
7*4391d5e9Schristos
8*4391d5e9SchristosThere is now a list of "tag queues" chained from each screen.  Each tag
9*4391d5e9Schristosqueue has one or more "tag locations".
10*4391d5e9Schristos
11*4391d5e9Schristos   +----+    +----+	+----+     +----+
12*4391d5e9Schristos   | EP | -> | Q1 | <-- | T1 | <-- | T2 |
13*4391d5e9Schristos   +----+    +----+ --> +----+ --> +----+
14*4391d5e9Schristos  	     |
15*4391d5e9Schristos  	     +----+     +----+
16*4391d5e9Schristos  	     | Q2 | <-- | T1 |
17*4391d5e9Schristos  	     +----+ --> +----+
18*4391d5e9Schristos  	     |
19*4391d5e9Schristos  	     +----+	+----+
20*4391d5e9Schristos  	     | Q3 | <-- | T1 |
21*4391d5e9Schristos  	     +----+ --> +----+
22*4391d5e9Schristos
23*4391d5e9SchristosIn the above diagram, each "Q" is a "tag queue", and each "T" is a
24*4391d5e9Schristostag location.  Generally, the commands:
25*4391d5e9Schristos
26*4391d5e9Schristos	:tag			create a new Q
27*4391d5e9Schristos	^[			create a new Q
28*4391d5e9Schristos	:cscope find		create a new Q
29*4391d5e9Schristos	:tagnext		move to the next T
30*4391d5e9Schristos	:tagprev		move to the previous T
31*4391d5e9Schristos	:tagpop			discard one or more Q's
32*4391d5e9Schristos	^T			discard the most recent Q
33*4391d5e9Schristos	:tagtop			discard all Q's
34*4391d5e9Schristos
35*4391d5e9SchristosMore specifically:
36*4391d5e9Schristos
37*4391d5e9Schristos:cs[cope] a[dd] cscope-dir
38*4391d5e9Schristos
39*4391d5e9Schristos	Attach to the cscope database in cscope-dir.
40*4391d5e9Schristos
41*4391d5e9Schristos:cs[cope] f[ind] c|d|e|f|g|i|s|t buffer|pattern
42*4391d5e9Schristos
43*4391d5e9Schristos	Query all attached cscopes for the pattern.  The pattern is a
44*4391d5e9Schristos	regular expression.  If the pattern is a double-quote character
45*4391d5e9Schristos	followed by a valid buffer name (e.g., "t), then the contents
46*4391d5e9Schristos	of the named buffer are used as the pattern.
47*4391d5e9Schristos
48*4391d5e9Schristos	c: find callers of name
49*4391d5e9Schristos	d: find all function calls made from name
50*4391d5e9Schristos	e: find pattern
51*4391d5e9Schristos	f: find files with name as substring
52*4391d5e9Schristos	g: find definition of name
53*4391d5e9Schristos	i: find files #including name
54*4391d5e9Schristos	s: find all uses of name
55*4391d5e9Schristos	t: find assignments to name
56*4391d5e9Schristos
57*4391d5e9Schristos	The find command pushes the current location onto the tags stack,
58*4391d5e9Schristos	and switches to the first location resulting from the query, if
59*4391d5e9Schristos	the query returned at least one result.
60*4391d5e9Schristos
61*4391d5e9Schristos:cs[cope] h[elp] [command]
62*4391d5e9Schristos
63*4391d5e9Schristos	List the cscope commands, or usage help on one command.
64*4391d5e9Schristos
65*4391d5e9Schristos:display c[onnections]
66*4391d5e9Schristos
67*4391d5e9Schristos	Display the list of cscope connections
68*4391d5e9Schristos
69*4391d5e9Schristos:display t[ags]
70*4391d5e9Schristos
71*4391d5e9Schristos	The tags display has been enhanced to display multiple tag
72*4391d5e9Schristos	locations per tag query.
73*4391d5e9Schristos
74*4391d5e9Schristos:cs[cope] k[ill] #
75*4391d5e9Schristos
76*4391d5e9Schristos	Kill cscope connection number #.
77*4391d5e9Schristos
78*4391d5e9Schristos:cs[cope] r[eset]
79*4391d5e9Schristos	Kill all attached cscopes.  Useful if one got hung but you don't
80*4391d5e9Schristos	know which one.
81*4391d5e9Schristos
82*4391d5e9Schristos:tagn[ext][!]
83*4391d5e9Schristos
84*4391d5e9Schristos	Move to the next tag resulting from a query.
85*4391d5e9Schristos
86*4391d5e9Schristos:tagpr[ev][!]
87*4391d5e9Schristos
88*4391d5e9Schristos	Return to the previous tag resulting from a query.
89*4391d5e9Schristos
90*4391d5e9Schristos:tagp[op], ^T
91*4391d5e9Schristos
92*4391d5e9Schristos	Return to the previous tag group (no change).
93*4391d5e9Schristos
94*4391d5e9Schristos:tagt[op]
95*4391d5e9Schristos
96*4391d5e9Schristos	Discard all tag groups (no change).
97*4391d5e9Schristos
98*4391d5e9SchristosSuggested maps:
99*4391d5e9Schristos
100*4391d5e9Schristos	" ^N: move to the next tag
101*4391d5e9Schristos	map ^N :tagnext^M
102*4391d5e9Schristos	" ^P: move to the previous tag
103*4391d5e9Schristos	map ^P :tagprev^M
104*4391d5e9Schristos
105*4391d5e9Schristos	" Tab+letter performs a C-Scope query on the current word.
106*4391d5e9Schristos	" C-Scope 12.9 has a text-string query (type t).
107*4391d5e9Schristos	" C-Scope 13.3 replaces it with an assignment query; hence a==t.
108*4391d5e9Schristos	map <tab>a "tye:csc find t"t
109*4391d5e9Schristos	map <tab>c "tye:csc find c"t
110*4391d5e9Schristos	map <tab>d "tye:csc find d"t
111*4391d5e9Schristos	map <tab>e "tye:csc find e"t
112*4391d5e9Schristos	map <tab>f "tye:csc find f"t
113*4391d5e9Schristos	map <tab>g "tye:csc find g"t
114*4391d5e9Schristos	map <tab>i "tye:csc find i"t
115*4391d5e9Schristos	map <tab>s "tye:csc find s"t
116*4391d5e9Schristos	map <tab>t "tye:csc find t"t
117*4391d5e9Schristos
118*4391d5e9SchristosTo start nvi with an initial set of cscope directories, use the environment
119*4391d5e9Schristosvariable CSCOPE_DIRS.  This variable should contain a <blank>-separated
120*4391d5e9Schristoslist of directories containing cscope databases.  (This MAY be changed to
121*4391d5e9Schristosbe an edit option, I haven't really decided, yet.)
122*4391d5e9Schristos
123*4391d5e9SchristosEach cscope directory must contain a file named "cscope.out" which is the
124*4391d5e9Schristosmain cscope database, or nvi will not attempt to connect to a cscope to
125*4391d5e9Schristoshandle requests for that database.
126*4391d5e9Schristos
127*4391d5e9SchristosThe file "cscope.tpath" may contain a colon-separated directory search
128*4391d5e9Schristospath which will be used to find the files reported by cscope.  If this
129*4391d5e9Schristoscscope.tpath does not exist, then the paths are assumed to be relative to
130*4391d5e9Schristosthe cscope directory itself.  This is an extension to the standard cscope,
131*4391d5e9Schristosbut seems important enough to keep.
132*4391d5e9Schristos
133*4391d5e9Schristos=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
134*4391d5e9SchristosCscope Availability:
135*4391d5e9Schristos
136*4391d5e9SchristosUNIXWare System V Release 4.0 variants such as Sun Solaris 2.x
137*4391d5e9Schristos(/opt/SUNWspro/bin) have version 11.5, and UNIXWare System V
138*4391d5e9SchristosRelease 4.1 has version 12.10 with an option for much faster
139*4391d5e9Schristossearching.
140*4391d5e9Schristos
141*4391d5e9SchristosYou can buy version 13.3 source with an unrestricted license
142*4391d5e9Schristosfor $400 from AT&T Software Solutions by calling +1-800-462-8146.
143