"Fossies" - the Fresh Open Source Software Archive

Member "global-6.6.5/doc/gtags.ref" (3 Sep 2020, 10604 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 "gtags.ref": 6.6.4_vs_6.6.5.

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