"Fossies" - the Fresh Open Source Software Archive

Member "global-6.6.5/gtags/manual.in" (3 Sep 2020, 11466 Bytes) of package /linux/misc/global-6.6.5.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "manual.in": 6.6.4_vs_6.6.5.

    1 #
    2 # Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2005
    3 #	2007, 2008, 2009, 2010, 2012, 2014, 2015, 2016, 2018
    4 #	Tama Communications Corporation
    5 #
    6 # This file is part of GNU GLOBAL.
    7 #
    8 # This program is free software: you can redistribute it and/or modify
    9 # it under the terms of the GNU General Public License as published by
   10 # the Free Software Foundation, either version 3 of the License, or
   11 # (at your option) any later version.
   12 # 
   13 # This program is distributed in the hope that it will be useful,
   14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
   16 # GNU General Public License for more details.
   17 # 
   18 # You should have received a copy of the GNU General Public License
   19 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
   20 #
   21 # This file is converted to the following files:
   22 #	o command source file (for usage and help).
   23 #	o man format reference manual.
   24 #	o texinfo format reference manual.
   25 #
   26 @HEADER	GTAGS,1,June 2018,GNU Project
   27 @NAME	gtags - create tag files for global
   29 	@name{gtags} [-ciIOqvw][-C @arg{dir}][-d @arg{tag-file}][-f @arg{file}][@arg{dbpath}]
   31 	@name{Gtags} is used to create tag files for @xref{global,1}.
   33 	@name{Gtags} recursively collects source files under the current directory,
   34 	picks up symbols and writes the cross-reference data into the tag files
   35 	(@file{GTAGS}, @file{GRTAGS} and @file{GPATH}).
   37 	By default, @name{gtags} picks up
   39 	Other files are assumed to be text files. Gtags does not treat binary files.
   41 	If @file{gtags.files} exists in the current directory
   42 	or a file is specified by the @option{-f} option,
   43 	target files are limited by it. Lines starting with @samp{. } are comments.
   44 @OPTIONS
   45 	The following options are available:
   47 	@begin_itemize
   48 	@item{@option{--accept-dotfiles}}
   49 		Accept files and directories whose names begin with a dot.
   50 		By default, @name{gtags} ignores them.
   51 	@item{@option{-c}, @option{--compact}}
   52 		Make @file{GTAGS} in compact format.
   53 		This option does not influence @file{GRTAGS},
   54 		because that is always made in compact format.
   55 	@item{@option{-C}, @option{--directory} @arg{dir}}
   56 		Change the directory before doing all the work including parameter analysis.
   57 		This option is ignored in @var{GTAGS_OPTIONS}.
   58 		Please specify it on the command line directly.
   59 	@item{@option{--config}[=@arg{name}]}
   60 		Print the value of config variable @arg{name}.
   61 		If @arg{name} is not specified then print all names and values.
   62 		In addition to the variables listed in the ENVIRONMENT section,
   63 		you can refer to install directories by read only variables:
   64 		@var{bindir}, @var{libdir}, @var{datadir}, @var{localstatedir} and @var{sysconfdir}.
   65 	@item{@option{-d}, @option{--dump} @arg{tag-file}}
   66 		Dump a tag file as text to the standard output.
   67 		Output format is 'key<tab>data'. This is for debugging.
   68 	@item{@option{--explain}}
   69 		Explain handling files.
   70 	@item{@option{-f}, @option{--file} @arg{file}}
   71 		Give a list of candidates of target files.
   72 		Files which are not on the list are ignored.
   73 		The argument @arg{file} can be set to @val{-} to accept a list of
   74 		files from the standard input.
   75 		File names must be separated by newline.
   76 		To make the list you may use @xref{find,1}, which has rich options
   77 		for selecting files.
   78 	@item{@option{--gtagsconf} @arg{file}}
   79 		Set environment variable @var{GTAGSCONF} to @arg{file}.
   80 	@item{@option{--gtagslabel} @arg{label}}
   81 		Set environment variable @var{GTAGSLABEL} to @arg{label}.
   82 	@item{@option{--help}}
   83 		Print a usage message.
   84 	@item{@option{-I}, @option{--idutils}}
   85 		In addition to tag files, make ID database for @xref{idutils,1}.
   86 	@item{@option{-i}, @option{--incremental}}
   87 		Update tag files incrementally.
   88 		It's better to use @xref{global,1} with the @option{-u} command.
   89 	@item{@option{-O}, @option{--objdir}}
   90 		Use BSD-style obj directory as the location of tag files.
   91 		If @var{GTAGSOBJDIRPREFIX} is set and @file{$GTAGSOBJDIRPREFIX} directory exists,
   92 		@name{gtags} creates @file{$GTAGSOBJDIRPREFIX/<current directory>} directory
   93 		and makes tag files in it.
   94 		Though you can use @var{MAKEOBJDIRPREFIX} instead of @var{GTAGSOBJDIRPREFIX},
   95 		it is deprecated.
   96 		If @arg{dbpath} is specified, this option is ignored.
   97 	@item{@option{--single-update} @arg{file}}
   98 		Update tag files for a single file.
   99 		It is considered that @arg{file} was added, updated or deleted,
  100 		and there is no change in other files.
  101 		This option implies the @option{-i} option.
  102 	@item{@option{--skip-unreadable}}
  103 		Skip unreadable files.
  104 	@item{@option{--skip-symlink} [=@arg{type}]}
  105 		Skip symbolic links. If @arg{type} is 'f' then skip only symbolic links for
  106 		file, else if 'd' then skip only symbolic links for directory.
  107 		The default value of @arg{type} is 'a' (all symbolic links).
  108 	@item{@option{--sqlite3}}
  109 		Use Sqlite 3 API to make tag files. By default, BSD/DB 1.85 API is used.
  110 		To use this option, you need to invoke configure script with
  111 		@option{--with-sqlite3} in the build phase.
  112 	@item{@option{--statistics}}
  113 		Print statistics information.
  114 	@item{@option{-q}, @option{--quiet}}
  115 		Quiet mode.
  116 	@item{@option{-v}, @option{--verbose}}
  117 		Verbose mode.
  118 	@item{@option{--version}}
  119 		Show version number.
  120 	@item{@option{-w}, @option{--warning}}
  121 		Print warning messages.
  122 	@item{@arg{dbpath}}
  123 		The directory in which tag files are generated.
  124 		The default is the current directory.
  125 	@end_itemize
  127 	@begin_verbatim
  128 	$ ls -F
  129 	Makefile      src/    lib/
  130 	$ gtags -v
  131 	$ global -x main
  132 	main              10 src/main.c  main (argc, argv) {
  133 	@end_verbatim
  134 @FILES
  135 	@begin_itemize
  136 	@item{@file{GTAGS}}
  137 		Tag file for definitions.
  138 	@item{@file{GRTAGS}}
  139 		Tag file for references.
  140 	@item{@file{GPATH}}
  141 		Tag file for source files.
  142 	@item{@file{gtags.conf}, @file{$HOME/.globalrc}}
  143 		Configuration data for GNU GLOBAL.
  144 		See @xref{gtags.conf,5}.
  145 	@item{@file{gtags.files}}
  146 		The list of candidates of target files.
  147 	@item{@file{.notfunction}}
  148 		The list of symbols which is not a definition.
  149 		If this file exists in the project root directory, @name{gtags} does not
  150 		regard the symbols listed in this file as definitions.
  151 	@end_itemize
  153 	The following environment variables affect the execution of @name{gtags}:
  155 	@begin_itemize
  156 	@item{@var{GTAGSCACHE}}
  157 		The size of the B-tree cache. The default is 50000000 (bytes).
  158 	@item{@var{GTAGSCONF}}
  159 		Configuration file.
  160 	@item{@var{GTAGSFORCECPP}}
  161 		If this variable is set, each file whose suffix is @file{.h} is treated
  162 		as a C++ source file.
  163 	@item{@var{GTAGSFORCEENDBLOCK}}
  164 		If this variable is set, each @} at the first column brings end of block
  165 		of 0 level.
  166 	@item{@var{GTAGSLABEL}}
  167 		Configuration label. The default is @val{default}.
  168 	@item{@var{GTAGSLOGGING}}
  169 		If this variable is set, @file{$GTAGSLOGGING} is used as the path name
  170 		of a log file. There is no default value.
  171 	@item{@var{GTAGS_COMMANDLINE}}
  172 		This variable can only be referenced from the hook (see gtags_hook).
  173 		@name{Gtags} sets its own effective command line to this variable before
  174 		calling the hook. Each argument is separated by whitespace, and
  175 		real whitespace is represented as '%20'. This is read only.
  176 	@item{@var{GTAGS_OPTIONS}}
  177 		The value of this variable is inserted in the head of arguments.
  178 	@item{@var{GTAGSOBJDIR}}
  179 		If this variable is set, it is used as the name of BSD-style objdir.
  180 		The default is @file{obj}.
  181 		Though you can use @var{MAKEOBJDIR} instead of @var{GTAGSOBJDIR},
  182 		it is deprecated.
  183 	@item{@var{GTAGSOBJDIRPREFIX}}
  184 		If this variable is set, it is used as the prefix of BSD-style objdir.
  185 		The default is @file{/usr/obj}.
  186 		Though you can use @var{MAKEOBJDIRPREFIX} instead of @var{GTAGSOBJDIRPREFIX},
  187 		it is deprecated.
  188 	@item{@var{TMPDIR}}
  189 		The location used to stored temporary files. The default is @file{/tmp}.
  190 	@end_itemize
  192 	The following configuration variables affect the execution of @name{gtags}.
  193 	You can see the default value for each variable with the @option{--config} option.
  195 	@begin_itemize
  196 	@item{@code{gtags_parser} (comma separated list)}
  197 		Specify the mapping of language names and plug-in parsers.
  198 		Each part delimited by the comma consists of a language name, a colon,
  199 		the shared object path, an optional colon followed by a function name.
  200 		If the function name is not specified, 'parser' is assumed.
  201 		As a special exception, @name{gtags} collects values
  202 		from multiple @code{gtags_parser} variables.
  203 		For these mappings, the first match is adopted.
  204 	@item{@code{gtags_hook} (command line)}
  205 		Specify a command line which should be executed at the beginning of @name{gtags}
  206 		after loading configuration file. You can use this hook to update
  207 		@file{gtags.files} dynamically.
  208 		"./" in it always means the project root directory, since @name{gtags} is
  209 		always invoked there.
  210 		@br
  211 		This hook is ignored when the following options are specified:
  212 		--version, --help, --config, --dump.
  213 	@item{@code{icase_path} (boolean)}
  214 		Ignore case distinctions in the path.
  215 		Suffixes check is affected by this capability.
  216 	@item{@code{langmap} (comma separated list)}
  217 		Language mapping. Each comma-separated map consists of
  218 		a language name, a colon, and a list of file extensions.
  219 		You can specify a glob pattern surrounded by parentheses instead of an extension
  220 		for the files without extensions (e.g. Make:([Mm]akefile).mak.mk).
  221 		As a special exception, @name{gtags} collects values
  222 		from multiple @code{langmap} variables.
  223 		For these mappings, the first match is adopted.
  224 		Default mapping is:@br
  225 		@samp{@DEFAULTLANGMAP@}.
  226 	@item{@code{skip} (comma separated list)}
  227 		@name{Gtags} skips files and directories which are given in this list.
  228 		As a special exception, @name{gtags} collects values from multiple
  229 		@code{skip} variables.
  230 		If the value ends with @samp{/}, it is assumed as a directory and
  231 		@name{gtags} skips all files under it.
  232 		The value may include glob patterns (*, ?, [...], [!...], [^...]).
  233 		@br
  234 		If the value starts with @samp{/}, it is assumed a relative path name
  235 		from the root directory of the project. You cannot use glob patterns
  236 		for a path name. However, this direction is out-of-date, and is not
  237 		recommended. Instead, you can use @option{-f} option which can be combined with
  238 		@xref{find,1}. Since @xref{find,1} has rich options to select files,
  239 		you can do everything. Additionally, this technique can also be applied
  240 		to any other tagging systems like @xref{ctags,1}, @xref{cscope,1}, etc. 
  241 		@br
  242 		Skip list is also effective when you use the @option{-f} or @file{gtags.files}.
  243 	@end_itemize
  245 	@name{Gtags} exits with a non-0 value if an error occurred, 0 otherwise.
  247 	Note that files created by @name{gtags} with a non-zero exit code should be
  248 	considered corrupted.
  249 @SEE ALSO
  250 	@xref{global,1},
  251 	@xref{htags,1},
  252 	@xref{gtags.conf,5}.
  254         GNU GLOBAL source code tag system@br
  255         (http://www.gnu.org/software/global/).
  256 @BUG
  257 	@file{GTAGS} and @file{GRTAGS} are very large.
  258 	In advance of using this command, check the space of your disk.
  260 	Assembly language support is far from complete.
  261 	It extracts only @code{ENTRY()} and @code{ALTENTRY()} from source file.
  262 	Probably valid only for FreeBSD and Linux kernel source.
  264 	C++ support is deprecated.
  266 	There is no concurrency control about tag files.
  267 @AUTHOR
  268 	Shigio YAMAGUCHI, Hideki IWAMOTO and others.
  269 @HISTORY
  270 	The @name{gtags} command appeared in FreeBSD 2.2.2.