00001 /* -*- mode: text; fill-column: 70; indent-tabs-mode: nil -*- 00002 $Id: howto-using-emacs-tags.dxy 6364 2006-03-14 18:50:59Z rjpeters $ 00003 */ 00004 00005 /** \page howto-using-emacs-tags HOWTO Use emacs with the TAGS facility 00006 00007 - For the impatient or the forgetful (like myself) 00008 - build a TAGS file using <tt>make TAGS</tt> 00009 - do a tags search in emacs using <tt>Esc-x tags-search RETURN</tt> 00010 - cycle through search hits using <tt>Esc-,</tt> (<tt>Esc-COMMA</tt>) 00011 - find a tag definition using <tt>Esc-x find-tag RETURN</tt> or 00012 simply <tt>Esc-.</tt> (<tt>Esc-PERIOD</tt>) 00013 00014 00015 \note This HOWTO was originally written around svn revision 6588 of 00016 the toolkit, around March 2006; if you are reading this later and find 00017 discrepancies between this HOWTO and the latest code, please either: 00018 fix the HOWTO and commit a change back through svn, or post a comment 00019 to http://ilab.usc.edu/forum/ mentioning the problem. 00020 00021 <!--############################################################--><hr> 00022 00023 \section making-tags Making a TAGS file 00024 00025 Often with a large source codebase like the iLab Neuromorphic Vision 00026 C++ Toolkit (<tt>wc `./devscripts/list-sources.sh`</tt> currently 00027 shows 354,849 lines of C++ code) it is easy to forget, or simply be 00028 unfamiliar with, the far reaches of the source code. One easy way to 00029 help you keep the entire codebase under your thumb is to use the TAGS 00030 facility of emacs. 00031 00032 A TAGS file is just an index of all of the source files in the 00033 project, which allows emacs to do global searches through the entire 00034 source code. To build a TAGS file, just do 00035 00036 \verbatim 00037 make TAGS 00038 \endverbatim 00039 00040 Internally, that just calls 00041 00042 \verbatim 00043 etags -o TAGS `./devscripts/list-sources.sh` 00044 \endverbatim 00045 00046 You can build custom TAGS files similarly; for example you could make 00047 a TAGS file with only the headers from src/Image: 00048 00049 \verbatim 00050 etags -o IMAGE_H_TAGS src/Image/?*.H 00051 \endverbatim 00052 00053 \section tags-search Using TAGS to search 00054 00055 For this example, let's say we're trying to hunt down the code behind 00056 the <tt>--maxnorm-type</tt> option. You need to know that in the code, 00057 all options are defined without the leading double-dash. So, in emacs 00058 you would type 00059 00060 \verbatim 00061 Esc-x tags-search RETURN "maxnorm-type" 00062 \endverbatim 00063 00064 (WITH the quotes around "maxnorm-type", since we are looking for a C 00065 string literal in the source code, which will have quotes around 00066 it). Emacs will ask you which TAGS file to load; just point it to 00067 path/to/saliency/TAGS. Then it should take you straight to line 114 of 00068 src/Channel/ChannelOpts.C (if it takes you somewhere else first, you 00069 can do <tt>Esc-,</tt> to cycle through subsequent search hits until 00070 you find the one you want). There you see that the 00071 <tt>--maxnorm-type</tt> command-line option is implemented by a 00072 ModelOptionDef named <tt>OPT_MaxNormType</tt>. Also you see that the 00073 parameter type underlying this option is MaxNormType because the 00074 definition contains <tt>MODOPT_ARG(MaxNormType)</tt> (which says that 00075 the command-line option needs an argument of type 00076 <tt>MaxNormType</tt>). 00077 00078 \section find-tag Using TAGS to find the definition of a tag 00079 00080 Next, we can do two things: we can hunt down <tt>MaxNormType</tt>, and 00081 we can look for uses of <tt>OPT_MaxNormType</tt>. First, we can look 00082 for the definition of <tt>MaxNormType</tt> by using (in emacs) 00083 00084 \verbatim 00085 Esc-x find-tag RETURN MaxNormType 00086 \endverbatim 00087 00088 In general, you can use <tt>Esc-x find-tag</tt> to find the definition 00089 of any class, struct, enum, function, global variable, or macro. An 00090 equivalent shorthand is 00091 00092 \verbatim 00093 Esc-. MaxNormType (that's Esc-PERIOD MaxNormType) 00094 \endverbatim 00095 00096 That should take you straight to the definition of <tt>enum 00097 MaxNormType</tt> around line 49 of src/Image/fancynorm.H. There you 00098 see the <tt>VCXNORM_SURPRISE</tt> enumerant. We can do another search 00099 for that value with 00100 00101 \verbatim 00102 Esc-x tags-search RETURN VCXNORM_SURPRISE 00103 \endverbatim 00104 00105 That should take you first to around line 536 of 00106 src/Neuro/VisualCortex.C. To see subsequent search hits, do 00107 00108 \verbatim 00109 Esc-, (that's Esc-COMMA) 00110 \endverbatim 00111 00112 A few lines down in src/Neuro/VisualCortex.C you see that 00113 <tt>itsOutput</tt> is multiplied by <tt>itsOutputFactor</tt>. Let's 00114 say we want to find out which command-line option controls 00115 <tt>itsOutputFactor</tt>. If you scroll back up toward the top of the 00116 file, you'll see that <tt>itsOutputFactor</tt> is associated with 00117 <tt>OPT_VisualCortexOutputFactor</tt>. We can find the definition of 00118 that option using 00119 00120 \verbatim 00121 Esc-x find-tag RETURN OPT_VisualCortexOutputFactor 00122 \endverbatim 00123 00124 Or, if you put emacs's cursor on top of the word you want to search 00125 for (in this case, OPT_VisualCortexOutputFactor), you can just do 00126 00127 \verbatim 00128 Esc-x find-tag RETURN RETURN 00129 \endverbatim 00130 00131 since emacs will by default search for the word under point. Even 00132 shorter would be just 00133 00134 \verbatim 00135 Esc-. RETURN 00136 \endverbatim 00137 00138 Anyway, that will take you to around line 92 of 00139 src/Channel/ChannelOpts.C, where you see that 00140 <tt>OPT_VisualCortexOutputFactor</tt> is controlled by 00141 <tt>--vcx-outfac</tt>. 00142 00143 */