1187 lines
50 KiB
Groff
1187 lines
50 KiB
Groff
.TH CTAGS 1 "Version @VERSION@" "Darren Hiebert" "Exuberant Ctags"
|
|
|
|
|
|
.SH "NAME"
|
|
ctags \- Generate tag files for source code
|
|
|
|
|
|
.SH SYNOPSIS
|
|
.TP 6
|
|
\fBctags\fP [\fBoptions\fP] [\fIfile(s)\fP]
|
|
.TP 6
|
|
\fBetags\fP [\fBoptions\fP] [\fIfile(s)\fP]
|
|
|
|
|
|
.SH "DESCRIPTION"
|
|
The \fBctags\fP and \fBetags\fP programs (hereinafter collectively referred to
|
|
as \fBctags\fP, except where distinguished) generate an index (or "tag") file
|
|
for a variety of language objects found in \fIfile(s)\fP.
|
|
This tag file allows these items to be quickly and easily located by a text
|
|
editor or other utility. A "tag" signifies a language object for which an
|
|
index entry is available (or, alternatively, the index entry created for that
|
|
object).
|
|
|
|
Alternatively, \fBctags\fP can generate a cross reference file which lists, in
|
|
human readable form, information about the various source objects found in a
|
|
set of language files.
|
|
|
|
Tag index files are supported by numerous editors, which allow the user to
|
|
locate the object associated with a name appearing in a source file and jump
|
|
to the file and line which defines the name. Those known about at the time of
|
|
this release are:
|
|
|
|
.RS 4
|
|
\fBVi\fP(1) and its derivatives (e.g. Elvis, Vim, Vile, Lemmy),
|
|
\fBCRiSP\fP,
|
|
\fBEmacs\fP,
|
|
\fBFTE\fP (Folding Text Editor),
|
|
\fBJED\fP,
|
|
\fBjEdit\fP,
|
|
\fBMined\fP,
|
|
\fBNEdit\fP (Nirvana Edit),
|
|
\fBTSE\fP (The SemWare Editor),
|
|
\fBUltraEdit\fP,
|
|
\fBWorkSpace\fP,
|
|
\fBX2\fP,
|
|
\fBZeus\fP
|
|
.RE
|
|
|
|
\fBCtags\fP is capable of generating different kinds of tags for each of many
|
|
different languages. For a complete list of supported languages, the names
|
|
by which they are recognized, and the kinds of tags which are generated for
|
|
each, see the \fB\-\-list\-languages\fP and \fB\-\-list\-kinds\fP options.
|
|
|
|
|
|
.SH "SOURCE FILES"
|
|
|
|
Unless the \fB\-\-language\-force\fP option is specified, the language of each
|
|
source file is automatically selected based upon a mapping of file names to
|
|
languages. The mappings in effect for each language may be display using the
|
|
\fB\-\-list\-maps\fP option and may be changed using the \fB\-\-langmap\fP option.
|
|
On platforms which support it, if the name of a file is not mapped
|
|
to a language and the file is executable, the first line of the file is
|
|
checked to see if the file is a "#!" script for a recognized language.
|
|
|
|
By default, all other files names are ignored. This permits running
|
|
\fBctags\fP on all files in either a single directory (e.g. "ctags *"), or on
|
|
all files in an entire source directory tree (e.g. "ctags \-R"), since only
|
|
those files whose names are mapped to languages will be scanned.
|
|
|
|
[The reason that .h extensions are mapped to C++ files rather than C files
|
|
is because it is common to use .h extensions in C++, and no harm results in
|
|
treating them as C++ files.]
|
|
|
|
|
|
.SH "OPTIONS"
|
|
|
|
Despite the wealth of available options, defaults are set so that \fBctags\fP
|
|
is most commonly executed without any options (e.g. "ctags *", or "ctags \-R"),
|
|
which will create a tag file in the current directory for all recognized
|
|
source files. The options described below are provided merely to allow custom
|
|
tailoring to meet special needs.
|
|
|
|
Note that spaces separating the single-letter options from their parameters
|
|
are optional.
|
|
|
|
Note also that the boolean parameters to the long form options (those
|
|
beginning with "\-\-" and that take a "\fI[=yes\fP|\fIno]\fP" parameter) may
|
|
be omitted, in which case "\fB=\fP\fIyes\fP" is implied. (e.g. \fB\-\-sort\fP
|
|
is equivalent to \fB\-\-sort\fP=\fIyes\fP). Note further that "=\fI1\fP" and
|
|
"=\fIon\fP" are considered synonyms for "=\fIyes\fP", and that "=\fI0\fP"
|
|
and "=\fIoff\fP" are considered synonyms for "=\fIno\fP".
|
|
|
|
Some options are either ignored or useful only when used while running in
|
|
etags mode (see \fB\-e\fP option). Such options will be noted.
|
|
|
|
Most options may appear anywhere on the command line, affecting only those
|
|
files which follow the option. A few options, however, must appear before the
|
|
first file name and will be noted as such.
|
|
|
|
Options taking language names will accept those names in either upper or lower
|
|
case. See the \fB\-\-list\-languages\fP option for a complete list of the
|
|
built-in language names.
|
|
|
|
.TP 5
|
|
.B \-a
|
|
Equivalent to \fB\-\-append\fP.
|
|
|
|
.TP 5
|
|
.B \-B
|
|
Use backward searching patterns (e.g. ?pattern?). [Ignored in etags mode]
|
|
|
|
.TP 5
|
|
.B \-e
|
|
Enable etags mode, which will create a tag file for use with the Emacs editor.
|
|
Alternatively, if \fBctags\fP is invoked by a name containing the string
|
|
"etags" (either by renaming, or creating a link to, the executable), etags
|
|
mode will be enabled. This option must appear before the first file name.
|
|
|
|
.TP 5
|
|
.BI \-f " tagfile"
|
|
Use the name specified by \fItagfile\fP for the tag file (default is "tags",
|
|
or "TAGS" when running in etags mode). If \fItagfile\fP is specified as
|
|
"\-", then the tag file is written to standard output instead. \fBCtags\fP
|
|
will stubbornly refuse to take orders if \fItagfile\fP exists and its first
|
|
line contains something other than a valid tags line. This will save your neck
|
|
if you mistakenly type "ctags \-f *.c", which would otherwise overwrite your
|
|
first C file with the tags generated by the rest! It will also refuse to
|
|
accept a multi-character file name which begins with a '\-' (dash) character,
|
|
since this most likely means that you left out the tag file name and this
|
|
option tried to grab the next option as the file name. If you really want to
|
|
name your output tag file "\-ugly", specify it as "./\-ugly". This option must
|
|
appear before the first file name. If this option is specified more than once,
|
|
only the last will apply.
|
|
|
|
.TP 5
|
|
.B \-F
|
|
Use forward searching patterns (e.g. /pattern/) (default).
|
|
[Ignored in etags mode]
|
|
|
|
.TP 5
|
|
.BI \-h " list"
|
|
Specifies a list of file extensions, separated by periods, which are to be
|
|
interpreted as include (or header) files. To indicate files having no
|
|
extension, use a period not followed by a non-period character (e.g. ".",
|
|
"..x", ".x."). This option only affects how the scoping of a particular kinds
|
|
of tags is interpreted (i.e. whether or not they are considered as globally
|
|
visible or visible only within the file in which they are defined); it does
|
|
not map the extension to any particular language. Any tag which is located in
|
|
a non-include file and cannot be seen (e.g. linked to) from another file is
|
|
considered to have file-limited (e.g. static) scope. No kind of tag appearing
|
|
in an include file will be considered to have file-limited scope. If the first
|
|
character in the list is a plus sign, then the extensions in the list will be
|
|
appended to the current list; otherwise, the list will replace the current
|
|
list. See, also, the \fB\-\-file\-scope\fP option. The default list is
|
|
".h.H.hh.hpp.hxx.h++.inc.def". To restore the default list, specify \fB\-h\fP
|
|
\fIdefault\fP. Note that if an extension supplied to this option is not
|
|
already mapped to a particular language (see \fBSOURCE FILES\fP, above), you
|
|
will also need to use either the \fB\-\-langmap\fP or \fB\-\-language\-force\fP
|
|
option.
|
|
|
|
.TP 5
|
|
.BI \-I " identifier\-list"
|
|
Specifies a list of identifiers which are to be specially handled while
|
|
parsing C and C++ source files. This option is specifically provided to handle
|
|
special cases arising through the use of preprocessor macros. When the
|
|
identifiers listed are simple identifiers, these identifiers will be ignored
|
|
during parsing of the source files. If an identifier is suffixed with a '+'
|
|
character, \fBctags\fP will also ignore any parenthesis-enclosed argument list
|
|
which may immediately follow the identifier in the source files. If two
|
|
identifiers are separated with the '=' character, the first identifiers is
|
|
replaced by the second identifiers for parsing purposes. The list of
|
|
identifiers may be supplied directly on the command line or read in from a
|
|
separate file. If the first character of \fIidentifier\-list\fP is '@', '.' or
|
|
a pathname separator ('/' or '\\'), or the first two characters specify a
|
|
drive letter (e.g. "C:"), the parameter \fIidentifier\-list\fP will be
|
|
interpreted as a filename from which to read a list of identifiers, one per
|
|
input line. Otherwise, \fIidentifier\-list\fP is a list of identifiers (or
|
|
identifier pairs) to be specially handled, each delimited by a either a comma
|
|
or by white space (in which case the list should be quoted to keep the entire
|
|
list as one command line argument). Multiple \fB\-I\fP options may be supplied.
|
|
To clear the list of ignore identifiers, supply a single dash ("\-") for
|
|
\fIidentifier\-list\fP.
|
|
|
|
This feature is useful when preprocessor macros are used in such a way that
|
|
they cause syntactic confusion due to their presence. Indeed, this is the best
|
|
way of working around a number of problems caused by the presence of
|
|
syntax-busting macros in source files (see \fBCAVEATS\fP, below). Some
|
|
examples will illustrate this point.
|
|
|
|
.RS 8
|
|
int foo ARGDECL4(void *, ptr, long int, nbytes)
|
|
.RE
|
|
|
|
.IP
|
|
In the above example, the macro "ARGDECL4" would be mistakenly interpreted to
|
|
be the name of the function instead of the correct name of "foo". Specifying
|
|
\fB\-I\fP \fIARGDECL4\fP results in the correct behavior.
|
|
|
|
.RS 8
|
|
/* creates an RCS version string in module */
|
|
.br
|
|
MODULE_VERSION("$Revision$")
|
|
.RE
|
|
|
|
.IP
|
|
In the above example the macro invocation looks too much like a function
|
|
definition because it is not followed by a semicolon (indeed, it could even be
|
|
followed by a global variable definition that would look much like a K&R style
|
|
function parameter declaration). In fact, this seeming function definition
|
|
could possibly even cause the rest of the file to be skipped over while trying
|
|
to complete the definition. Specifying \fB\-I\fP \fIMODULE_VERSION+\fP would
|
|
avoid such a problem.
|
|
|
|
.RS 8
|
|
CLASS Example {
|
|
.br
|
|
// your content here
|
|
.br
|
|
};
|
|
.RE
|
|
|
|
.IP
|
|
The example above uses "CLASS" as a preprocessor macro which expands to
|
|
something different for each platform. For instance CLASS may be defined as
|
|
"class __declspec(dllexport)" on Win32 platforms and simply "class" on UNIX.
|
|
Normally, the absence of the C++ keyword "class" would cause the source file
|
|
to be incorrectly parsed. Correct behavior can be restored by specifying
|
|
\fB\-I\fP \fICLASS=class\fP.
|
|
|
|
.TP 5
|
|
.BI \-L " file"
|
|
Read from \fIfile\fP a list of file names for which tags should be generated.
|
|
If \fIfile\fP is specified as "\-", then file names are read from standard
|
|
input. File names read using this option are processed following file names
|
|
appearing on the command line. Options are also accepted in this input. If
|
|
this option is specified more than once, only the last will apply. \fBNote:\fP
|
|
\fIfile\fP is read in line-oriented mode, where a new line is the only
|
|
delimiter and non-trailing white space is considered significant, in order
|
|
that file names containing spaces may be supplied (however, trailing white
|
|
space is stripped from lines); this can affect how options are parsed if
|
|
included in the input.
|
|
|
|
.TP 5
|
|
.B \-n
|
|
Equivalent to \fB\-\-excmd\fP=\fInumber\fP.
|
|
|
|
.TP 5
|
|
.B \-N
|
|
Equivalent to \fB\-\-excmd\fP=\fIpattern\fP.
|
|
|
|
.TP 5
|
|
.BI \-o " tagfile"
|
|
Equivalent to \fB\-f\fP \fItagfile\fP.
|
|
|
|
.TP 5
|
|
.B \-R
|
|
Equivalent to \fB\-\-recurse\fP.
|
|
|
|
.TP 5
|
|
.B \-u
|
|
Equivalent to \fB\-\-sort\fP=\fIno\fP (i.e. "unsorted").
|
|
|
|
.TP 5
|
|
.B \-V
|
|
Equivalent to \fB\-\-verbose\fP.
|
|
|
|
.TP 5
|
|
.B \-w
|
|
This option is silently ignored for backward-compatibility with the ctags
|
|
of SVR4 Unix.
|
|
|
|
.TP 5
|
|
.B \-x
|
|
Print a tabular, human-readable cross reference (xref) file to standard output
|
|
instead of generating a tag file. The information contained in the output
|
|
includes: the tag name; the kind of tag; the line number, file name, and
|
|
source line (with extra white space condensed) of the file which defines the
|
|
tag. No tag file is written and all options affecting tag file output will be
|
|
ignored. Example applications for this feature are generating a listing of all
|
|
functions located in a source file (e.g. \fBctags \-x \-\-c\-kinds\fP=\fIf\fP
|
|
\fIfile\fP), or generating a list of all externally visible global variables
|
|
located in a source file (e.g. \fBctags \-x \-\-c\-kinds\fP=\fIv\fP
|
|
\fB\-\-file\-scope\fP=\fIno file\fP). This option must appear before the first
|
|
file name.
|
|
|
|
.TP 5
|
|
\fB\-\-append\fP[=\fIyes\fP|\fIno\fP]
|
|
Indicates whether tags generated from the specified files should be appended
|
|
to those already present in the tag file or should replace them. This option
|
|
is off by default. This option must appear before the first file name.
|
|
|
|
.TP 5
|
|
\fB\-\-etags\-include\fP=\fIfile\fP
|
|
Include a reference to \fIfile\fP in the tag file. This option may be
|
|
specified as many times as desired. This supports Emacs' capability to use a
|
|
tag file which "includes" other tag files. [Available only in etags mode]
|
|
|
|
.TP 5
|
|
\fB\-\-exclude\fP=[\fIpattern\fP]
|
|
Add \fIpattern\fP to a list of excluded files and directories. This option
|
|
may be specified as many times as desired. For each file name considered by
|
|
\fBctags\fP, each \fIpattern\fP specified using this option will be compared
|
|
against both the complete path (e.g. some/path/base.ext) and the base name
|
|
(e.g. base.ext) of the file, thus allowing patterns which match a given file
|
|
name irrespective of its path, or match only a specific path. If appropriate
|
|
support is available from the runtime library of your C compiler, then
|
|
\fIpattern\fP may contain the usual shell wildcards (not regular expressions)
|
|
common on Unix (be sure to quote the option parameter to protect the wildcards
|
|
from being expanded by the shell before being passed to \fBctags\fP; also be
|
|
aware that wildcards can match the slash character, '/'). You can determine if
|
|
shell wildcards are available on your platform by examining the output of the
|
|
\fB\-\-version\fP option, which will include "+wildcards" in the compiled
|
|
feature list; otherwise, \fIpattern\fP is matched against file names using a
|
|
simple textual comparison.
|
|
|
|
If \fIpattern\fP begins with the character '@', then the rest of the string
|
|
is interpreted as a file name from which to read exclusion patterns, one per
|
|
line. If \fIpattern\fP is empty, the list of excluded patterns is cleared.
|
|
Note that at program startup, the default exclude list contains "EIFGEN",
|
|
"SCCS", "RCS", and "CVS", which are names of directories for which it is
|
|
generally not desirable to descend while processing the \fB\-\-recurse\fP
|
|
option.
|
|
|
|
.TP 5
|
|
\fB\-\-excmd\fP=\fItype\fP
|
|
Determines the type of EX command used to locate tags in the source file.
|
|
[Ignored in etags mode]
|
|
|
|
The valid values for \fItype\fP (either the entire word or the first letter is
|
|
accepted) are:
|
|
|
|
.RS 5
|
|
.TP 9
|
|
.I number
|
|
Use only line numbers in the tag file for locating tags. This has four
|
|
advantages:
|
|
.PD 0
|
|
.RS 9
|
|
.TP 4
|
|
1.
|
|
Significantly reduces the size of the resulting tag file.
|
|
.TP 4
|
|
2.
|
|
Eliminates failures to find tags because the line defining the tag has
|
|
changed, causing the pattern match to fail (note that some editors, such as
|
|
\fBvim\fP, are able to recover in many such instances).
|
|
.TP 4
|
|
3.
|
|
Eliminates finding identical matching, but incorrect, source lines (see
|
|
\fBBUGS\fP, below).
|
|
.TP 4
|
|
4.
|
|
Retains separate entries in the tag file for lines which are identical in
|
|
content. In \fIpattern\fP mode, duplicate entries are dropped because the
|
|
search patterns they generate are identical, making the duplicate entries
|
|
useless.
|
|
.RE
|
|
.PD 1
|
|
|
|
.IP
|
|
However, this option has one significant drawback: changes to the source files
|
|
can cause the line numbers recorded in the tag file to no longer correspond
|
|
to the lines in the source file, causing jumps to some tags to miss the target
|
|
definition by one or more lines. Basically, this option is best used when the
|
|
source code to which it is applied is not subject to change. Selecting this
|
|
option type causes the following options to be ignored: \fB\-BF\fP.
|
|
|
|
.TP 9
|
|
.I pattern
|
|
Use only search patterns for all tags, rather than the line numbers usually
|
|
used for macro definitions. This has the advantage of not referencing obsolete
|
|
line numbers when lines have been added or removed since the tag file was
|
|
generated.
|
|
|
|
.TP 9
|
|
.I mixed
|
|
In this mode, patterns are generally used with a few exceptions. For C, line
|
|
numbers are used for macro definition tags. This was the default format
|
|
generated by the original \fBctags\fP and is, therefore, retained as the
|
|
default for this option. For Fortran, line numbers are used for common blocks
|
|
because their corresponding source lines are generally identical, making
|
|
pattern searches useless for finding all matches.
|
|
.RE
|
|
|
|
.TP 5
|
|
\fB\-\-extra\fP=\fI[+|\-]flags\fP
|
|
Specifies whether to include extra tag entries for certain kinds of
|
|
information. The parameter \fIflags\fP is a set of one-letter flags, each
|
|
representing one kind of extra tag entry to include in the tag file. If
|
|
\fIflags\fP is preceded by either the '+' or '\-' character, the effect of
|
|
each flag is added to, or removed from, those currently enabled; otherwise the
|
|
flags replace any current settings. The meaning of each flag is as follows:
|
|
|
|
.PP
|
|
.RS 8
|
|
.TP 4
|
|
.I f
|
|
Include an entry for the base file name of every source file (e.g.
|
|
"example.c"), which addresses the first line of the file.
|
|
.TP 4
|
|
.I q
|
|
Include an extra class-qualified tag entry for each tag which is a member
|
|
of a class (for languages for which this information is extracted; currently
|
|
C++, Eiffel, and Java). The actual form of the qualified tag depends upon the
|
|
language from which the tag was derived (using a form that is most natural for
|
|
how qualified calls are specified in the language). For C++, it is in the form
|
|
"class::member"; for Eiffel and Java, it is in the form "class.member". This
|
|
may allow easier location of a specific tags when multiple occurrences of a
|
|
tag name occur in the tag file. Note, however, that this could potentially
|
|
more than double the size of the tag file.
|
|
.RE
|
|
|
|
.TP 5
|
|
\fB\-\-fields\fP=\fI[+|\-]flags\fP
|
|
Specifies the available extension fields which are to be included in the
|
|
entries of the tag file (see \fBTAG FILE FORMAT\fP, below, for more
|
|
information). The parameter \fIflags\fP is a set of one-letter flags, each
|
|
representing one type of extension field to include, with the following
|
|
meanings (disabled by default unless indicated):
|
|
|
|
.PP
|
|
.PD 0
|
|
.RS 8
|
|
.TP 4
|
|
.I a
|
|
Access (or export) of class members
|
|
.TP 4
|
|
.I f
|
|
File-restricted scoping [enabled]
|
|
.TP 4
|
|
.I i
|
|
Inheritance information
|
|
.TP 4
|
|
.I k
|
|
Kind of tag as a single letter [enabled]
|
|
.TP 4
|
|
.I K
|
|
Kind of tag as full name
|
|
.TP 4
|
|
.I l
|
|
Language of source file containing tag
|
|
.TP 4
|
|
.I m
|
|
Implementation information
|
|
.TP 4
|
|
.I n
|
|
Line number of tag definition
|
|
.TP 4
|
|
.I s
|
|
Scope of tag definition [enabled]
|
|
.TP 4
|
|
.I S
|
|
Signature of routine (e.g. prototype or parameter list)
|
|
.TP 4
|
|
.I z
|
|
Include the "kind:" key in kind field
|
|
.TP 4
|
|
.I t
|
|
Type and name of a variable or typedef as "typeref:" field [enabled]
|
|
.PD 1
|
|
.RE
|
|
|
|
.RS 5
|
|
Each letter or group of letters may be preceded by either '+' to add it to the
|
|
default set, or '\-' to exclude it. In the absence of any preceding '+' or '\-'
|
|
sign, only those kinds explicitly listed in \fIflags\fP will be included in
|
|
the output (i.e. overriding the default set). This option is ignored if the
|
|
option \fB\-\-format\fP=\fI1\fP has been specified. The default value
|
|
of this option is \fIfkst\fP.
|
|
.RE
|
|
|
|
.TP 5
|
|
\fB\-\-file\-scope\fP[=\fIyes\fP|\fIno\fP]
|
|
Indicates whether tags scoped only for a single file (i.e. tags which cannot
|
|
be seen outside of the file in which they are defined, such as "static" tags)
|
|
should be included in the output. See, also, the \fB\-h\fP option. This option
|
|
is enabled by default.
|
|
|
|
.TP 5
|
|
\fB\-\-filter\fP[=\fIyes\fP|\fIno\fP]
|
|
Causes \fBctags\fP to behave as a filter, reading source file names from
|
|
standard input and printing their tags to standard output on a file-by-file
|
|
basis. If \fB\-\-sorted\fP is enabled, tags are sorted only within the source
|
|
file in which they are defined. File names are read from standard input in
|
|
line-oriented input mode (see note for \fB\-L\fP option) and only after file
|
|
names listed on the command line or from any file supplied using the \fB\-L\fP
|
|
option. When this option is enabled, the options \fB\-f\fP, \fB\-o\fP,
|
|
and \fB\-\-totals\fP are ignored. This option is quite esoteric and is disabled
|
|
by default. This option must appear before the first file name.
|
|
|
|
.TP 5
|
|
\fB\-\-filter\-terminator\fP=\fIstring\fP
|
|
Specifies a string to print to standard output following the tags for each
|
|
file name parsed when the \fB\-\-filter\fP option is enabled. This may permit an
|
|
application reading the output of ctags to determine when the output for each
|
|
file is finished. Note that if the file name read is a directory and
|
|
\fB\-\-recurse\fP is enabled, this string will be printed only once at the
|
|
end of all tags found for by descending the directory. This string will always
|
|
be separated from the last tag line for the file by its terminating newline.
|
|
This option is quite esoteric and is empty by default. This option must appear
|
|
before the first file name.
|
|
|
|
.TP 5
|
|
\fB\-\-format\fP=\fIlevel\fP
|
|
Change the format of the output tag file. Currently the only valid values for
|
|
\fIlevel\fP are \fI1\fP or \fI2\fP. Level 1 specifies the original tag file
|
|
format and level 2 specifies a new extended format containing extension fields
|
|
(but in a manner which retains backward-compatibility with original
|
|
\fBvi\fP(1) implementations). The default level is 2. This option must appear
|
|
before the first file name. [Ignored in etags mode]
|
|
|
|
.TP 5
|
|
.B \-\-help
|
|
Prints to standard output a detailed usage description, and then exits.
|
|
|
|
.TP 5
|
|
\fB\-\-if0\fP[=\fIyes\fP|\fIno\fP]
|
|
Indicates a preference as to whether code within an "#if 0" branch of a
|
|
preprocessor conditional should be examined for non-macro tags (macro tags are
|
|
always included). Because the intent of this construct is to disable code, the
|
|
default value of this option is \fIno\fP. Note that this indicates a
|
|
preference only and does not guarantee skipping code within an "#if 0" branch,
|
|
since the fall-back algorithm used to generate tags when preprocessor
|
|
conditionals are too complex follows all branches of a conditional. This
|
|
option is disabled by default.
|
|
|
|
.TP 5
|
|
\fB\-\-<LANG>\-kinds\fP=\fI[+|\-]kinds\fP
|
|
Specifies a list of language-specific kinds of tags (or kinds) to include in
|
|
the output file for a particular language, where \fB<LANG>\fP is
|
|
case-insensitive and is one of the built-in language names (see the
|
|
\fB\-\-list\-languages\fP option for a complete list). The parameter \fIkinds\fP
|
|
is a group of one-letter flags designating kinds of tags (particular to the
|
|
language) to either include or exclude from the output. The specific sets of
|
|
flags recognized for each language, their meanings and defaults may be list
|
|
using the \fB\-\-list\-kinds\fP option. Each letter or group of letters may be
|
|
preceded by either '+' to add it to, or '\-' to remove it from, the default
|
|
set. In the absence of any preceding '+' or '\-' sign, only those kinds
|
|
explicitly listed in \fIkinds\fP will be included in the output (i.e.
|
|
overriding the default for the specified language).
|
|
|
|
As an example for the C language, in order to add prototypes and external
|
|
variable declarations to the default set of tag kinds, but exclude macros,
|
|
use \fB\-\-c\-kinds\fP=\fI+px\-d\fP; to include only tags for functions, use
|
|
\fB\-\-c\-kinds\fP=\fIf\fP.
|
|
|
|
.TP 5
|
|
\fB\-\-langdef\fP=\fIname\fP
|
|
Defines a new user-defined language, \fIname\fP, to be parsed with regular
|
|
expressions. Once defined, \fIname\fP may be used in other options taking
|
|
language names. The typical use of this option is to first define the
|
|
language, then map file names to it using \fI\-\-langmap\fP, then specify
|
|
regular expressions using \fI\-\-regex\-<LANG>\fP to define how its tags are
|
|
found.
|
|
|
|
.TP 5
|
|
\fB\-\-langmap\fP=\fImap[,map[...]]\fP
|
|
Controls how file names are mapped to languages (see the \fB\-\-list\-maps\fP
|
|
option). Each comma-separated \fImap\fP consists of the language name (either
|
|
a built-in or user-defined language), a colon, and a list of file extensions
|
|
and/or file name patterns. A file extension is specified by preceding the
|
|
extension with a period (e.g. ".c"). A file name pattern is specified by
|
|
enclosing the pattern in parentheses (e.g. "([Mm]akefile)"). If appropriate
|
|
support is available from the runtime library of your C compiler, then the
|
|
file name pattern may contain the usual shell wildcards common on Unix (be
|
|
sure to quote the option parameter to protect the wildcards from being
|
|
expanded by the shell before being passed to \fBctags\fP). You can determine
|
|
if shell wildcards are available on your platform by examining the output of
|
|
the \fB\-\-version\fP option, which will include "+wildcards" in the compiled
|
|
feature list; otherwise, the file name patterns are matched against file names
|
|
using a simple textual comparison. When mapping a file extension, it will
|
|
first be unmapped from any other languages.
|
|
|
|
If the first character in a map is a plus sign, then the extensions and file
|
|
name patterns in that map will be appended to the current map for that
|
|
language; otherwise, the map will replace the current map. For example, to
|
|
specify that only files with extensions of .c and .x are to be treated as C
|
|
language files, use "\fB\-\-langmap\fP=\fIc:.c.x\fP"; to also add files with
|
|
extensions of .j as Java language files, specify
|
|
"\fB\-\-langmap\fP=\fIc:.c.x,java:+.j\fP". To map makefiles (e.g. files
|
|
named either "Makefile", "makefile", or having the extension ".mak") to a
|
|
language called "make", specify "\fB\-\-langmap\fP=\fImake:([Mm]akefile).mak\fP".
|
|
To map files having no extension, specify a period not followed by a
|
|
non-period character (e.g. ".", "..x", ".x."). To clear the mapping for a
|
|
particular language (thus inhibiting automatic generation of tags for that
|
|
language), specify an empty extension list (e.g.
|
|
"\fB\-\-langmap\fP=\fIfortran:\fP"). To restore the default language mappings
|
|
for all a particular language, supply the keyword "default" for the mapping.
|
|
To specify restore the default language mappings for all languages, specify
|
|
"\fB\-\-langmap\fP=\fIdefault\fP". Note that file extensions are tested before
|
|
file name patterns when inferring the language of a file.
|
|
|
|
.TP 5
|
|
\fB\-\-language\-force\fP=\fIlanguage\fP
|
|
By default, \fBctags\fP automatically selects the language of a source file,
|
|
ignoring those files whose language cannot be determined (see
|
|
\fBSOURCE FILES\fP, above). This option forces the specified \fIlanguage\fP
|
|
(case-insensitive; either built-in or user-defined) to be used for every
|
|
supplied file instead of automatically selecting the language based upon its
|
|
extension. In addition, the special value \fIauto\fP indicates that the
|
|
language should be automatically selected (which effectively disables this
|
|
option).
|
|
|
|
.TP 5
|
|
\fB\-\-languages\fP=\fI[+|\-]list\fP
|
|
Specifies the languages for which tag generation is enabled, with \fIlist\fP
|
|
containing a comma-separated list of language names (case-insensitive; either
|
|
built-in or user-defined). If the first language of \fIlist\fP is not preceded
|
|
by either a '+' or '\-', the current list will be cleared before adding or
|
|
removing the languages in \fIlist\fP. Until a '\-' is encountered, each
|
|
language in the list will be added to the current list. As either the '+' or
|
|
\&'\-' is encountered in the list, the languages following it are added or
|
|
removed from the current list, respectively. Thus, it becomes simple to
|
|
replace the current list with a new one, or to add or remove languages from
|
|
the current list. The actual list of files for which tags will be generated
|
|
depends upon the language extension mapping in effect (see the \fB\-\-langmap\fP
|
|
option). Note that all languages, including user-defined languages are enabled
|
|
unless explicitly disabled using this option. Language names included in
|
|
\fIlist\fP may be any built-in language or one previously defined with
|
|
\fB\-\-langdef\fP. The default is "all", which is also accepted as a valid
|
|
argument. See the \fB\-\-list\-languages\fP option for a complete list of the
|
|
built-in language names.
|
|
|
|
.TP 5
|
|
\fB\-\-license\fP
|
|
Prints a summary of the software license to standard output, and then exits.
|
|
|
|
.TP 5
|
|
\fB\-\-line\-directives\fP[=\fIyes\fP|\fIno\fP]
|
|
Specifies whether "#line" directives should be recognized. These are present
|
|
in the output of preprocessors and contain the line number, and possibly the
|
|
file name, of the original source file(s) from which the preprocessor output
|
|
file was generated. When enabled, this option will cause \fBctags\fP to
|
|
generate tag entries marked with the file names and line numbers of their
|
|
locations original source file(s), instead of their actual locations in the
|
|
preprocessor output. The actual file names placed into the tag file will have
|
|
the same leading path components as the preprocessor output file, since it is
|
|
assumed that the original source files are located relative to the
|
|
preprocessor output file (unless, of course, the #line directive specifies an
|
|
absolute path). This option is off by default. \fBNote:\fP This option is
|
|
generally only useful when used together with the \fB\-\-excmd\fP=\fInumber\fP
|
|
(\fB\-n\fP) option. Also, you may have to use either the \fB\-\-langmap\fP or
|
|
\fB\-\-language\-force\fP option if the extension of the preprocessor output file
|
|
is not known to \fBctags\fP.
|
|
|
|
.TP 5
|
|
\fB\-\-links\fP[=\fIyes\fP|\fIno\fP]
|
|
Indicates whether symbolic links (if supported) should be followed. When
|
|
disabled, symbolic links are ignored. This option is on by default.
|
|
|
|
.TP 5
|
|
\fB\-\-list\-kinds\fP[=\fIlanguage\fP|\fIall\fP]
|
|
Lists the tag kinds recognized for either the specified language or all
|
|
languages, and then exits. Each kind of tag recorded in the tag file is
|
|
represented by a one-letter flag, which is also used to filter the tags placed
|
|
into the output through use of the \fB\-\-<LANG>\-kinds\fP option. Note that some
|
|
languages and/or tag kinds may be implemented using regular expressions and
|
|
may not be available if regex support is not compiled into \fBctags\fP (see
|
|
the \fB\-\-regex\-<LANG>\fP option). Each kind listed is enabled unless followed
|
|
by "[off]".
|
|
|
|
.TP 5
|
|
\fB\-\-list\-maps\fP[=\fIlanguage\fP|\fIall\fP]
|
|
Lists the file extensions and file name patterns which associate a file name
|
|
with a language for either the specified language or all languages, and then
|
|
exits. See the \fB\-\-langmap\fP option, and \fBSOURCE FILES\fP, above.
|
|
|
|
.TP 5
|
|
\fB\-\-list\-languages\fP
|
|
Lists the names of the languages understood by \fBctags\fP, and then exits.
|
|
These language names are case insensitive and may be used in the
|
|
\fB\-\-language\-force\fP, \fB\-\-languages\fP, \fB\-\-<LANG>\-kinds\fP, and
|
|
\fB\-\-regex\-<LANG>\fP options.
|
|
|
|
.TP 5
|
|
\fB\-\-options\fP=\fIfile\fP
|
|
Read additional options from \fIfile\fP. The file should contain one option
|
|
per line. As a special case, if
|
|
\fB\-\-options\fP=\fINONE\fP is specified as the first option on the command
|
|
line, it will disable the automatic reading of any configuration options from
|
|
either a file or the environment (see \fBFILES\fP).
|
|
|
|
.TP 5
|
|
\fB\-\-recurse\fP[=\fIyes\fP|\fIno\fP]
|
|
Recurse into directories encountered in the list of supplied files. If the
|
|
list of supplied files is empty and no file list is specified with the
|
|
\fB\-L\fP option, then the current directory (i.e. ".") is assumed. Symbolic
|
|
links are followed. If you don't like these behaviors, either explicitly
|
|
specify the files or pipe the output of \fBfind\fP(1) into \fBctags \-L\-\fP
|
|
instead. \fBNote:\fP This option is not supported on all platforms at present.
|
|
It is available if the output of the \fB\-\-help\fP option includes this option.
|
|
See, also, the \fB\-\-exclude\fP to limit recursion.
|
|
|
|
.TP 5
|
|
\fB\-\-regex\-<LANG>\fP=\fI/regexp/replacement/[kind\-spec/][flags]\fP
|
|
The \fI/regexp/replacement/\fP pair define a regular expression replacement
|
|
pattern, similar in style to \fBsed\fP substitution commands, with which to
|
|
generate tags from source files mapped to the named language, \fB<LANG>\fP,
|
|
(case-insensitive; either a built-in or user-defined language). The regular
|
|
expression, \fIregexp\fP, defines an extended regular expression (roughly that
|
|
used by \fBegrep\fP(1)), which is used to locate a single source line
|
|
containing a tag and may specify tab characters using \\t. When a matching
|
|
line is found, a tag will be generated for the name defined by
|
|
\fIreplacement\fP, which generally will contain the special back-references
|
|
\\1 through \\9 to refer to matching sub-expression groups within
|
|
\fIregexp\fP. The '/' separator characters shown in the parameter to the
|
|
option can actually be replaced by any character. Note that whichever
|
|
separator character is used will have to be escaped with a backslash ('\\')
|
|
character wherever it is used in the parameter as something other than a
|
|
separator. The regular expression defined by this option is added to the
|
|
current list of regular expressions for the specified language unless the
|
|
parameter is omitted, in which case the current list is cleared.
|
|
|
|
Unless modified by \fIflags\fP, \fIregexp\fP is interpreted as a Posix
|
|
extended regular expression. The \fIreplacement\fP should expand for all
|
|
matching lines to a non-empty string of characters, or a warning message will
|
|
be reported. An optional kind specifier for tags matching \fIregexp\fP may
|
|
follow \fIreplacement\fP, which will determine what kind of tag is reported in
|
|
the "kind" extension field (see \fBTAG FILE FORMAT\fP, below). The full form
|
|
of \fIkind\-spec\fP is in the form of a single letter, a comma, a name (without
|
|
spaces), a comma, a description, followed by a separator, which specify
|
|
the short and long forms of the kind value and its textual description
|
|
(displayed using \fB\-\-list\-kinds\fP). Either the kind name and/or the
|
|
description may be omitted. If \fIkind\-spec\fP is omitted, it defaults to
|
|
"\fIr,regex\fP". Finally, \fIflags\fP are one or more single-letter characters
|
|
having the following effect upon the interpretation of \fIregexp\fP:
|
|
|
|
.PP
|
|
.RS 8
|
|
.TP 4
|
|
.I b
|
|
The pattern is interpreted as a Posix basic regular expression.
|
|
.TP 4
|
|
.I e
|
|
The pattern is interpreted as a Posix extended regular expression (default).
|
|
.TP 4
|
|
.I i
|
|
The regular expression is to be applied in a case-insensitive manner.
|
|
.RE
|
|
|
|
.RS 5
|
|
Note that this option is available only if \fBctags\fP was compiled with
|
|
support for regular expressions, which depends upon your platform. You can
|
|
determine if support for regular expressions is compiled in by examining the
|
|
output of the \fB\-\-version\fP option, which will include "+regex" in the
|
|
compiled feature list.
|
|
|
|
For more information on the regular expressions used by \fBctags\fP, see
|
|
either the \fBregex(5,7)\fP man page, or the GNU info documentation for regex
|
|
(e.g. "info regex").
|
|
.RE
|
|
|
|
.TP 5
|
|
\fB\-\-sort\fP[=\fIyes\fP|\fIno\fP|\fIfoldcase\fP]
|
|
Indicates whether the tag file should be sorted on the tag name (default is
|
|
\fIyes\fP). Note that the original \fBvi\fP(1) required sorted tags.
|
|
The \fIfoldcase\fP value specifies case insensitive (or case-folded) sorting.
|
|
Fast binary searches of tag files sorted with case-folding will require
|
|
special support from tools using tag files, such as that found in the ctags
|
|
readtags library, or Vim version 6.2 or higher (using "set ignorecase"). This
|
|
option must appear before the first file name. [Ignored in etags mode]
|
|
|
|
.TP 5
|
|
\fB\-\-tag\-relative\fP[=\fIyes\fP|\fIno\fP]
|
|
Indicates that the file paths recorded in the tag file should be relative to
|
|
the directory containing the tag file, rather than relative to the current
|
|
directory, unless the files supplied on the command line are specified with
|
|
absolute paths. This option must appear before the first file name. The
|
|
default is \fIyes\fP when running in etags mode (see the \fB\-e\fP
|
|
option), \fIno\fP otherwise.
|
|
|
|
.TP 5
|
|
\fB\-\-totals\fP[=\fIyes\fP|\fIno\fP]
|
|
Prints statistics about the source files read and the tag file written during
|
|
the current invocation of \fBctags\fP. This option is off by default.
|
|
This option must appear before the first file name.
|
|
|
|
.TP 5
|
|
\fB\-\-verbose\fP[=\fIyes\fP|\fIno\fP]
|
|
Enable verbose mode. This prints out information on option processing and a
|
|
brief message describing what action is being taken for each file considered
|
|
by \fBctags\fP. Normally, \fBctags\fP does not read command line arguments
|
|
until after options are read from the configuration files (see \fBFILES\fP,
|
|
below) and the \fBCTAGS\fP environment variable. However, if this option is
|
|
the first argument on the command line, it will take effect before any options
|
|
are read from these sources. The default is \fIno\fP.
|
|
|
|
.TP 5
|
|
\fB\-\-version\fP
|
|
Prints a version identifier for \fBctags\fP to standard output, and then
|
|
exits. This is guaranteed to always contain the string "Exuberant Ctags".
|
|
|
|
|
|
.SH "OPERATIONAL DETAILS"
|
|
|
|
As \fBctags\fP considers each file name in turn, it tries to determine the
|
|
language of the file by applying the following three tests in order: if the
|
|
file extension has been mapped to a language, if the file name matches a shell
|
|
pattern mapped to a language, and finally if the file is executable and its
|
|
first line specifies an interpreter using the Unix-style "#!" specification
|
|
(if supported on the platform). If a language was identified, the file is
|
|
opened and then the appropriate language parser is called to operate on the
|
|
currently open file. The parser parses through the file and adds an entry to
|
|
the tag file for each language object it is written to handle. See
|
|
\fBTAG FILE FORMAT\fP, below, for details on these entries.
|
|
|
|
This implementation of \fBctags\fP imposes no formatting requirements on C
|
|
code as do legacy implementations. Older implementations of ctags tended to
|
|
rely upon certain formatting assumptions in order to help it resolve coding
|
|
dilemmas caused by preprocessor conditionals.
|
|
|
|
In general, \fBctags\fP tries to be smart about conditional preprocessor
|
|
directives. If a preprocessor conditional is encountered within a statement
|
|
which defines a tag, \fBctags\fP follows only the first branch of that
|
|
conditional (except in the special case of "#if 0", in which case it follows
|
|
only the last branch). The reason for this is that failing to pursue only one
|
|
branch can result in ambiguous syntax, as in the following example:
|
|
|
|
.RS
|
|
#ifdef TWO_ALTERNATIVES
|
|
.br
|
|
struct {
|
|
.br
|
|
#else
|
|
.br
|
|
union {
|
|
.br
|
|
#endif
|
|
.RS 4
|
|
short a;
|
|
.br
|
|
long b;
|
|
.RE
|
|
}
|
|
.RE
|
|
|
|
Both branches cannot be followed, or braces become unbalanced and \fBctags\fP
|
|
would be unable to make sense of the syntax.
|
|
|
|
If the application of this heuristic fails to properly parse a file,
|
|
generally due to complicated and inconsistent pairing within the conditionals,
|
|
\fBctags\fP will retry the file using a different heuristic which does not
|
|
selectively follow conditional preprocessor branches, but instead falls back
|
|
to relying upon a closing brace ("}") in column 1 as indicating the end of a
|
|
block once any brace imbalance results from following a #if conditional branch.
|
|
|
|
\fBCtags\fP will also try to specially handle arguments lists enclosed in
|
|
double sets of parentheses in order to accept the following conditional
|
|
construct:
|
|
|
|
.RS
|
|
extern void foo __ARGS((int one, char two));
|
|
.RE
|
|
|
|
Any name immediately preceding the "((" will be automatically ignored and
|
|
the previous name will be used.
|
|
|
|
C++ operator definitions are specially handled. In order for consistency with
|
|
all types of operators (overloaded and conversion), the operator name in the
|
|
tag file will always be preceded by the string "operator " (i.e. even if the
|
|
actual operator definition was written as "operator<<").
|
|
|
|
After creating or appending to the tag file, it is sorted by the tag name,
|
|
removing identical tag lines.
|
|
|
|
|
|
.SH "TAG FILE FORMAT"
|
|
|
|
When not running in etags mode, each entry in the tag file consists of a
|
|
separate line, each looking like this in the most general case:
|
|
|
|
.RS 1
|
|
tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields
|
|
.RE
|
|
|
|
The fields and separators of these lines are specified as follows:
|
|
|
|
.PD 0
|
|
.RS 4
|
|
.TP 4
|
|
1.
|
|
tag name
|
|
.TP 4
|
|
2.
|
|
single tab character
|
|
.TP 4
|
|
3.
|
|
name of the file in which the object associated with the tag is located
|
|
.TP 4
|
|
4.
|
|
single tab character
|
|
.TP 4
|
|
5.
|
|
EX command used to locate the tag within the file; generally a search pattern
|
|
(either /pattern/ or ?pattern?) or line number (see \fB\-\-excmd\fP). Tag file
|
|
format 2 (see \fB\-\-format\fP) extends this EX command under certain
|
|
circumstances to include a set of extension fields (described below) embedded
|
|
in an EX comment immediately appended to the EX command, which leaves it
|
|
backward-compatible with original \fBvi\fP(1) implementations.
|
|
.RE
|
|
.PD 1
|
|
|
|
A few special tags are written into the tag file for internal purposes. These
|
|
tags are composed in such a way that they always sort to the top of the file.
|
|
Therefore, the first two characters of these tags are used a magic number to
|
|
detect a tag file for purposes of determining whether a valid tag file is
|
|
being overwritten rather than a source file.
|
|
|
|
Note that the name of each source file will be recorded in the tag file
|
|
exactly as it appears on the command line. Therefore, if the path you
|
|
specified on the command line was relative to the current directory, then it
|
|
will be recorded in that same manner in the tag file. See, however, the
|
|
\fB\-\-tag\-relative\fP option for how this behavior can be modified.
|
|
|
|
Extension fields are tab-separated key-value pairs appended to the end of the
|
|
EX command as a comment, as described above. These key value pairs appear in
|
|
the general form "\fIkey\fP:\fIvalue\fP". Their presence in the lines of the
|
|
tag file are controlled by the \fB\-\-fields\fP option. The possible keys and
|
|
the meaning of their values are as follows:
|
|
|
|
.TP 12
|
|
.I access
|
|
Indicates the visibility of this class member, where \fIvalue\fP is specific
|
|
to the language.
|
|
|
|
.TP 12
|
|
.I file
|
|
Indicates that the tag has file-limited visibility. This key has no
|
|
corresponding value.
|
|
|
|
.TP 12
|
|
.I kind
|
|
Indicates the type, or kind, of tag. Its value is either one of the
|
|
corresponding one-letter flags described under the various
|
|
\fB\-\-<LANG>\-kinds\fP options above, or a full name. It is permitted (and is,
|
|
in fact, the default) for the key portion of this field to be omitted. The
|
|
optional behaviors are controlled with the \fB\-\-fields\fP option.
|
|
|
|
.TP 12
|
|
.I implementation
|
|
When present, this indicates a limited implementation (abstract vs. concrete)
|
|
of a routine or class, where \fIvalue\fP is specific to the language
|
|
("virtual" or "pure virtual" for C++; "abstract" for Java).
|
|
|
|
.TP 12
|
|
.I inherits
|
|
When present, \fIvalue\fP. is a comma-separated list of classes from which
|
|
this class is derived (i.e. inherits from).
|
|
|
|
.TP 12
|
|
.I signature
|
|
When present, \fIvalue\fP is a language-dependent representation of the
|
|
signature of a routine. A routine signature in its complete form specifies the
|
|
return type of a routine and its formal argument list. This extension field is
|
|
presently supported only for C-based languages and does not include the return
|
|
type.
|
|
|
|
.PP
|
|
In addition, information on the scope of the tag definition may be available,
|
|
with the key portion equal to some language-dependent construct name and its
|
|
value the name declared for that construct in the program. This scope entry
|
|
indicates the scope in which the tag was found. For example, a tag generated
|
|
for a C structure member would have a scope looking like "struct:myStruct".
|
|
|
|
|
|
.SH "HOW TO USE WITH VI"
|
|
Vi will, by default, expect a tag file by the name "tags" in the current
|
|
directory. Once the tag file is built, the following commands exercise the tag
|
|
indexing feature:
|
|
.TP 12
|
|
.B vi \-t tag
|
|
Start vi and position the cursor at the file and line where "tag" is defined.
|
|
.TP 12
|
|
.B :ta tag
|
|
Find a tag.
|
|
.TP 12
|
|
.B Ctrl-]
|
|
Find the tag under the cursor.
|
|
.TP 12
|
|
.B Ctrl-T
|
|
Return to previous location before jump to tag (not widely implemented).
|
|
|
|
|
|
.SH "HOW TO USE WITH GNU EMACS"
|
|
Emacs will, by default, expect a tag file by the name "TAGS" in the current
|
|
directory. Once the tag file is built, the following commands exercise the
|
|
tag indexing feature:
|
|
.TP 10
|
|
.B "M-x visit\-tags\-table <RET> FILE <RET>"
|
|
Select the tag file, "FILE", to use.
|
|
.TP 10
|
|
.B "M-. [TAG] <RET>"
|
|
Find the first definition of TAG. The default tag is the identifier under the
|
|
cursor.
|
|
.TP 10
|
|
.B "M-*"
|
|
Pop back to where you previously invoked "M-.".
|
|
.TP 10
|
|
.B "C-u M-."
|
|
Find the next definition for the last tag.
|
|
|
|
.PP
|
|
For more commands, see the \fITags\fP topic in the Emacs info document.
|
|
|
|
|
|
.SH "HOW TO USE WITH NEDIT"
|
|
NEdit version 5.1 and later can handle the new extended tag file format (see
|
|
\fB\-\-format\fP). To make NEdit use the tag file, select "File\->Load Tags
|
|
File". To jump to the definition for a tag, highlight the word, then press
|
|
Ctrl-D. NEdit 5.1 can can read multiple tag files from different directories.
|
|
Setting the X resource nedit.tagFile to the name of a tag file instructs NEdit
|
|
to automatically load that tag file at startup time.
|
|
|
|
|
|
.SH "CAVEATS"
|
|
Because \fBctags\fP is neither a preprocessor nor a compiler, use of
|
|
preprocessor macros can fool \fBctags\fP into either missing tags or
|
|
improperly generating inappropriate tags. Although \fBctags\fP has been
|
|
designed to handle certain common cases, this is the single biggest cause of
|
|
reported problems. In particular, the use of preprocessor constructs which
|
|
alter the textual syntax of C can fool \fBctags\fP. You can work around many
|
|
such problems by using the \fB\-I\fP option.
|
|
|
|
Note that since \fBctags\fP generates patterns for locating tags (see
|
|
the \fB\-\-excmd\fP option), it is entirely possible that the wrong line may be
|
|
found by your editor if there exists another source line which is identical to
|
|
the line containing the tag. The following example demonstrates this condition:
|
|
|
|
.RS
|
|
int variable;
|
|
|
|
/* ... */
|
|
.br
|
|
void foo(variable)
|
|
.br
|
|
int variable;
|
|
.br
|
|
{
|
|
.RS 4
|
|
/* ... */
|
|
.RE
|
|
}
|
|
.RE
|
|
|
|
Depending upon which editor you use and where in the code you happen to be, it
|
|
is possible that the search pattern may locate the local parameter declaration
|
|
in foo() before it finds the actual global variable definition, since the
|
|
lines (and therefore their search patterns are identical). This can be avoided
|
|
by use of the \fB\-\-excmd\fP=\fIn\fP option.
|
|
|
|
|
|
.SH "BUGS"
|
|
\fBCtags\fP has more options than \fBls\fP(1).
|
|
|
|
When parsing a C++ member function definition (e.g. "className::function"),
|
|
\fBctags\fP cannot determine whether the scope specifier is a class name or a
|
|
namespace specifier and always lists it as a class name in the scope portion
|
|
of the extension fields. Also, if a C++ function is defined outside of the
|
|
class declaration (the usual case), the access specification (i.e. public,
|
|
protected, or private) and implementation information (e.g. virtual, pure
|
|
virtual) contained in the function declaration are not known when the tag is
|
|
generated for the function definition. It will, however be available for
|
|
prototypes (e.g \fB\-\-c++\-kinds\fP=\fI+p\fP).
|
|
|
|
No qualified tags are generated for language objects inherited into a class.
|
|
|
|
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
|
|
.TP 8
|
|
.B CTAGS
|
|
If this environment variable exists, it will be expected to contain a set of
|
|
default options which are read when \fBctags\fP starts, after the
|
|
configuration files listed in \fBFILES\fP, below, are read, but before any
|
|
command line options are read. Options appearing on the command line will
|
|
override options specified in this variable. Only options will be read from
|
|
this variable. Note that all white space in this variable is considered a
|
|
separator, making it impossible to pass an option parameter containing an
|
|
embedded space. If this is a problem, use a configuration file instead.
|
|
|
|
.TP 8
|
|
.B ETAGS
|
|
Similar to the \fBCTAGS\fP variable above, this variable, if found, will be
|
|
read when \fBetags\fP starts. If this variable is not found, \fBetags\fP will
|
|
try to use \fBCTAGS\fP instead.
|
|
|
|
.TP 8
|
|
.B TMPDIR
|
|
On Unix-like hosts where mkstemp() is available, the value of this variable
|
|
specifies the directory in which to place temporary files. This can be useful
|
|
if the size of a temporary file becomes too large to fit on the partition
|
|
holding the default temporary directory defined at compilation time.
|
|
\fBctags\fP creates temporary files only if either (1) an emacs-style tag file
|
|
is being generated, (2) the tag file is being sent to standard output, or (3)
|
|
the program was compiled to use an internal sort algorithm to sort the tag
|
|
files instead of the the sort utility of the operating system. If the sort
|
|
utility of the operating system is being used, it will generally observe this
|
|
variable also. Note that if \fBctags\fP is setuid, the value of TMPDIR will be
|
|
ignored.
|
|
|
|
|
|
.SH "FILES"
|
|
.PD 0
|
|
.I /ctags.cnf (on MSDOS, MSWindows only)
|
|
.br
|
|
.I /etc/ctags.conf
|
|
.br
|
|
.I /usr/local/etc/ctags.conf
|
|
.br
|
|
.I $HOME/.ctags
|
|
.br
|
|
.I $HOME/ctags.cnf (on MSDOS, MSWindows only)
|
|
.br
|
|
.I .ctags
|
|
.br
|
|
.I ctags.cnf (on MSDOS, MSWindows only)
|
|
.IP
|
|
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 \fBctags\fP
|
|
starts, but before the \fBCTAGS\fP 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 \fBctags\fP to read an
|
|
additional configuration file before any of those shown above, which will be
|
|
indicated if the output produced by the \fB\-\-version\fP option lists the
|
|
"custom-conf" feature. Options appearing in the \fBCTAGS\fP 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.
|
|
.PD 1
|
|
|
|
.TP
|
|
.I tags
|
|
The default tag file created by \fBctags\fP.
|
|
.TP
|
|
.I TAGS
|
|
The default tag file created by \fBetags\fP.
|
|
|
|
.SH "SEE ALSO"
|
|
The official Exuberant Ctags web site at:
|
|
|
|
.RS
|
|
http://ctags.sourceforge.net
|
|
.RE
|
|
|
|
Also \fBex\fP(1), \fBvi\fP(1), \fBelvis\fP, or, better yet, \fBvim\fP, the
|
|
official editor of \fBctags\fP. For more information on \fBvim\fP, see the VIM
|
|
Pages web site at:
|
|
|
|
.RS
|
|
http://www.vim.org/
|
|
.RE
|
|
|
|
|
|
.SH "AUTHOR"
|
|
Darren Hiebert <dhiebert at users.sourceforge.net>
|
|
.br
|
|
http://DarrenHiebert.com/
|
|
|
|
|
|
.SH "MOTIVATION"
|
|
"Think ye at all times of rendering some service to every member of the human
|
|
race."
|
|
|
|
"All effort and exertion put forth by man from the fullness of his heart is
|
|
worship, if it is prompted by the highest motives and the will to do service
|
|
to humanity."
|
|
|
|
.RS
|
|
\-\- From the Baha'i Writings
|
|
.RE
|
|
|
|
|
|
.SH "CREDITS"
|
|
This version of \fBctags\fP was originally derived from and inspired by the
|
|
ctags program by Steve Kirkendall <kirkenda@cs.pdx.edu> that comes with the
|
|
Elvis vi clone (though virtually none of the original code remains).
|
|
|
|
Credit is also due Bram Moolenaar <Bram@vim.org>, the author of \fBvim\fP, who
|
|
has devoted so much of his time and energy both to developing the editor as a
|
|
service to others, and to helping the orphans of Uganda.
|
|
|
|
The section entitled "HOW TO USE WITH GNU EMACS" was shamelessly stolen from
|
|
the info page for GNU \fBetags\fP.
|