     [file version.texi not included]

This file documents the GNU GLOBAL source code tag system.

Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2006 Tama Communications Corporation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

GNU GLOBAL source code tag system
*********************************

This manual documents version VERSION of the GNU GLOBAL source code tag system.

Overview of the tools
*********************

What is this?
=============

GLOBAL is a source code tagging system (like ctags/etags) that is compatible with numerous application environments including vi, emacs, less, bash. You can locate specified object in source files and move there easily. It is useful for hacking a large project containing many subdirectories, many #ifdef and many main() functions.

Concept of project.
===================

GNU GLOBAL can treat a source tree containing subdirectories as a project. It is similar to CVS. You need not specify where the tag file is. Instead, global(1) will locate the tag file by itself. If tag file isn't found in the current directory, global(1) search parent directories for tag file.

User's position (current directory) is the first argument for GLOBAL's command.

Features.
=========

GNU GLOBAL has following features:

  * support C, C++, Yacc, Java, PHP4 and assembly.

  * work the same way across diverse environments. Currently, support followings:

       - Shell command line

       - Bash shell.

       - Vi editor clone (nvi, elvis, vim)

       - Less viewer

       - Emacs editor (emacs, mule, xemacs)

       - Glimmer editor

       - Web browser

       - Doxygen documentation system

  * find the locations of specified object quickly.

  * locate not only object definitions but also object references.

  * allows duplicate objects.

  * locate also path which includes specified pattern.

  * search not only in a source tree but also in library paths.

  * understand POSIX 1003.2 regular expressions.

  * support external search engine (grep and idutils).

  * generate hypertext of source code.

  * tag files are independent of machine architecture.

  * plugin parser is available to treat new language.

  * support incremental updating of tag files.

  * support customizing with gtags.conf.

  * generate completion list for completing input method.

Command line GLOBAL
*******************

You can use tag facilities from shell command line. It is a big merit of GLOBAL compared with any other tag system.

Preparation.
============

First of all, you must execute gtags(1)(see gtags) at the root of source tree. For example, if you want to browse vi's source code:

         $ cd /usr/src/usr.bin/vi
         $ gtags

Gtags traverse subdirectories and makes four databases at the root of the source tree.

         $ ls G*
         GPATH   GRTAGS  GSYMS   GTAGS

  * GTAGS database of object definitions

  * GRTAGS database of object references

  * GSYMS database of other symbols

  * GPATH database of path names

You should prepare for considerable disk space for tag files. For example, FreeBSD 7.0 kernel source code requires:

         source code(/usr/src/sys)       123MB

         GPATH                             1MB
         GTAGS                            24MB
         GRTAGS                           28MB
         GSYMS                            32MB
         -------------------------------------
         total of tag files               85MB

Basic usage.
============

Consider the following source tree:

         ROOT/           <- the root of source tree (GTAGS,GRTAGS,...)
         |
         |- DIR1/
         |  |
         |  |- fileA.c   .....   +---------------+
         |  |                    |main(){        |
         |  |                    |       func1();|
         |  |                    |       func2();|
         |  |                    |}              |
         |  |                    +---------------+
         |  |
         |  |- fileB.c   .....   +---------------+
         |                       |func1(){ ... } |
         |                       +---------------+
         |- DIR2/
            |
            |- fileC.c   .....   +---------------+
                                 |#ifdef X       |
                                 |func2(){ i++; }|
                                 |#else          |
                                 |func2(){ i--; }|
                                 |#endif         |
                                 |func3(){       |
                                 |       func1();|
                                 |}              |
                                 +---------------+

  * You can get the relative path of your object from anywhere in the source tree. You need not specify where the tag file is. Global will locate the tag file by itself.

              $ cd ROOT
              $ global func1
              DIR1/fileB.c            # func1() is defined in fileB.c
              $ cd DIR1
              $ global func1
              fileB.c                 # relative path from DIR1
              $ cd ../DIR2
              $ global func1
              ../DIR1/fileB.c         # relative path from DIR2

  * The -r option locates object references.

              $ global -r func2
              ../DIR1/fileA.c         # func2() is referred from fileA.c

  * You can use POSIX regular expressions.

              $ cd ROOT
              $ global 'func[1-3]'
              DIR1/fileB.c            # func1, func2 and func3 are matched
              DIR2/fileC.c

  * The -x option shows the details. It is similar to the -x option in ctags(1).

              $ global func2
              DIR2/fileC.c
              $ global -x func2
              func2              2 DIR2/fileC.c       func2(){ i++; }
              func2              4 DIR2/fileC.c       func2(){ i--; }

  * The -a option produces the absolute path name.

              $ global -a func1
              /home/user/ROOT/DIR1/fileB.c

  * The -s command locates any symbols which are not defined in GTAGS.

              $ global -xs X
              X                  1 DIR2/fileC.c #ifdef X

  * The -g command locates any patterns including symbols. It is similar to grep(1).

              $ global -xg '#ifdef'
              #ifdef             1 DIR2/fileC.c #ifdef X

  * The -P command enables you to locate path which includes specified string.

              $ global -P fileB
              DIR1/fileB.c
              $ global -P '1/'
              DIR1/fileA.c
              DIR1/fileB.c
              $ global -P '\.c$'
              DIR1/fileA.c
              DIR1/fileB.c
              DIR2/fileC.c

  * The -f command enables you see the list of objects of specified file.

              $ global -f DIR2/fileC.c
              func2              2 DIR2/fileC.c   func2(){ i++; }
              func2              4 DIR2/fileC.c   func2(){ i--; }
              func3              6 DIR2/fileC.c   func3(){

Applied usage.
==============

You can make multiple tag files. For example, you can execute gtags at ROOT/, version1.0/ and version2.0/.

         ROOT/                   <- the root of source tree      (GTAGS,...)
         |
         |- version1.0/          <- the root of version1.0       (GTAGS,...)
         |  |
         |  |- file.c    .....   +---------------+
         |                       |func1(){ i++; }|
         |                       +---------------+
         |
         |- version2.0/          <- the root of version2.0       (GTAGS,...)
            |
            |- file.c    .....   +---------------+
                                 |func1(){ i--; }|
                                 +---------------+

  * When you are in the version1.0 directory, global will only locate objects that are in version1.0.

              $ cd ROOT/version1.0
              $ global -x func1
              func1              1 file.c          func1(){ i++; }

  * When you are in the version2.0, global will only locate objects that are in version2.0.

              $ cd ROOT/version2.0
              $ global -x func1
              func1              1 file.c          func1(){ i--; }

  * If you are at ROOT/, or you set the GTAGSROOT environment variable to ROOT, then global will locate objects in both directories.

              $ cd ROOT
              $ global -x func1
              func1              1 version1.0/file.c  func1(){ i++; }
              func1              1 version2.0/file.c  func1(){ i--; }

There is another usage of GTAGSROOT.

  * If your source files are on a read-only device, such as CDROM, then you cannot make databases at the root of the source tree. In such cases, please do the following:

              $ mkdir /var/dbpath
              $ cd /cdrom/src                 # the root of source tree
              $ gtags /var/dbpath             # make tag file in /var/dbpath
              $ export GTAGSROOT=`pwd`
              $ export GTAGSDBPATH=/var/dbpath
              $ global func

  * If you want all references to an object that is not defined in the source tree to be treated as calls to library functions or system calls, then you can specify library directories with the GTAGSLIBPATH environment variable.

     You should execute gtags at each directory of the path. If GTAGS is not found in a directory, global ignores that directory.

              $ pwd
              /develop/src/mh                         # this is the source tree
              $ gtags
              $ ls G*TAGS
              GRTAGS  GTAGS
              $ global mhl
              uip/mhlsbr.c                            # mhl() is found
              $ global strlen                         # strlen() is not found
              $ (cd /usr/src/lib; gtags)              # library source
              $ (cd /usr/src/sys; gtags)              # kernel source
              $ export GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
              $ global strlen
              ../../../usr/src/lib/libc/string/strlen.c  # found in library
              $ global access
              ../../../usr/src/sys/kern/vfs_syscalls.c   # found in kernel

     Of course, the user program does not call kernel functions directly, but at least it is useful.

  * If you forget a object name, you can use the -c (complete) command.

              $ global -c kmem                # maybe k..k.. kmem..
              kmem_alloc
              kmem_alloc_pageable
              kmem_alloc_wait
              kmem_free
              kmem_free_wakeup
              kmem_init
              kmem_malloc
              kmem_suballoc                   # This is what I need!
              $ global kmem_suballoc
              ../vm/vm_kern.c

  * You can use the -c command with complete command in shell.

     In bash:

              $ funcs()
              > {
              >         local cur
              >         cur=${COMP_WORDS[COMP_CWORD]}
              >         COMPREPLY=(`global -c $cur`)
              > }
              $ complete -F funcs global
              $ global kmem_TABTAB
              kmem_alloc           kmem_alloc_wait      kmem_init
              kmem_alloc_nofault   kmem_free            kmem_malloc
              kmem_alloc_pageable  kmem_free_wakeup     kmem_suballoc
              $ global kmem_sTAB
              $ global kmem_suballoc
              ../vm/vm_kern.c

     In tcsh:

              % set funcs=(`global -c`)
              % complete global 'n/*/$funcs/'
              % global kmem_TAB
              kmem_alloc          kmem_free_wakeup
              kmem_alloc_pageable kmem_init
              kmem_alloc_wait     kmem_malloc
              kmem_free           kmem_suballoc
              % global kmem_sTAB
              % global kmem_suballoc
              ../vm/vm_kern.c

  * You can edit all files that include specified object by typing one command, for example:

              $ vi `global func1`     # edit fileB.c

  * If you want to browse many files in order, do the following:

              $ global -xr fork | awk '{printf "view +%s %s\n",$2,$3}'
              view +650 ../dev/aic7xxx/aic7xxx_asm.c
              view +250 ibcs2/ibcs2_misc.c
              view +401 linux/linux_misc.c
              view +310 ../kern/init_main.c
              view +318 ../kern/init_main.c
              view +336 ../kern/init_main.c
              view +351 ../kern/init_main.c
              $ !! | sh            # from now on, go to next tag with 'ZZ'.

Various applications
********************

Global facility for Bash
========================

Special support for bash is available.

Features.
---------

  * Vi-like tag stack is available.

  * Emacs-like tag name completion is available.

  * Editor or viewer is automatically invoked.

  * Tag mark facility is available.

  * Yor can manage directory list by cookie facility.

Preparation.
------------

First, do the preparation of global. See Preparation. And you can invoke bash(1) with ---rcfile option.

         $ bash --rcfile /usr/local/share/gtags/globash.rc

You will see a prompt like this:

         [/usr/src/sys]/kern _

This prompt means that the current directory is '/usr/src/sys/kern' and the root of the source tree is '/usr/src/sys'. Tag and marker are valid only in a project.

When you get out of the project, globash warns like:

         [/usr/src/sys] cd ..
         You are going to get out of current project.
         Tag stack and marker will be removed. Sure? ([y]/n)_

If you answer 'y' and RET or just RET in above example then tag stack and marker will be removed.

If you need help then please type 'ghelp'.

Basic usage.
------------

  * Almost global(1)(see global)'s command character is available as a command.

              [/usr/src/sys] x fork               <- (global -x fork)
              >    1  fork              94 kern/kern_fork.c fork(p, uap)
              [/usr/src/sys] r                    <- (global -xr fork)
              >    1  fork              85 alpha/linux/linux_machdep.c
                   2  fork             184 i386/linux/linux_machdep.c
              [/usr/src/sys] s lbolt              <- (global -xs lbolt)
              >    1  lbolt            1210 i386/isa/wd_cd.c     tsleep((cad
                   2  lbolt            1211 i386/isa/wd_cd.c     tsleep((cad
                   3  lbolt            709 i386/isa/wfd.c     tsleep ((caddr
              ...
              [/usr/src/sys] g                    <- (global -xg lbolt)
              >    1  lbolt            1210 i386/isa/wd_cd.c     tsleep((cad
              ...
              [/usr/src/sys] P init               <- (global -xP init)
              >    1  path    1 dev/hea/eni_init.c
                   2  path    1 dev/hfa/fore_init.c
                   3  path    1 i386/i386/initcpu.c
                   4  path    1 kern/init_main.c
                   5  path    1 kern/init_sysent.c
                   6  path    1 kern/vfs_init.c
                   7  path    1 vm/vm_init.c
              [/usr/src/sys] _

     If no tag name is specified then it is assumed the latest tag name.

  * You can select a tag by show command.

              [/usr/src/sys] x main
              >    1  main              70 alpha/alpha/gensetdefs.c main(in
                   2  main             1500 alpha/alpha/ieee_float.c main(i
                   3  main             227 boot/alpha/boot1/boot1.c main()
              ....
              [/usr/src/sys] show 3
              (Load editor and show boot/alpha/boot1/boot1.c at line 227.)

     The default editor is vi(1) but you can specify it statically by EDITOR environment variable or temporarily by option.

              [/usr/src/sys] show -e 3
              (Preloaded emacs show boot/alpha/boot1/boot1.c at line 227.)
              [/usr/src/sys] show -l 3
              (Load less and show boot/alpha/boot1/boot1.c at line 227.)
              [/usr/src/sys] show -g 3
              (Preloaded mozilla show boot/alpha/boot1/boot1.c at line 227.)

  * You can use vi-like tag stack. You can return previous tag list by pop or CTL-T command.

              [/usr/src/sys] x main
              >    1  main              70 alpha/alpha/gensetdefs.c main(in
                   2  main             1500 alpha/alpha/ieee_float.c main(i
                   3  main             227 boot/alpha/boot1/boot1.c main()
              ....
              [/usr/src/sys] show 3
              (Load editor and show boot/alpha/boot1/boot1.c at line 227.)
              [/usr/src/sys] x fork          <- push new tag on tag stack.
              >    1  fork              94 kern/kern_fork.c fork(p, uap)
              [/usr/src/sys] pop             <- pop tag stack.
              [/usr/src/sys] show
              (Load editor and show boot/alpha/boot1/boot1.c at line 227.)

Applied usage.
--------------

  * You can memory tags using 'mark' command.

              [/usr/src/sys] x fork
              >    1  fork              94 kern/kern_fork.c fork(p, uap)
              [/usr/src/sys] mark
              [/usr/src/sys] x main
              >    1  main              70 alpha/alpha/gensetdefs.c main(in
                   2  main             1500 alpha/alpha/ieee_float.c main(i
                   3  main             227 boot/alpha/boot1/boot1.c main()
              ....
              [/usr/src/sys] mark -l              <- show marker list.
                   1  fork              94 kern/kern_fork.c fork(p, uap)
              [/usr/src/sys] mark 1               <- select a marker.
              (Load editor and show kern/kern_fork.c at line 227.)
              [/usr/src/sys] list
              >    1  main              70 alpha/alpha/gensetdefs.c main(in
                   2  main             1500 alpha/alpha/ieee_float.c main(i
                   3  main             227 boot/alpha/boot1/boot1.c main()
              ....

     Marked tags are valid until you get out of current project or quit current bash session.

  * You can memory directories using 'cookie' command.

              [/usr/src/sys] cookie               <- drop cookie.
              [/usr/src/sys] cd kern
              [/usr/src/sys]/kern cookie          <- drop cookie again.
              [/usr/src/sys]/kern cd ../i386
              [/usr/src/sys]/i386 cookie -l       <- show cookie list.
                   1  /usr/src/sys/kern
                   2  /usr/src/sys
              [/usr/src/sys]/i386 warp 2          <- warp to selected cookie.
              [/usr/src/sys] _

     Cookie directories are valid until you delete them.

Less using GLOBAL.
==================

You can use GLOBAL as a tag system of less instead of ctags.

Features.
---------

  * You can use most of GLOBAL's facilities from less-370 or the later.

  * Less viewer support duplicated tag.

Preparation.
------------

First, do the preparation of global. See Preparation.

Second, to use global from less, you need to set environment variable LESSGLOBALTAGS to "global".

         $ export LESSGLOBALTAGS=global

Basic usage.
------------

  * To go to func1, you can say

              $ less -t func1

     Please note that if tags exist then less use it. If you want to use GTAGS even if tags exist then please specify tag file explicitly like this.

              $ less -TGTAGS -t func1

  * To go to the referenced point of func1, please specify GRTAGS.

              $ less -TGRTAGS -t func1

     In the same way, you can use GTAGS, GRTAGS, GSYMS, GPATH as tag file.

  * If a number of objects are located, less goes to the first tag. You can go to next tag by typing t and back by typing T.

     t
          go to next tag.

     T
          go to previous tag.

  * From less session, you can use :t command to locate new symbol. But in this case, you cannot change tag file from one specified by -T option.

Applied usage.
--------------

  * With -T- option, less read standard input as tag file. It is very valuable. You can connect global and less with pipe line.

              $ global -x func | less -T-

     In the same way, you can use following command lines.

              # pattern match with grep(1).
              $ global -xg 'lseek(.*)' | less -T-

              # pattern match with idutils(1).
              $ global -xI func | less -T-

              # all objects definitions in *.c.
              $ global -f *.c | less -T-

              # all files includes 'init' in its path.
              $ global -Px init | less -T-

  * If your editor doesn't support GLOBAL directly then you can use less as a footstool.

              # invoke less
              $ less -t main
              main(int argc, char **argv)
              {
              int i;
              .....
              [xxx/main.c (tag 1 of 55)]

              # type 'v'(vi) command in less session.
              v

              # load vi and show the same position.
              .....
              main((int argc, char **argv)
              {
              int i;
              .....
              [xxx/main.c 313 lines, 7783 char]

              # type 'ZZ' command in vi session.
              ZZ

              # exit vi and back to less session.
              main(int argc, char **argv)
              {
              int i;
              .....
              [xxx/main.c (tag 1 of 55)]

Extended nvi-1.79 using GLOBAL.
===============================

You can use GLOBAL as a tag system of Nvi editor instead of ctags.

Features.
---------

  * You can use most of GLOBAL's facilities from the editor.

  * Recognition of the current token and its type.

  * Extended nvi is completely backward-compatible with the original nvi. You can use GLOBAL's facilities only in 'gtags mode'.

Preparation.
------------

First, do the preparation of global. See Preparation.

Second, to use global from nvi, you need to get into gtagsmode. There are several ways to do this:

 1. Start nvi with -G option

              $ nvi -G file.c

 2. Start nvi and execute set gtagsmode.

              $ nvi file.c
              ~
              ~
              ~
              :set gtagsmode

 3. Write the above set command to the .exrc or .nexrc and start nvi

              $HOME/.exrc
              +----------------------------
              |set gtagsmode

     You must start nvi under the source tree described in Preparation.

Basic usage.
------------

  * To go to func1, you can say

              :tag func1

     It seemes the same as original nvi, but extended nvi use GTAGS instead of tags.

  * To go to the referenced point of func1, add the option -r

              :tag -r func1

     Extended nvi use GRTAGS.

  * If a number of objects are located, extended nvi goes to the first tag. You can go to next tag by typing :tagnext and back by typing :tagprev.

              Suggested .nexrc:
              set gtagsmode
              map ^N :tagnext^M
              map ^P :tagprev^M

  * CTL-] command is available. In gtags mode, if current token is not a function then it is equivalent to :tag -s CURRENT TOKEN. Otherwise, if you are in the first column of a line, it is equivalent to :tag -r CURRENT TOKEN else it is equivalent to :tag CURRENT TOKEN.

  * You can use the -s option. It locates any symbols which are not defined in GTAGS.

              :tag -s pat

     Extended nvi use GSYMS.

  * The -g, -f and -P option are also available. It works like command line. Extended nvi use no index file.

              :tag -g pat

  * Other tag commands are also available:

     CTL-T
          Return to the most recent tag context.

     :tagpop
          Go to the specified tag in the tags stack.

     :tagtop
          Go to the top tag in the tags stack.

     :display tags
          Display the tags stack.

Applied usage.
--------------

  * In large projects that include many main() function like MH, you can start nvi like this:

              $ nvi -G -t main

     You can browse all commands sequentially.

  * When you want to check objects the name of which start with "set" or "get", use:

              $ nvi -G -t '^[sg]et'

     Of course, the following command is also available:

              :tag ^[sg]et

  * If your source files are on a read only device like a CD-ROM, please do the following:

              $ mkdir /var/dbpath             # directory for the tag file
              $ cd /cdrom/src                 # the root of the source tree
              $ gtags /var/dbpath             # make tag files in /var/dbpath
              $ export GTAGSROOT=`pwd`
              $ export GTAGSDBPATH=/var/dbpath
              $ nvi -G -t main

  * If you want all references to an object that is not defined in the source tree to be treated as references to library functions or as system calls, do the following:

              $ cd /usr/src/lib
              $ gtags                         # probably as a root
              $ cd /usr/src/sys
              $ gtags
              $ export GTAGSLIBPATH=/usr/src/lib:/usr/src/sys

  * If you examine vi's source,

              $ cd /usr/src/usr.bin/vi
              $ gtags
              $ nvi -G -t main

     You can start from nvi and browse the whole unix world as if you were using hypertext.

nvi-1.81.5 using GLOBAL.
========================

You can use GLOBAL as a tag system of Nvi editor instead of ctags.

Features.
---------

  * You can use most of GLOBAL's facilities from the editor.

  * Recognition of the current token and its type.

Preparation.
------------

First, do the preparation of global. See Preparation.

Second, to use global from nvi, you need write to .nexrc like this: It assumed that gtags.pl is put on $HOME/perl.

         $HOME/.nexrc
         +----------------------------
         |perl use lib "$ENV{'HOME'}/perl"
         |perl require 'gtags.pl'
         |map ^P :tagprev^M
         |map ^N :tagnext^M
         |map ^] :perl tag^M
         |ab gtag perl tag qw(
         |ab gta perl tag qw(
         |ab gt perl tag qw(

You must start nvi under the source tree described in Preparation.

Basic usage.
------------

  * To go to func1, you can say

              :perl tag qw(func1)

              Suggested .nexrc:
              ab gtag perl tag qw(
              ab gta perl tag qw(
              ab gt perl tag qw(

  * To go to the referenced point of func1, add the option -r

              :perl tag qw(-r func1)

  * If a number of objects are located, nvi goes to the first tag. You can go to next tag by typing :tagnext and back by typing :tagprev.

              Suggested .nexrc:
              map ^N :tagnext^M
              map ^P :tagprev^M

  * If you don't specify any argument. ':perl tag' command do the followins: If current token is not a function then it is equivalent to :perl tag qw(-s CURRENT TOKEN). Otherwise, if you are in the first column of a line, it is equivalent to :perl tag qw(-r CURRENT TOKEN) else it is equivalent to :perl tag qw(CURRENT TOKEN).

              Suggested .nexrc:
              map ^] :perl tag^M

     It is similar to CTL-] command.

  * You can use the -s option. It locates any symbols which are not defined in GTAGS.

              :perl tag qw(-s pat)

  * The -g, -f and -P option are also available. It works like command line.

              :perl tag qw(-g pat)

  * When you want to check objects the name of which start with "set" or "get", use:

              :perl tag qw(^[sg]et)

  * Other tag commands are also available:

     CTL-T
          Return to the most recent tag context.

     :tagpop
          Go to the specified tag in the tags stack.

     :tagtop
          Go to the top tag in the tags stack.

     :display tags
          Display the tags stack.

Elvis using global
==================

Elvis 2.1 has new tagprg and tagprgonce variables for running an external tag search program. You can use them with GLOBAL.

Features.
---------

  * You can use most of GLOBAL's facilities from the editor.

  * No source level patch is needed.

  * Mouse events are supported.

Preparation.
------------

First, do the preparation of global. See Preparation.

Second, start elvis and execute set tagprg="global -t $1" like this.

         $ elvis
         ~
         ~
         ~
         ~
         ~
         ~
         :set tagprg="global -t $1"

Basic usage.
------------

  * To go to func1, you can say

              :tag func1

     It seemes the same as original elvis, but elvis execute global -t func1 internally and read it instead of tags file.

  * To go to the referenced point of func1, add -r option.

              :tag -r func1

     Elvis executes command like global -t -r func1 internally.

  * To go to any symbols which are not defined in GTAGS, try this.

              :tag -s lbolt

  * To go to any strings other than symbols, try this.

              :tag -g Copyright

  * When using -r, -s or -g, you had better to use browse command.

              :browse -r fork

     It brings a following selection list. You can select tag and go to the point.

              Browse -r fork (2 matches)
              +----------------+----------------+--------------------
              | TAG NAME       | SOURCE FILE    | SOURCE LINE
              +----------------+----------------+--------------------
              |fork            |ux/linux_misc.c | (line 565)
              |fork            |ern/init_main.c | (line 191)
              +----------------+----------------+--------------------

  * To get list of objects in a file, use -f command.

              :browse -f main.c               <- locate definitions in main.c

  * Other tag commands are also available:

     CTL-]
          go to the definition of current token.

     CTL-T
          return to the most recent tag context.

     :tag
          without argument, go to the next tag.

     :pop
          return to the most recent tag context.

     :stack
          display the tags stack.

     :stag
          creates a new window and moves its cursor to the tag's definition point.

     :sbrowse
          same with 'browse' but show in a new window.

Applied usage.
--------------

  * You can use POSIX regular expressions.

              :tag ^put_                  <- locate objects start with 'put_'

              :browse -g 'fseek(.*L_SET)' <- locate fseek() using L_SET argument

  * You can browse object list of many files.

              :browse -f *.c              <- locate objects in *.c

  * You can browse project files whose path includs specified pattern.

              :browse -P /vm/             <- under vm/ directory
              :browse -P \.h$             <- all include files
              :browse -P init             <- path including 'init'

  * You can use mouse to select tag.

              +----------------+----------------+--------------------
              | TAG NAME       | SOURCE FILE    | SOURCE LINE
              +----------------+----------------+--------------------
              |fork            |ux/linux_misc.c | (line 565)
              |fork            |ern/init_main.c | (line 191)
              +----------------+----------------+--------------------

     Please select tag name with mouse cursor and double click on the left button and you go to the tag's point. In source screen, also select an object name and double click on the left button and you can go to the point that the object is defined. To come back, double click on the right button.

Vim using global
================

In vim 6.2 or later, you can use gtags.vim script.

Features.
---------

  * You can use most of GLOBAL's facilities from the editor.

  * Intelligent recognition of the current token and its type.

  * Special character '%', '#' and input completion are available.

Preparation.
------------

First, do the preparation of global. See Preparation.

Second, copy gtags.vim to your plugin directory or source it from your vimrc.

         $ cp /usr/local/share/gtags/gtags.vim $HOME/.vim/plugin

Basic usage.
------------

  * To go to main, you can say

              :Gtags main

     Vim execute global -t main, parse the output, list located objects in quickfix window and load the first entry. The quickfix windows is like this:

          gctags/gctags.c|119| main
          global/global.c|154| main
          gozilla/gozilla.c|156| main
          gtags/gtags.c|199| main
          libglibc/getopt.c|701| main
          libglibc/getopt1.c|93| main
          [Error List]

     You can go to any entry using quickfix command.

     :cn
          go to the next entry.

     :cp
          go to the previous entry.

     :ccN
          go to the N'th entry.

     :cl
          list all entries.

     You can see the help of quickfix like this:

              :h quickfix

  * To go to the referenced point of func1, add -r option.

              :Gtags -r func1

     vim executes command like global -t -r func1 internally.

  * To go to any symbols which are not defined in GTAGS, try this.

              :Gtags -s lbolt

  * To go to any strings other than symbols, try this.

              :Gtags -g Copyright

  * To get list of objects in a file, use -f command.

              :Gtags -f main.c               <- locate objects in main.c

     If you are editing main.c itself, you can use '%' instead.

              :Gtags -f %                    <- locate objects in main.c

Applied usage.
--------------

  * You can use POSIX regular expressions.

              :Gtags ^put_                <- locate objects start with 'put_'

              :Gtags -g fseek(.*SEEK_SET) <- locate fseek() using SEEK_SET

  * Input completion is available.

     :Gtags fuTAB

     :Gtags func1               <- 'nc1' is appended by vim

  * You can browse project files whose path includes specified pattern.

              :Gtags -P /vm/             <- under vm/ directory
              :Gtags -P \.h$             <- all include files
              :Gtags -P init             <- path including 'init'

  * You can use all options of global(1) except for the -c, -p, -u and all long name options. They are sent to global(1) as is. For example,

              :Gtags -gi paTtern         <- match to both 'PATTERN' and 'pattern'.

     About the other options, see global.

  * The GtagsCursor command brings you to the definition or reference of the current token in C language. The GtagsCursor is not perfect though is considerably wise. If current token is not a function then it is equivalent to :Gtags -s CURRENT TOKEN. Otherwise, if you are in the first column of a line, it is equivalent to :Gtags -r CURRENT TOKEN else it is equivalent to :Gtags CURRENT TOKEN.

              :GtagsCursor

              Suggested map:
              map <C-]> :GtagsCursor<CR>

  * If you have the hypertext generated by htags(1) then you can display the same place on mozilla browser. Let's load mozilla and try this:

              :Gozilla

              Suggested map:
              map <C-g> :Gozilla<CR>

  * If you want to load vim with all main()s then following command line is useful.

              $ vim '+Gtags main'

Extended emacs using global
===========================

You can use GLOBAL as a tag system of Emacs editor instead of etags.

Features.
---------

  * You can use most of GLOBAL's facilities from the editor.

  * More intelligent recognition of the current token and its type.

  * Tag completion is available for input tag name.

  * Mouse events are supported.

Preparation.
------------

First, do the preparation of global. See Preparation.

Second, to use global from emacs, you need to load the gtags.el and execute gtags-mode function in it.

 1. Write the autoload function to the $HOME/.emacs, start emacs and execute the gtags-mode function. If you don't put gtags.el in standard macro directory, you need to add the directory to load-path.

              $HOME/.emacs
              +------------------------------------------------------
              |(setq load-path (cons "/home/owner/global" load-path))
              |(autoload 'gtags-mode "gtags" "" t)

              $ emacs

              |
              |J_:-----Mule: *scratch*       (Lisp Interaction)--L16--All----
              |M-x gtags-mode[RET]
              +------------------------------------------------------

     If you want to get into gtags-mode on c-mode then you can append followings into the $HOME/.emacs.

                (setq c-mode-hook
                    '(lambda ()
                        (gtags-mode 1)
                ))

 2. Specify the root directory of the source tree using gtags-visit-rootdir. If you have tag files in /usr/src/sys then please do like this:

              Visit root directory: /usr/src/sys

Basic usage.
------------

  * To go to func1, invoke gtags-find-tag and you can see a prompt in mini-buffer. Then input the tag name.

              Find tag: func1			<- 'Find tag: ' is a prompt

  * To go to a point that references func1, invoke gtags-find-rtag.

              Find tag (reference): func1

  * Tag name completion is available. You need to execute gtags-make-complete-list command before it.

              Find tag: fuTAB

              Find tag: func1                     <- 'nc1' is appended by emacs

  * If a number of objects are located, emacs goes into GTAGS SELECT MODE like this:

              +-------------------------------------------------------------
              |main             347 i386/isa/ultra14f.c main()
              |main             128 kern/init_main.c   main(framep)
              |main             104 netiso/clnp_debug.c main()
              |main             164 netiso/xebec/main.c main(argc, argv)
              |
              |
              |
              |
              |
              |J_:--%*-Mule: *scratch*       (Gtags Select)--L1--All----
              |[GTAGS SELECT MODE] 4 lines
              +-------------------------------------------------------------

     You can select a tag line by using any emacs command and pressing RET, and you can go to the tag's point. When you want to go to the next or the previous tag, you can return to 'GTAGS SELECT MODE' with gtags-pop-stack and reselect.

  * gtags-find-tag-from-here command is available.

     If current token is a definition, it is equivalent to Find tag (reference): CURRENT TOKENRET, otherwise it is equivalent to Find tag: CURRENT TOKENRET. (This facility is supported only in C language. GLOBAL decides this intelligentlly, but may sometimes misunderstand.)

  * To go to any symbols which are not defined in GTAGS, try gtags-find-symbol.

              Find symbol: lbolt		<- 'Find symbol:' is a prompt

  * To go to any strings other than symbols, try gtags-find-with-grep.

              Find pattern: Copyright

Applied usage.
--------------

  * You can use POSIX regular expressions.

              Find tag: ^put_                 <- locate tags start with 'put_'

  * If your source files are on a read-only device like a CDROM, please do the following:

              $ mkdir /var/dbpath             # directory for the tag file
              $ cd /cdrom/src                 # the root of the source tree
              $ gtags /var/dbpath             # make tag files in /var/dbpath
              $ export GTAGSROOT=`pwd`
              $ export GTAGSDBPATH=/var/dbpath
              $ emacs -f gtags-mode

  * If you want all references to an object that is not defined in the source tree to be treated as references to library functions or as system calls, do the following:

              $ cd /usr/src/lib
              $ gtags                         <- probably as a root
              $ cd /usr/src/sys
              $ gtags
              $ export GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
              $ emacs -f gtags-mode

  * Mouse command is avalable.

     If you use X version emacs, try the following

     Move the mouse cursor to an object name and click the middle button. You will then go to the object's definition, or to its references, depending on the context. In 'GTAGS SELECT MODE', move the mouse cursor to a line and click the center button.

     To return to the previous position, click the right button.

Hypertext generator
===================

You can use GLOBAL's facilities from WWW browser.

Features.
---------

  * Htags makes hypertext from C, C++, Yacc and Java source files.

  * Once the hypertext is generated, you need nothing other than a WWW browser.

  * You can move the hypertext to anywhere. It is independent of the source code.

  * You can use all of your browser's functions, such as search, history, bookmark, save, frames, windows.

Preparation.
------------

At first, you must ensure that you have a lot of disk space for hypertext. For example, FreeBSD 7.0 kernel source code (123MB) requires disk space from 600 to 1200MB.

         source code(/usr/src/sys)            123MB
         GPATH,GTAGS,GRTAGS,GSYMS              86MB

         hypertext (with no option)           645MB
         hypertext (with -s option)          1168MB
         hypertext (with -D option)           383MB
         hypertext (with -s and -D option)    616MB

Please invoke gtags(1)(see gtags) and htags(1)(see htags) in order like this:

         (at your source directory)
         $ gtags                 # make tag files(GTAGS,GRTAGS,GSYMS)
         $ htags                 # make hypertext(HTML/)

Then you will find an HTML subdirectory in the current directory. Htags has many options.

         Suggested option:
         $ htags -vsanohIT

If http server is available then the -D and -f option are also useful.

Usage.
------

Please start a web browser like this:

         $ lynx HTML/index.html

You will understand the usage by looking at the examples.

You can move the HTML directory to anywhere. It is independent of the source code.

Using mozilla, you can also utilize hypertext from your command line like this:

         $ mozilla				# load mozilla
         $ global -x main
         main        10 main.c main(int argc, char *argv[]) {
         $ gozilla +10 main.c		# usage is similar to vi editor.
         (show main.c at 10 on mozilla's screen.)

But in this case, you must not move HTML directory from the source directory.

Doxygen using global
====================

You can use GLOBAL as a source browser of Doxygen.

Doxygen Release 1.4.3 or later includs config option USE_HTAGS. When enabled in combination with SOURCE_BROWSER=YES, htags(1) is used as the source browser instead of doxygen's own.

Here is an example.

     (in source directory)
     $ doxygen -g
     $ vi Doxyfile
     +---------------------------------
     |...
     |INPUT                  = .
     |RECURSIVE              = YES
     |SOURCE_BROWSER         = YES
     |USE_HTAGS              = YES
     |...

     $ doxygen
     $ lynx html/index.html

Other topics
************

How to config GLOBAL.
=====================

You can customize GLOBAL using configuration file.

         # cp gtags.conf /etc/gtags.conf         # system wide config file.
         # vi /etc/gtags.conf

         $ cp gtags.conf $HOME/.globalrc         # personal config file.
         $ vi $HOME/.globalrc

If $HOME/.globalrc exists then GLOBAL use it. Else if /etc/gtags.conf exists then GLOBAL use it. Otherwise default value will be used. The format of gtags.conf is resemble to termcap(5). By default, 'default' target is used. About the capabilities, please see each command manual. See Reference.

Plug-in parser.
===============

You can write new parser and use as a plugin parser.

How to plug in a parser.
------------------------

Copy gtags.conf to /etc/gtags.conf or $HOME/.globalrc.

If you would like to use exuberant ctags included by Vim editor,

         $ cd /VIM SOURCE DIRECTORY/src/ctags
         $ cp Makefile.unix Makefile
         $ make
         # cp ctags /usr/local/bin/ctags-exuberant
         $ export GTAGSLABEL=ctags-exuberant     # see gtags.conf
         $ gtags
         $ ls G*
         GPATH   GTAGS

GRTAGS and GSYMS don't exist, simply because these parsers don't support the -r option and -s option like gtags-parser(1) does.

Requirement of plugin parser.
-----------------------------

Plug-in parser must print tag information to standard output in the same style as ctags -x, ie.:

         [1]    [2] [3]          [4]
         ----------------------------------------------------------------
         main    20 ./main.c     main(argc, argv)        /* xxx */

         [1] tag name
         [2] line number the tag appeared
         [3] path name. It must be equal to argument path name.
         [4] line image

Plug-in parser must process the files in the order they are given in the argument. In each file, any order is acceptable.

  * Good example

     The following good-prog does correct operation as a plugin parser.

                  $ good-prog a.c b.c        <= order: a.c -> b.c
                              ~~~~~~~
                  main          25 a.c  main(int argc, char *argv[])
                  func          45 a.c  func(int a) {
                  sub2          20 b.c  sub2() {
                  sub1          10 b.c  sub1() {
                                    ^
                                    |
                                   *** order: a.c -> b.c (Good!)

  * Bad example

     The following bad-prog does wrong operation as a plugin parser.

                  $ bad-prog a.c b.c        <= order: a.c -> b.c
                  main          25 a.c  main(int argc, char *argv[])
                  sub2          20 b.c  sub2() {
                  sub1          10 b.c  sub1() {
                  func          45 a.c  func(int a) {
                                    ^
                                    |
                                   *** order: b.c -> a.c (BAD!!!)

Incremental updating.
=====================

Modifying some source files, you need not remake whole tag files. Instead, you can use incremental updating facility (-u option).

         $ gtags
         $ cd kern
         $ vi tty.c                              # modify tty.c
         ...
         :wq
         $ global -vu                            # -v means verbose
         [Sun Dec  6 16:27:47 JST 1998] Gtags started
          Tag found in '/usr/src/sys'.
          Incremental update.
         [Sun Dec  6 16:28:48 JST 1998] Updating 'GTAGS'.
          [1/1] deleting tags of kern/tty.c
          [1/1] adding tags of kern/tty.c
         [Sun Dec  6 16:28:59 JST 1998] Updating 'GRTAGS'.
          [1/1] deleting tags of kern/tty.c
          [1/1] adding tags of kern/tty.c
         [Sun Dec  6 16:28:14 JST 1998] Updating 'GSYMS'.
          [1/1] deleting tags of kern/tty.c
          [1/1] adding tags of kern/tty.c
          Global databases have been modified.
         [Sun Dec  6 16:28:30 JST 1998] Done.
         $ global -vu                            # try again
         [Sun Dec  6 16:28:48 JST 1998] Gtags started
          Tag found in '/usr/src/sys'.
          Incremental update.
          Global databases are up to date.       # do nothing
         [Sun Dec  6 16:28:52 JST 1998] Done.

Command References
******************

     [file reference.texi not included]

Copying This Manual
*******************

     [file fdl.texi not included]

Business Model
**************

     [file define.texi not included]
     [file faq.texi not included]