make TAGSEsc-x tags-search RETURNEsc-, (Esc-COMMA)Esc-x find-tag RETURN or simply Esc-. (Esc-PERIOD)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
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).
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.
1.6.3