1.. _option_files: 2 3Option files 4~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5.. Q: shouldn't the section about option files (preload especially) go in 6 their own section somewhere else in the docs? They're not specifically 7 for "Extending ctags" - they can be used for any command options that 8 you want to use permanently. It's really the new language parsers using 9 --regex-<LANG> and such that are about "Extending ctags", no? 10 11An "option file" is a file in which command line options are written line 12by line. ``ctags`` loads it and runs as if the options in the file were 13passed through command line. 14 15The following file is an example of an option file: 16 17.. code-block:: ctags 18 19 # Exclude directories that don't contain real code 20 --exclude=Units 21 # indentation is ignored 22 --exclude=tinst-root 23 --exclude=Tmain 24 25The character `#` can be used as a start marker of a line comment. 26Whitespaces at the start of lines are ignored during loading. 27 28And it works exactly as if we had called: 29 30.. code-block:: sh 31 32 ctags --exclude=Units --exclude=tinst-root --exclude=Tmain 33 34Order of loading option files 35...................................................................... 36 37Option files are loaded by ``ctags`` automatically at start-up time. 38 39Which files are loaded at start-up time are very different from Exuberant Ctags. 40See :ref:`option-file_difference` for the differences and their intentions. 41 42At start-up time, ``ctags`` loads files having :file:`.ctags` as a 43file extension under the following statically defined directories: 44 45#. :file:`$XDG_CONFIG_HOME/ctags/`, or :file:`$HOME/.config/ctags/` if :file:`$XDG_CONFIG_HOME` is not defined (on other than Windows) 46#. :file:`$HOME/.ctags.d/` 47#. :file:`$HOMEDRIVE$HOMEPATH/ctags.d/` (on Windows) 48#. :file:`./.ctags.d/` 49#. :file:`./ctags.d/` 50 51``ctags`` visits the directories in the order listed above for preloading files. 52``ctags`` loads files having :file:`.ctags` as file extension in alphabetical 53order (``strcmp(3)`` is used for comparing, so for example 54:file:`.ctags.d/ZZZ.ctags` will be loaded *before* :file:`.ctags.d/aaa.ctags` in an ordinary locale). 55 56If a option file includes ``--options=PATHNAME`` option, specified files are 57loaded immediately as described in the next section. ``ctags`` load a option 58file only once if it is specified multiple times. 59 60Finally if ``--options=PATHNAME`` option is specified on ``ctags`` command line, 61option files specified are load. 62 63``--options=PATHNAME`` option 64...................................................................... 65Exuberant Ctags also has the ``--options`` option, but you can only specify a 66single file to load. Universal Ctags extends the option in two aspects: 67 68- You can specify a directory, to load all the files in that directory. 69- You can specify a PATH list to look in. See next section for details. 70 71Specifying a directory 72,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 73 74If you specify a directory instead of a file as the argument for the 75``--options=PATHNAME``, ``ctags`` will load all files having a 76:file:`.ctags` extension under said directory in alphabetical order. 77 78Specifying an optlib PATH list 79,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 80 81Much like a command line shell, ``ctags`` has an *optlib PATH list* in which it 82can look for a file (or directory) to load. 83 84When loading a file (or directory) specified with ``--options=PATHNAME``, 85ctags first checks if ``PATHNAME`` is an absolute path or a relative path. 86An absolute path starts with '``/``' or '``.``'. 87If ``PATHNAME`` is an absolute path, ctags tries to load it immediately. 88 89If, on the contrary, is a relative path, ``ctags`` does two things: First, 90looks for the file (or directory) in *optlib PATH list* and tries to load it. 91 92If the file doesn't exist in the PATH list, ``ctags`` treats ``PATHNAME`` as a 93path relative to the working directory and loads the file. 94 95By default, *optlib PATH list* is empty. To set or add a directory 96path to the list, use ``--optlib-dir=PATH``. 97 98For setting (adding one after clearing):: 99 100 --optlib-dir=PATH 101 102For adding on the beginning of the PATH list:: 103 104 --optlib-dir=+PATH 105 106Tips for writing an option file 107...................................................................... 108 109* Use ``--quiet --options=NONE`` to disable preloading. 110 111* ``--_echo=MSG`` and ``--_force-quit=[NUM]`` options are introduced for 112 debugging the process of loading option files. See "OPTIONS" 113 section of :ref:`ctags-optlib(7) <ctags-optlib(7)>`. 114 115* Universal Ctags has an ``optlib2c`` script that translates an option file 116 into C source code. Your optlib parser can thus easily become a built-in parser. 117 See :ref:`optlib2c` for details. 118 119.. _option-file_difference: 120 121Difference from Exuberant Ctags 122...................................................................... 123Quoted from man page of Exuberant Ctags: 124 125 FILES 126 - /ctags.cnf (on MSDOS, MSWindows only) 127 - /etc/ctags.conf 128 - /usr/local/etc/ctags.conf 129 - $HOME/.ctags 130 - $HOME/ctags.cnf (on MSDOS, MSWindows only) 131 - .ctags 132 - ctags.cnf (on MSDOS, MSWindows only) 133 134 If any of these configuration files exist, each will 135 be expected to contain a set of default options 136 which are read in the order listed when ctags 137 starts, but before the CTAGS environment variable is 138 read or any command line options are read. This 139 makes it possible to set up site-wide, personal or 140 project-level defaults. It is possible to compile 141 ctags to read an additional configuration file 142 before any of those shown above, which will be 143 indicated if the output produced by the --version 144 option lists the "custom-conf" feature. Options 145 appearing in the CTAGS environment variable or on 146 the command line will override options specified in 147 these files. Only options will be read from these 148 files. Note that the option files are read in 149 line-oriented mode in which spaces are significant 150 (since shell quoting is not possible). Each line of 151 the file is read as one command line parameter (as 152 if it were quoted with single quotes). Therefore, 153 use new lines to indicate separate command-line 154 arguments. 155 156What follows explains the differences and their intentions... 157 158 159Directory oriented configuration management 160,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 161 162Exuberant Ctags provides a way to customize ctags with options like 163``--langdef=<LANG>`` and ``--regex-<LANG>``. These options are 164powerful and make ctags popular for programmers. 165 166Universal Ctags extends this idea; we have added new options for 167defining a parser, and have extended existing options. Defining 168a new parser with the options is more than "customizing" in 169Universal Ctags. 170 171To make easier the maintenance a parser defined using the options, you can put 172each language parser in a different options file. Universal Ctags doesn't 173preload a single file. Instead, Universal Ctags loads all the files having the 174:file:`.ctags` extension under the previously specified directories. If you 175have multiple parser definitions, put them in different files. 176 177Avoiding option incompatibility issues 178,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 179 180The Universal Ctags options are different from those of Exuberant Ctags, 181therefore Universal Ctags doesn't load any of the files Exuberant Ctags loads at 182start-up. Otherwise there would be incompatibility issues if Exuberant Ctags 183loaded an option file that used a newly introduced option in Universal Ctags, 184and vice versa. 185 186No system wide configuration 187,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 188 189To make the preload path list short and because it was rarely ever used, 190Universal Ctags does not load any option files for system wide configuration. 191(i.e., no :file:`/etc/ctags.d`) 192 193Using :file:`.ctags` for the file extension 194,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 195 196Extensions :file:`.cnf` and :file:`.conf` are obsolete. 197Use the unified extension :file:`.ctags` only. 198