Cscope-fast in OpenSolaris-Land
By Alan Hargreaves-Oracle on Jul 17, 2005
While Chandan has written an absolutely fabulous source browser, there are times when you may not have web access (like right now as I am writing this on a train between Sydney and Gosford) or you may prefer a text based browser.
About a year ago I gave a presentation to our local groups within PTS about how to use cscope-fast.
This blog entry will be a slight rewrite of that presentation removing stuff that is not relevant to the open solaris community and adding a bit that is. For example, you really don't need to know where we keep the source trees inside Sun, but you will probably be interested in how to build the inverted indexes that cscope-fast uses.
Throughout this entry I will almost certainly say cscope. In actuality I mean cscope-fast. Cscope-fast is a modified version of cscope that uses larger and faster indexes.
OK, here's what I'll cover.
- Why cscope?
- What is cscope?
- How to build indexes
- Where is cscope?
- Subtrees with indexes
- Using cscope
- Useful options
Chandan's browser provides a great interface for basic source tree functionality. It does, however have it's limitations.
The big one is that you need to be online to use it.
Another is that you can only look at the online tree with it. If you have been modifying code, it's not much use to you.
I've also never been a great fan of GUIs and web based interfaces. While they have their place, give me a text based interface any day. Cscope is one such tool.
Another nice feature is that I get to browse the code in the editor of my choice rather than being limited to my browsers functionality.
What is Cscope?
This is a screenshot taken while running cscope.
The top line shows the most recent search.
Below that is the list of matches to this search.
At the bottom of the screen are the searches that can be performed.
Some of these are particularly useful.
I've found myself using
- Find Assignments to:, and
- Functions calling this function:
How to build indexes
There are two options here.
- Build all of the indexes defined in the source tree
- Build the ones you are interested in.
/opt/onbld/bin/build_cscope will go away and build the indexes defined in $SRC/tools/scripts/build_cscope.conf. By default this means that we will get indexes in
This build will also create ctags and etags cross references.
Alternately from any of the above named directories you can issue the command
This will create the cscope indexes along wit the ctags and etags cross references for that particular directory.
Where is cscope?
cscope-fast can be found in /opt/onbld/bin/`uname -p`/cscope-fast. For those interested in the sources, they can be found in $SRC/tools/cscope-fast.
Subtrees with indexes
As mentioned earlier, we can build cscope indexes in various subtrees. If you are only working with a particular subtree, it makes sense to run cscope from that subtree to exclude things you are not interested in. It also substantially speeds up egrep searches.
From a directory with an index issue the command
-dq is probably the minimum arguments that you should run with. I'll mention some of the other options and what they actually mean later.
You can navigate the search fields with the tab key or the up and down arrows. When you are on the type of search you want, simply type the key and hit return.
Let's see what that looks like.
Yes it's the same image I used earlier.
In this search we went looking for assignments to pidlock. This was probably not a great example to use as pidlock gets assigned from as an argument to mutex_enter(), but it does show that this search includes the declaration of a variable.
Normally if there is only one match, you will be thrown straight into the editor. We weren't in this instance as I was using options that prevent this. More on this later.
Once you are displaying the matches, you select the one you want by typing the number to it's left.
Again, with only -dq as options, you don't need to hit a return following thatnumber as there will always be fewer than 10 entries displayed. If you use the options that display more than 10, then obviously, you will need to hit enter following your selection.
One thing that I shoudl have mentioned earlieris the $EDITOR environment variable. If you don't define it, it looks like it defaults to dtpad. At least it does if you are running CDE. JDS appears to do the right thing (well that means vi for me), but it's probably a good idea to be specific.
Now it is almost always going to be the case that we will get more than a single page of matches to a search. Plus and Minus (+/-) allow you to navigate those pages. The space bar will also take you forward through them.
We also have some search history, so you can drop back to the search screen to quickly look for something else and then use history to go back to where you were. History is implemented with Control-B (Back) and Control-F (Forward).
Of course typing a ? will give you a help screen.
One of the really nice things about using vi is that as I commented earlier, we created ctags (not being an emacs person, I assume that the etags are for emacs, but I have not had to work out how to use them).
This means that while you are looking at a file, you can type
:ta nameto look for the definition of name. Name can be things like variables, functions or types.
To move back to the file you were editing, pop the tag-stack by typing Control-T.
A Tag command can be repeated by simply typing
Specifying the same options to cscope-fast gets a bit tiring after a while, besides if you don't use it a lot you probably don't want to have to go and find out what the ones you like were again. The fact that for some reason the man page is not available does not help here either.
Saving then in your startup is not a bad idea. You can do this in $CSCOPEOPTIONS.
Anyway here are the options that I like to use are CSCOPEOPTIONS=-dqrp5.
- 'd' - pre-built index
- 'q' - fast (inverted) index
- 'r' - show as many lines as will fit on the screen
- 'p' - number of directory elements to display
If you have vim, it has a cscope mode which allows you to do cscope operatins from inside the editor (in addition to the tag commands). This adds some useful functionality like being able o have multiple files open and to be able to jump to a definition simply by using a keystroke whle the cursor is on top of the function or variable name that you are interested in.
A discussion of vim is beyond the scope of this introductory writeup and I haven't actually played a lot with it either, so if you want to find out about it, google is your friend. Try the keywords "vim" and "cscope".
Technorati Tags: OpenSolaris