HOWTO Use emacs with the TAGS facility

Note:
This HOWTO was originally written around svn revision 6588 of the toolkit, around March 2006; if you are reading this later and find discrepancies between this HOWTO and the latest code, please either: fix the HOWTO and commit a change back through svn, or post a comment to http://ilab.usc.edu/forum/ mentioning the problem.

Making a TAGS file

Often with a large source codebase like the iLab Neuromorphic Vision C++ Toolkit (wc `./devscripts/list-sources.sh` currently shows 354,849 lines of C++ code) it is easy to forget, or simply be unfamiliar with, the far reaches of the source code. One easy way to help you keep the entire codebase under your thumb is to use the TAGS facility of emacs.

A TAGS file is just an index of all of the source files in the project, which allows emacs to do global searches through the entire source code. To build a TAGS file, just do

make TAGS

Internally, that just calls

etags -o TAGS `./devscripts/list-sources.sh`

You can build custom TAGS files similarly; for example you could make a TAGS file with only the headers from src/Image:

etags -o IMAGE_H_TAGS src/Image/?*.H

Using TAGS to search

For this example, let's say we're trying to hunt down the code behind the --maxnorm-type option. You need to know that in the code, all options are defined without the leading double-dash. So, in emacs you would type

Esc-x tags-search RETURN "maxnorm-type"

(WITH the quotes around "maxnorm-type", since we are looking for a C string literal in the source code, which will have quotes around it). Emacs will ask you which TAGS file to load; just point it to path/to/saliency/TAGS. Then it should take you straight to line 114 of src/Channel/ChannelOpts.C (if it takes you somewhere else first, you can do Esc-, to cycle through subsequent search hits until you find the one you want). There you see that the --maxnorm-type command-line option is implemented by a ModelOptionDef named OPT_MaxNormType. Also you see that the parameter type underlying this option is MaxNormType because the definition contains MODOPT_ARG(MaxNormType) (which says that the command-line option needs an argument of type MaxNormType).

Using TAGS to find the definition of a tag

Next, we can do two things: we can hunt down MaxNormType, and we can look for uses of OPT_MaxNormType. First, we can look for the definition of MaxNormType by using (in emacs)

Esc-x find-tag RETURN MaxNormType

In general, you can use Esc-x find-tag to find the definition of any class, struct, enum, function, global variable, or macro. An equivalent shorthand is

Esc-. MaxNormType     (that's Esc-PERIOD MaxNormType)

That should take you straight to the definition of enum MaxNormType around line 49 of src/Image/fancynorm.H. There you see the VCXNORM_SURPRISE enumerant. We can do another search for that value with

Esc-x tags-search RETURN VCXNORM_SURPRISE

That should take you first to around line 536 of src/Neuro/VisualCortex.C. To see subsequent search hits, do

Esc-,     (that's Esc-COMMA)

A few lines down in src/Neuro/VisualCortex.C you see that itsOutput is multiplied by itsOutputFactor. Let's say we want to find out which command-line option controls itsOutputFactor. If you scroll back up toward the top of the file, you'll see that itsOutputFactor is associated with OPT_VisualCortexOutputFactor. We can find the definition of that option using

Esc-x find-tag RETURN OPT_VisualCortexOutputFactor

Or, if you put emacs's cursor on top of the word you want to search for (in this case, OPT_VisualCortexOutputFactor), you can just do

Esc-x find-tag RETURN RETURN

since emacs will by default search for the word under point. Even shorter would be just

Esc-. RETURN

Anyway, that will take you to around line 92 of src/Channel/ChannelOpts.C, where you see that OPT_VisualCortexOutputFactor is controlled by --vcx-outfac.

Generated on Sun May 8 08:43:02 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3