1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
.. _option_files:
Option files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. Q: shouldn't the section about option files (preload especially) go in
their own section somewhere else in the docs? They're not specifically
for "Extending ctags" - they can be used for any command options that
you want to use permanently. It's really the new language parsers using
--regex-<LANG> and such that are about "Extending ctags", no?
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:
.. code-block:: ctags
# 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:
.. code-block:: sh
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 :ref:`option-file_difference` for the differences and their intentions.
At start-up time, ``ctags`` loads files having :file:`.ctags` as a
file extension under the following statically defined directories:
#. :file:`$XDG_CONFIG_HOME/ctags/`, or :file:`$HOME/.config/ctags/` if :file:`$XDG_CONFIG_HOME` is not defined (on other than Windows)
#. :file:`$HOME/.ctags.d/`
#. :file:`$HOMEDRIVE$HOMEPATH/ctags.d/` (on Windows)
#. :file:`./.ctags.d/`
#. :file:`./ctags.d/`
``ctags`` visits the directories in the order listed above for preloading files.
``ctags`` loads files having :file:`.ctags` as file extension in alphabetical
order (``strcmp(3)`` is used for comparing, so for example
:file:`.ctags.d/ZZZ.ctags` will be loaded *before* :file:`.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
:file:`.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 :ref:`ctags-optlib(7) <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 :ref:`optlib2c` for details.
.. _option-file_difference:
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
:file:`.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 :file:`/etc/ctags.d`)
Using :file:`.ctags` for the file extension
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
Extensions :file:`.cnf` and :file:`.conf` are obsolete.
Use the unified extension :file:`.ctags` only.
|
