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:
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_HOME/ctags/
, or$HOME/.config/ctags/
if$XDG_CONFIG_HOME
is not defined$HOME/.ctags.d/
$HOMEDRIVE$HOMEPATH/ctags.d/
(on Windows)./.ctags.d/
./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.