IDM PowerTips

CTAGs and UltraEdit

What is Ctags?
Ctags is a program that generates a tag (or index) file of objects and functions found in C/C++ header and source files. The tag file allows these items to be referenced quickly from within UltraEdit.

What does Ctags do?
The purpose of Ctags is to allow you to quickly find a function or object that is defined elsewhere in the active file or another file (i.e. header or source file). You can use this feature to navigate through your project to find the various functions, variables, class members, and so on…

After you have generated your tag file, you simply use the “Find Symbol” in the Search menu to find the symbol (located next to the cursor in the active document) elsewhere in the file(s).

UltraEdit supports Ctags, either as part of a project, or independently.

Using Ctags

Important note: In order to use Ctags, your source code files must be part of an existing project. Please see our projects power tip for more information.

Ctags EXE
UltraEdit relies on an external tag file generator. There are many versions of Ctags; however, we recommend “Exuberant Ctags” available from http://ctags.sourceforge.net/. UltraEdit includes a Ctags EXE in the GNU folder (in the installation directory) as part of the standard installation. Therefore, you would not need to download/install Ctags to use this feature.

UltraEdit can make use of an existing tagfile, or if an EXE for creating Ctags is available it can also create the tag file. If you prefer to use a different Ctags version, you may specify this under Ctag Options in the Project menu.

PLEASE NOTE: IDM Computer Solutions, Inc. does not support Ctags (the program) and we can’t offer definitive answers on how Ctags itself works. We can help with information on standard configuration for integration with UltraEdit and how Ctags should work in conjunction with UltraEdit. For the most comprehensive and up-to-date information regarding Exuberant Ctags please see http://ctags.sourceforge.net/. The latest version of the manual for Exuberant Ctags should be available at http://ctags.sourceforge.net/ctags.html.

Step 1: Create the Tag file

The tag file is the index file of the various functions, class members, etc. In order to use Ctags, you must first create the Tag file.

You can create the Tag file using the Create CTAG file menu item in the Project menu.

If you prefer, you may also select the option Create CTAG file on project load in the Project Settings dialog in the Project Menu. This will cause the Ctags file to be created automatically when the project is loaded. This essentially ensures that you have an updated Ctags file every time you open the project.

Step 2: Find a Symbol/Tag

As we’ve previously discussed, the purpose of Ctags is to be able to quickly find a function or object that is defined elsewhere in the active file or another file (i.e. header or source file).

Using Ctags is simple. When editing source files, you may position the cursor over a function, variable, class member, or macro and press F11. This activates the Find Symbol functionality (in the Search menu) which positions the cursor on the definition of the item you searched for.

If the specified item (symbol) exists in the active document, focus will shift to the appropriate line in the active file. If the specified item (symbol) exists in a different file, that file will be opened to the line where the symbol is defined. Let’s give it a try…

Now that we’ve created the Tag file in Step 1, you may place your cursor next to a symbol or tag (function, class member, variable, etc).

You may now select the Find Symbol item from the Search menu (or press F11). UltraEdit, in conjunction with the Tag file, will search for the symbol.

If only one match is found
The file will be opened (in UltraEdit) and the cursor positioned at the symbol.

If multiple matches occur
A dialog box will be shown giving you the option to position the cursor at the appropriate tag.

If a tag cannot be found
A dialog will be displayed indicating that the tag could not be found.

Using our sample project, the definition of “UpdateClientWindow” was found on line 32 and the cursor is positioned at the beginning of the line.

Ctags Configuration within UltraEdit

As we’ve previously mentioned above, Ctags is intalled as part of the standard installation, so it is not necessary to download/install the Ctags exe. However, UltraEdit does allow you to configure some options in Ctags.

The Ctag Options dialog (in the Project menu) allows you to change options related to Ctags:

The following three items may be defined using the Tag File Options dialog:

Default Tagfile
This specifies the tagfile to be used if there is not a specific project tagfile active (defined in the Project Settings dialog under the Project menu). Note: This must be present if there is not a project-specific tagfile for UltraEdit to look up the symbols associated with the active project.

Ctag EXE Path/Name
This specifies the full path and name of the Ctag exe that will be run to create the tag file from within UltraEdit. UltraEdit can reference a tagfile for symbols if this is not present, but it can not create a new Tag file. The default setting for this is “ctags.exe” in the “GNU” subdirectory under the UltraEdit installation directory.

CTAG Parameters
This specifies the parameters to be passed to the Ctags exe for it to function correctly. The default settings ( -L %fi -f %fo ) are configured for Exuberant Ctags as described above.

Troubleshooting/Tips

 

What does “-L %fi -f %fo” mean?

-L file This instructs Ctags to read from file a list of file names for which tags should be generated. If file is specified as “−”, then file names are read from standard input. File names read using this option are processed following file names appearing on the command line. Options are also accepted in this input. If this option is specified more than once, only the last will apply.

Note: File is read in line-oriented mode, where a new line is the only delimiter and non-trailing white space is considered significant, in order that file names containing spaces may be supplied (however, trailing white space is stripped from lines); this can affect how options are parsed if included in the input.

%fi
%fi on the parameter line is replaced when the ctag exe is run with the filename/path of a file that contains a list of files that the ctags.exe will use to create its tags from. If a project is loaded in UltraEdit, UltraEdit creates a temporary file with a list of the project files and passes this in place of %fi.

-f tagfile
-f tagfile instructs Ctags to use the name specified by tagfile for the tag file (default is “tags”, or “TAGS” when running in etags mode). If tagfile is specified as “−”, then the tag file is written to standard output instead. Ctags will stubbornly refuse to take orders if tagfile exists and its first line contains something other than a valid tags line. This will save your neck if you mistakenly type “ctags −f *.c”, which would otherwise overwrite your first C file with the tags generated by the rest! It will also refuse to accept a multi-character file name which begins with a ’−’ (dash) character, since this most likely means that you left out the tag file name and this option tried to grab the next option as the file name. If you really want to name your output tag file “−ugly”, specify it as “./−ugly”. This option must appear before the first file name. If this option is specified more than once, only the last will apply.

%fo
%fo on the parameter line is replaced with the full filename/path of the tag file to be created. This would be the tag file specified in the project, or the Default Tagfile defined above.

All Options
For further options for Exuberant Ctags please see http://ctags.sourceforge.net/ctags.html.

 

Why aren’t the tags in my files being mapped?

–langmap=map[,map[…]] controls how file names are mapped to languages (see SOURCE FILES, at http://ctags.sourceforge.net/ctags.html). Each comma-separated map consists of the language name (either a built-in or user-defined language), a colon, and a list of file extensions and/or file name patterns. A file extension is specified by preceding the extension with a period (e.g. “.c”). A file name pattern is specified by enclosing the pattern in parentheses (e.g. “([Mm]akefile)”). If appropriate support is available from the runtime library of your C compiler, then the file name pattern may contain the usual shell wildcards common on Unix (be sure to quote the option parameter to protect the wildcards from being expanded by the shell before being passed to ctags). You can determine if shell wildcards are available on your platfom by examining the output of the –version option, which will include “+wildcards” in the compiled feature list; otherwise, the file name patterns are matched against file names using a simple textual comparison.

If the first character in a map is a plus sign, then the extensions and file name patterns in that map will be appended to the current map for that language; otherwise, the map will replace the current map. For example, to specify that only files with extensions of .c and .x are to be treated as C language files, use “–langmap=c:.c.x“; to also add files with extensions of .j as Java language files, specify “–langmap=c:.c.x,java:+.j“. To map makefiles (.e.g files named either “Makefile”, “makefile”, or having the extension “.mak”) to a language called “make”, specify “–langmap=make:([Mm]akefile).mak“. To map files having no extension, specify a period not followed by a non-period character (e.g. “.”, “..x”, “.x.”). To clear the mapping for a particular language (thus inhibiting automatic generation of tags for that language), specify an empty extension list (e.g. “–langmap=fortran:“). To restore the default language mappings for all a particular language, supply the keyword “default” for the mapping. To specify restore the default language mappings for all languages, specify “–langmap=default“. Note that file extensions are tested before file name patterns when inferring the language of a file.

If you were to specify this in the Ctag Options dialog in the Project menu you could use
“–langmap=c:.c.x -L %fi -f %fo” with the default parameters so that files with a “.x” extension would be parsed as C files. The “-L” option which indicates that the files to be parsed are to be read from the specified file would still require that these files be part of the project for this to work.

 

How can I keep the Find Symbol function from going to a matching but incorrect tag?

The -n option may be added so that only line numbers would be used in the tag file for locating tags. This has four advantages:

1. Significantly reduces the size of the resulting tag file.

2. Eliminates failures to find tags because the line defining the tag has changed, causing the pattern match to fail.

3. Eliminates finding identical matching, but incorrect, source lines.

4. Retains separate entries in the tag file for lines which are identical in content.