Option files

An “option file” is a file in which command line options are written line by line. ctags loads it and runs as if the options in the file were passed through command line.

The following file is an example of an option file:

# Exclude directories that don't contain real code
--exclude=Units
        # indentation is ignored
        --exclude=tinst-root
--exclude=Tmain

The character # can be used as a start marker of a line comment. Whitespaces at the start of lines are ignored during loading.

And it works exactly as if we had called:

ctags --exclude=Units --exclude=tinst-root --exclude=Tmain

Order of loading option files

Option files are loaded by ctags automatically at start-up time.

Which files are loaded at start-up time are very different from Exuberant Ctags. See Difference from Exuberant Ctags for the differences and their intentions.

At start-up time, ctags loads files having .ctags as a file extension under the following statically defined directories:

1. $XDG_CONFIG_HOME/ctags/, or $HOME/.config/ctags/ if $XDG_CONFIG_HOME is not defined (on other than Windows)

2. $HOME/.ctags.d/

3. $HOMEDRIVE$HOMEPATH/ctags.d/ (on Windows)

4. ./.ctags.d/

5. ./ctags.d/

ctags visits the directories in the order listed above for preloading files. ctags loads files having .ctags as file extension in alphabetical order (strcmp(3) is used for comparing, so for example .ctags.d/ZZZ.ctags will be loaded before .ctags.d/aaa.ctags in an ordinary locale).

If a option file includes --options=PATHNAME option, specified files are loaded immediately as described in the next section. ctags load a option file only once if it is specified multiple times.

Finally if --options=PATHNAME option is specified on ctags command line, option files specified are load.

--options=PATHNAME option

Exuberant Ctags also has the --options option, but you can only specify a single file to load. Universal Ctags extends the option in two aspects:

• You can specify a directory, to load all the files in that directory.

• You can specify a PATH list to look in. See next section for details.

Specifying a directory

If you specify a directory instead of a file as the argument for the --options=PATHNAME, ctags will load all files having a .ctags extension under said directory in alphabetical order.

Specifying an optlib PATH list

Much like a command line shell, ctags has an optlib PATH list in which it can look for a file (or directory) to load.

When loading a file (or directory) specified with --options=PATHNAME, ctags first checks if PATHNAME is an absolute path or a relative path. An absolute path starts with ‘/’ or ‘.’. If PATHNAME is an absolute path, ctags tries to load it immediately.

If, on the contrary, is a relative path, ctags does two things: First, looks for the file (or directory) in optlib PATH list and tries to load it.

If the file doesn’t exist in the PATH list, ctags treats PATHNAME as a path relative to the working directory and loads the file.

By default, optlib PATH list is empty. To set or add a directory path to the list, use --optlib-dir=PATH.

For setting (adding one after clearing):

--optlib-dir=PATH

For adding on the beginning of the PATH list:

--optlib-dir=+PATH

Tips for writing an option file

• Use --quiet --options=NONE to disable preloading.

• --_echo=MSG and --_force-quit=[NUM] options are introduced for debugging the process of loading option files. See “OPTIONS” section of ctags-optlib(7).

• Universal Ctags has an optlib2c script that translates an option file into C source code. Your optlib parser can thus easily become a built-in parser. See Translating an option file into C source code (optlib2c) for details.

Difference from Exuberant Ctags

Quoted from man page of Exuberant Ctags:

FILES

• /ctags.cnf (on MSDOS, MSWindows only)

• /etc/ctags.conf

• /usr/local/etc/ctags.conf

• $HOME/.ctags

• $HOME/ctags.cnf (on MSDOS, MSWindows only)

• .ctags

• ctags.cnf (on MSDOS, MSWindows only)

If any of these configuration files exist, each will be expected to contain a set of default options which are read in the order listed when ctags starts, but before the CTAGS environment variable is read or any command line options are read. This makes it possible to set up site-wide, personal or project-level defaults. It is possible to compile ctags to read an additional configuration file before any of those shown above, which will be indicated if the output produced by the --version option lists the “custom-conf” feature. Options appearing in the CTAGS environment variable or on the command line will override options specified in these files. Only options will be read from these files. Note that the option files are read in line-oriented mode in which spaces are significant (since shell quoting is not possible). Each line of the file is read as one command line parameter (as if it were quoted with single quotes). Therefore, use new lines to indicate separate command-line arguments.

What follows explains the differences and their intentions…

Directory oriented configuration management

Exuberant Ctags provides a way to customize ctags with options like --langdef=<LANG> and --regex-<LANG>. These options are powerful and make ctags popular for programmers.

Universal Ctags extends this idea; we have added new options for defining a parser, and have extended existing options. Defining a new parser with the options is more than “customizing” in Universal Ctags.

To make easier the maintenance a parser defined using the options, you can put each language parser in a different options file. Universal Ctags doesn’t preload a single file. Instead, Universal Ctags loads all the files having the .ctags extension under the previously specified directories. If you have multiple parser definitions, put them in different files.

Avoiding option incompatibility issues

The Universal Ctags options are different from those of Exuberant Ctags, therefore Universal Ctags doesn’t load any of the files Exuberant Ctags loads at start-up. Otherwise there would be incompatibility issues if Exuberant Ctags loaded an option file that used a newly introduced option in Universal Ctags, and vice versa.

No system wide configuration

To make the preload path list short and because it was rarely ever used, Universal Ctags does not load any option files for system wide configuration. (i.e., no /etc/ctags.d)

Using .ctags for the file extension

Extensions .cnf and .conf are obsolete. Use the unified extension .ctags only.