www.delorie.com/gnu/docs/emacs-lisp-intro/emacs-lisp-intro_201.html

search

	Buy the book!

Programming in Emacs Lisp

12.5 Create Your Own `TAGS' File

The M-. (find-tag) command takes you directly to the source for a function, variable, node, or other source. The function depends on tags tables to tell it where to go.

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 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, Java, LaTeX, Pascal, Perl, Python, 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 below the top level of your Emacs source 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 section `Tag Tables' in The GNU Emacs Manual.