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