An “option file” is a file in which command line options are written 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:
$XDG_CONFIG_HOMEis not defined (on other than Windows)
ctags visits the directories in the order listed above for preloading files.
ctags loads files having
.ctags as file extension in alphabetical
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.
--options=PATHNAME option is specified on
ctags command line,
option files specified are load.
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
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
ctags first checks if
PATHNAME is an absolute path or a relative path.
An absolute path starts with ‘
/’ or ‘
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,
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
For setting (adding one after clearing):
For adding on the beginning of the PATH list:
Tips for writing an option file¶
--quiet --options=NONEto disable preloading.
--_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
optlib2cscript 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.