Node:etags, Next:, Previous:forward-paragraph, Up:Regexp Search


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 Tags.