12.5 Create Your Own TAGS File

Besides C-h f (describe-function), another way to see the source of a function is to type M-. (find-tag) and the name of the function when prompted for it. This is a good habit to get into. The M-. (find-tag) command takes you directly to the source for a function, variable, or node. The function depends on tags tables to tell it where to go.

If the find-tag function first asks you for the name of a TAGS table, give it the name of a TAGS file such as /usr/local/src/emacs/src/TAGS. (The exact path to your TAGS file depends on how your copy of Emacs was installed. I just told you the location that provides both my C and my Emacs Lisp sources.)

You can also create your own TAGS file for directories that lack one.

You often need to build and install tags tables yourself. They are not built automatically. A tags table is called a TAGS file; the name is in upper case letters.

You can create a TAGS file by calling the etags program that comes as a part of the Emacs distribution. Usually, etags is compiled and installed when Emacs is built. (etags is not an Emacs Lisp function or a part of Emacs; it is a C program.)

To create a TAGS file, first switch to the directory in which you want to create the file. In Emacs you can do this with the M-x cd command, or by visiting a file in the directory, or by listing the directory with C-x d (dired). Then run the compile command, with etags *.el as the command to execute

M-x compile RET etags *.el RET

to create a TAGS file for Emacs Lisp.

For example, if you have a large number of files in your ~/emacs directory, as I do—I have 137 .el files in it, of which I load 12—you can create a TAGS file for the Emacs Lisp files in that directory.

The etags program takes all the usual shell ‘wildcards’. For example, if you have two directories for which you want a single TAGS file, type etags *.el ../elisp/*.el, where ../elisp/ is the second directory:

M-x compile RET etags *.el ../elisp/*.el RET

Type

M-x compile RET etags --help RET

to see a list of the options accepted by etags as well as a list of supported languages.

The etags program handles more than 20 languages, including Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, LaTeX, Pascal, Perl, PostScript, Python, TeX, Texinfo, makefiles, and most assemblers. The program has no switches for specifying the language; it recognizes the language in an input file according to its file name and contents.

etags is very helpful when you are writing code yourself and want to refer back to functions you have already written. Just run etags again at intervals as you write new functions, so they become part of the TAGS file.

If you think an appropriate TAGS file already exists for what you want, but do not know where it is, you can use the locate program to attempt to find it.

Type M-x locate RET TAGS RET and Emacs will list for you the full path names of all your TAGS files. On my system, this command lists 34 TAGS files. On the other hand, a ‘plain vanilla’ system I recently installed did not contain any TAGS files.

If the tags table you want has been created, you can use the M-x visit-tags-table command to specify it. Otherwise, you will need to create the tag table yourself and then use M-x visit-tags-table.

Building Tags in the Emacs sources

The GNU Emacs sources come with a Makefile that contains a sophisticated etags command that creates, collects, and merges tags tables from all over the Emacs sources and puts the information into one TAGS file in the src/ directory. (The src/ directory is below the top level of your Emacs directory.)

To build this TAGS file, go to the top level of your Emacs source directory and run the compile command make tags:

M-x compile RET make tags RET

(The make tags command works well with the GNU Emacs sources, as well as with some other source packages.)

For more information, see Tag Tables in The GNU Emacs Manual.