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