CTAGS Help

CTAGS
Symbol lookup

Ctags generates an index (or tag) file of language objects found in source files that allows these items to be quickly and easily located by Vedit.

The "ctags" facility is useful to programmers that are working on large programs, particularly programs that consist of many files. Once setup, you can place the cursor on any function (subroutine) or symbol name and select {MISC, More macros, Utags} or press a hot-key (default: <Ctrl-F12>) to lookup the symbol. VEDIT will open the file in which the symbol is declared, with the cursor on the symbol's declaration. You can then press another hot-key (default: <Ctrl-Shift-F12>)) to return to the original file/location.

As supplied, ctags.vdm supports C, Assembly language and Fortran modules. Item types supported include functions, macros and constants.

Ctags.vdm also supports a user specified symbol "search" string for other languages. It could also be used for non-programming applications.

Ctags.vdm works similar to the WILDFILE macro. At the files field of the dialog box, you enter a wildcard specification such as "*.c", "*.h" and "*.asm". It then processes all specified files in the directory given in directory field, and optionally in all subdirectories. After that, you can append more files from another directory and so on.

There is no limit in the database size. VEDIT's ctags facility therefore supports the biggest projects, even those with thousands of files in many subdirectories.

The format of the generated tags file is identical to that produced by the UNIX "ctags" utility. Therefore, as an alternative to the ctags.vdm macro, you should be able to produce the tags file with any utility that is "ctags" compatible.

The "ctags" facility consists of two macro files:
  • Ctags.vdm creates the tags database file with symbol declarations.
  • Utags.vdm performs the lookup function.

For details on using ctags facility, see the following topics:


Ctags.vdm - setting up tags database

Ctags.vdm
Setting up tags database

To use ctags facility, you must first create the tags database, typically in the main project directory. This is done with the macro ctags.vdm.

To start ctags.vdm, select { MISC, More macros, Ctags }
or { User -> Create Ctags file } (assuming you are using the standard User menu).
The main dialog box is now displayed:

Ctags.vdm main dialog

Ctags.vdm dialog box

The dialog box contains the following fields:

Tags dir
The directory where tags database file and ctags.ini file are stored.

Default is the directory of any existing tags file, if one is found. On startup, ctags.vdm searches for any existing tags file or ctags.ini file, first from current file's directory, then from it's parent directory, then from the parent directory of that directory, and so on, until it finds either the tags file or ctags.ini file. If either one is found, it's directory is filled as default in the Tags dir field. If existing tags file or ctags.ini file is not found, current file's directory is used as default.

Append to existing "tags" file
Tick this option to append symbols found in specified files into existing tags file. If this option is not ticked, old tags file is erased and a new one is created.
If old tags file is not found, this checkbox is grayed.
Files
Enter file filter for source files from which you want to collect symbols, for example *.c or *.asm.
Directory
Base directory where to search for specified files. You can enter the directory path in the input field, or use the Browse button below it.
[ Browse ]
Click this button to select base directory. Navigate to the required directory and then click OK.
Search subdirectories
Check this tickbox to recursively search all subdirectories of the directory specified above.
Language
Programming language used in source files selected above: C, Assembler or Fortran.
Or select "Symbol recognition pattern..." to specify your own search pattern (in which case you will be prompted for the search pattern and options after you click OK).
Type of items to add
Check one or more of the tick boxes: Functions, Macros (preprocessor macros that may look like a function) and Constants (#define) that you want to include in tags. In current version, functions are supported with all languages, macros are supported with C and Assembly, and constants are only supported with C. If you select "Symbol recognition pattern...", these options are ignored.
[ Add files to tags ]
After you have selected all the options above, click this button to start generating tags database.
[ Batch ]
Go to Batch processing dialog (see below).
[ Help ]
Open the help application. Displays help both for ctags.vdm and utags.vdm.
[ Cancel ]
Cancel the operation and exit macro.

To create a "tags" database:

  1. Start the ctags.vdm macro (see above).
  2. Select the directory for tags database file. You can enter the path in the Tags dir field. Or click the button [Tags dir], browse to the directory where you want tags file to be stored and click [ OK ].

    You should put tags file in the directory where your source files are located. If your project consists of multiple directories, you should put tags file in the root of your project directory tree. This way, utags.vdm will find the file wherever in the directory tree you are.

  3. If the tags file was found, you have option to append new items to it by checking the checkbox Append to existing tags file. If the checkbox is not checked, old tags file is erased and replaced with new one. If old tags file was not found, this option is gray.
  4. In the Files field, enter file specification, typically using the wildcard characters "*" and "?". E.g., enter "*.c" or "*.asm".
  5. In the Directory field, enter the base directory where to search for the specified files. Or click the [ Browse ] button to choose the directory using File Open dialog box. Navigate to the reguired directory and then click OK to return to main dialog.
  6. Check the tickbox Search subdirectories to process all matching files in all subdirectories if required.
  7. Choose the lagnuage used in your source files (C, Assembler, Fortran), or choose "Symbol recognition pattern" to specify your own search pattern for other languages.
  8. In "Type(s) of items to add" section, select what kind of symbols you want to add to database.
  9. After you have selected all the options, click OK button to start processing.

During the processing, the names of the files processed are displayed on the screen, and the number of files and number of symbols found are displayed on status line.

After all the files have been processed, the main dialog box opens again. Number of symols and files added to TAGS database are displayed at the bottom of dialog. [Cancel] button has changed into [Exit] if there are no more settings in the .ini file.

You can then continue to add more files. (Append tickbox is now automatically ticked.) When you have finished adding files, click [Exit] button to exit the macro.

"Symbol recognition pattern" dialog box

Symbol recognition pattern dialog box

If you selected "Symbol recognition pattern" radio button, this dialog box is presented after you click [ Add files to TAGS ]. Enter the rearch string and options to seach for symbols to be included in TAGS database.

Pattern
The search pattern for symbols to be included in TAGS database.
Search mode
As in the standard Search dialog box.
- Simple = Handle search string as it is, no special control codes used
- Pattern = Vedit's own pattern matching codes that start with character '|'.
- Regular Expression = Standard regular expression search pattern, find shortest possible match
- Reg-Exp (Max) = Regular expressions, find longest possible match on single line
Options
- Case sensitive = Upper case and lower case letters are considered to be different characters
- Word = Searched pattern must be a word, not part of a longer word.
[ OK ]
Click OK button to start processing
[ Help ]
Show help for this dialog (and Ctags facility in general).
[ Cancel ]
Cancel operation and return to main dialog.

Batch Processing

Batch Processing allows you to re-build tags database in one go. It uses command file saved earlier to perform all the operations necessary to include all the different types of symbols from all the directories specified.

To open Batch Processing dialog box, click [ Batch ] button on the main dialog. The dialog box contains the following fields:

Batch Processing dialog box
Tags dir
The directory where tags database file and ctags.ini file are stored, as in the main dialog.
Append to existing "tags" file
Normally, this checkbox should be un-checked, since the whole tags database is created in one go.
File
The command file (*.ini) that contains all the settings. The default is file ctags.ini in the same directory tags (if one is found when ctags.vdm was started). However, you can change this to any other file, either by entering the filename and path in the input box, or by clicking the [ Browse ] button and then selecting the file graphically.
[ Generate TAGS ]
Click this button to start processing the files. After all the files have been processed, you will return to the main dialog box.
[ < Back ]
Exit batch processing dialog and return to main menu
[ Help ]
Display online help on Batch Processing (and Ctags facility in general).
[ Cancel ]
Cancel operation and exit Ctags.vdm macro.

Technical details

Saved settings

Ctags.vdm remembers the settings you have choosen. The settings are stored in file ctags.ini, which is stored in the same directory as the tags database (local .ini file). This allows you to have different configuration for each project, and the settings stored match the actual tags database.

If ctags.ini is not found in your project's folder structure, global ctags.ini file in Vedit user-mac directory is used. This file only contains the settings you used last, not all the settings needed to build tags database. Further, it does not contain the directory setting. Instead, current file's directory is used as default in the dialog.

The local ctags.ini file stores all the settings used for creating the tags database. That is, if you append files to TAGS from several directory trees, or process different file types (.c, .h, .asm etc.), all the settings are stored. When you start ctags.vdm next time, the first settings used for creating the TAGS database are loaded by default, so you can more easily repeat the process from the beginning.

You can process files with the old settings by just pressing Enter, or you can change the settings first. After you have run the first set, the new set of options is automatically fetched from ctags.ini. You can re-create the TAGS database step by step by just pressing Enter a few times. When all the settings in .ini file have been processed, the settings do not change any more, [Cancel] button changes to [Exit], and the message "Click [Exit] to finish adding files" is displayed on the dialog.

Click Exit if you just wanted to update the database. But you can continue add more symbols if you want.

Calling Batch Processing directly

You can select batch processing mode directly when calling ctags.vdm (for example from the User menu).
Call label BATCH_AUTO to run batch processing with the default search.ini file.
Call label BATCH_SET to select another .ini file. In this case, the filename must be given in text register 40.

Examples:
Call_File(100,"ctags.vdm","BATCH_AUTO")
RS(40,"ctag1.ini") Call_File(100,"ctags.vdm","BATCH_SET")

Or, you can call ctags.vdm from DOS command line or .BAT file:

Examples:
c:\vedit\vpw -q -c'Call_File(100,"ctags.vdm","BATCH_AUTO")'
c:\vedit\vpw -q -c'RS(40,"ctag1.ini") Call_File(100,"ctags.vdm","BATCH_SET")'

If the -q option is given, ctags.vdm runs quietly without displaying anything. When done, Vedit is closed.
If the -q option is not given, the filenames are displayed while processing as normally. When done, ctags.vdm dialog box stays open displaying the number of items found.

DOS mode

If you call ctags.vdm from DOS version of Vedit, text-mode input window is displayed instead of dialog box. You will be presented series of questions for filenames, type of patterns to search etc. After you have given all the necessary information, the processing begins.

You can force text mode interface in Windows version of Vedit (perhaps to automate your work by using input redirection) by calling label DOS_MODE, e.g

c:\vedit\vpw -c'Call_File(100,"ctags.vdm","DOS_MODE")'

However, since ctags.vdm now supports Batch Processing, it is no more necessary to use input redirection for automating tags file creation.

See also:

CTAGS Symbol lookup - General information about ctags facility.
Utags.vdm - Lookup from tags database
Setting up User Menu and Keyboard shortcuts


Utags.vdm - Lookup from tags database

Utags.vdm
Lookup from tags database

The utags.vdm macro is used to lookup symbols from the tags database created with ctags.vdm or with an external ctags program.

Put the tags file in the root of your project's folder structure. This way, it is found even if you are editing a file in one of the sub-folders. Utags.vdm searches for the tags file first from current file's directory, then from it's parent directory, then from the parent directory of that directory, and so on. If tags file is not found, an error message is diplayed on status line and the macro exits.

To lookup for a symbol (function, macro or constant), put cursor on the symbol in your source file and run utags.vdm.
To run utags.vdm, either
  • select Misc -> More macros -> UTAGS or
  • select User -> Lookup in Ctags (assuming you are using user menu that contains this option) or
  • press your hotkey (Ctrl-F12 recommended)

The file that contains the definition of the function, macro or constant is now opened and cursor is moved to correct location in the file.

If no symbol name is found at cursor location when you call Utags.vdm, a dialog box opens to inform you about this. You can then enter the symbol in the input field (or paste it from clipboard by pressing Ctrl-V). This allows you to search for a symbol that is not called in the currently open file. Or click [ Cancel ] and then move cursor to symbol location in the source file and try again.

If a (small) block is highlighted when utags.vdm is called, the block is used as symbol name. This allows you to specify exactly what you are searching for.

If there are multiple instances of the definition (e.g. different versions of the same file, or different versions of a function using #if's), the first instance is located immediatelly, but in addition, a message such as "Match 1 of 3" is displayed on status line. You can then call Utags again to show the next occurrence, and so on (the cursor must be on the function name, of course). After the last occurrence is displayed, the first occurrence is displayed again.

Utags.vdm has multi-level return function. Each time you jump to function/symbol definition using utags.vdm, the original location is stored in file utag_stack.tmp. You can then return to original location by pressing the hotkey (Ctrl-Shift-F12 recommended, see below). There is no limit in how many levels of return can be stored in the stack.

Utags.vdm returns to previous location only if that file is still open in Vedit. If the file is not open, utags.vdm skips that location and fetches previous location from the stack. When no more return locations are in the stack, message "No more files to return to" is displayed on status line.

For easy access to Utags.vdm and Ctags.vdm, add calls for the macros in your User Menu, and then add keyboard shortcuts for those menu items. For details, see Setting up User Menu and Keyboard shortcuts.

Configuring utags.vdm

You can change the vay utags.vdm works by editing options near the beginning of utags.vdm
#60 = 1		//#60 determines what is done when the symbol is found:
1 - Simply switch to the symbol's definition file.
2 - Cascade all windows with symbol's definition file on top.
3 - Switch to the symbol's definition file; assign Ctrl-Shft-F12 to switch back to original file.

If option 3 is selected, help window is displayed on bottom of the screen giving information about the key configuration. The help window remains visible as long as there are items in the return stack.

In most cases, option 0 is the best choice. Option 3 is not needed if you have configured the Ctrl-Shft-F12 key by default (see the link above).

#68 = 0		//#68 can be set for compatibility with TAGS file created by other utility.
0 - Normal mode (tags file created by ctags.vdm)
1 - Compatibility mode. Remove quote characters '\' from search string (regular expressions)

Compatibility with other Ctags tools

Utags.vdm is compatible with tags files created with Unix ctags facility or other Ctags tools. However, note the following details about tags file structure:

  • The tags file needs not to be sorted. Utags.vdm searches the file in linear order. If there are multiple occurrences of a symbol, they are presented in the order they are listed in tags.
  • The filename in tags file may have full path or relative path. If relative path is used, it is relative to the location of tags database file.
  • The command used to locate the symbol can be either a search string or a line number.
  • If search string is used, it is assumed to be delimited text string embedded between the regular expression characters '^' and '$' (begin and end of line). No other regular expressions patterns are expected.

Ctags.vdm does not quote any characters inside the search string. If you are using tags database created with some other ctags tool, it may contain quote characters (\). In this case, you need to configure utags.vdm to remove quote characters by setting register #68 = 1, as described in "Configuring utags.vdm" above.

See also:

CTAGS Symbol lookup - General information about ctags facility.
Ctags.vdm - Setting up tags database
Setting up User Menu and Keyboard shortcuts


Setting up User Menu and keyboard shortcuts for Ctags

Setting up User Menu and Keyboard shortcuts

To make it easier to call utags, add the following lines in the User Menu (if not already there):

6
Create Ctags file
#124=Reg_Free Call_File(#124,"ctags.vdm") Reg_Empty(#124)

12
Lookup in Ctags
#124=Reg_Free Call_File(#124,"utags.vdm") Reg_Empty(#124)

16
Return from Ctags file
#124=Reg_Free Call_File(#124,"utags.vdm","GO_BACK") Reg_Empty(#124)

(In the above menu configuration, hotkeys E, T and G are used. You may need to change these if they are already used in your User Menu.)

Then configure shortcut keys to these menu items. You can do this for example by using Config -> Keyboard -> Record macro. After recording the key macro, save your keyboard configuration, or save your project.

Alternatively, you can add the following definitions directly to the vedit.key file:

  Ctrl-F12              [MENU]UT
  Ctrl-Shift-F12        [MENU]UG

These are calls to "Lookup in Ctags" and "Return from Ctags file", respectively. ("Create Ctags file" is used less often, so you may not need to add shortcut key for it.)

See also:

CTAGS Symbol lookup - General information about ctags facility.
Ctags.vdm - Setting up tags database
Utags.vdm - Lookup from tags database