GNU GLOBAL is a source code tag system that works the same way
across diverse environments.
You can locate a specified object in the source files and move there easily.
It is useful for hacking a large project containing many subdirectories,
many #ifdef and many main() functions.
It is similar to ctags or etags but is different from them at the point of independence of any editor.
GNU GLOBAL can treat a source tree containing subdirectories as a project. It is similar to CVS. You can get the relative path of your object from anywhere in the source tree.
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.
GNU GLOBAL has following features:
You can use tag facilities from shell command line. It is a big merit of GLOBAL compared with any other tag system.
First of all, you must execute gtags(1)(see section 5.2 gtags - create tag files for global.) 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
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();|
|} |
+---------------+
$ 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
$ global -r func2
../DIR1/fileA.c # func2() is referred from fileA.c
$ cd ROOT
$ global 'func[1-3]'
DIR1/fileB.c # func1, func2 and func3 are matched
DIR2/fileC.c
$ global func2
DIR2/fileC.c
$ global -x func2
func2 2 DIR2/fileC.c func2(){ i++; }
func2 4 DIR2/fileC.c func2(){ i--; }
$ global -a func1
/home/user/ROOT/DIR1/fileB.c
$ global -xs X
X 1 DIR2/fileC.c #ifdef X
$ global -xg '#ifdef'
#ifdef 1 DIR2/fileC.c #ifdef X
$ 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
$ 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(){
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--; }|
+---------------+
$ cd ROOT/version1.0
$ global -x func1
func1 1 file.c func1(){ i++; }
$ cd ROOT/version2.0
$ global -x func1
func1 1 file.c func1(){ i--; }
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.
$ 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
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.
$ 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
$ 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
$ vi `global func1` # edit fileB.c
$ 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'.
Special support for bash is available.
First, do the preparation of global. See section 2.1 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'.
[/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.
[/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.)
[/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.)
[/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.
[/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.
You can use GLOBAL as a tag system of less instead of ctags.
First, do the preparation of global. See section 2.1 Preparation..
Second, to use global from less, you need to set environment variable
LESSGLOBALTAGS to "global".
$ export LESSGLOBALTAGS=global
$ 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
$ less -TGRTAGS -t func1
In the same way, you can use `GTAGS', `GRTAGS', `GSYMS',
`GPATH' as tag file.
t
T
$ 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 id-utils(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-
# 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)]
You can use GLOBAL as a tag system of Nvi editor instead of ctags.
First, do the preparation of global. See section 2.1 Preparation..
Second, to use global from nvi, you need to get into gtagsmode. There are several ways to do this:
$ nvi -G file.c
set gtagsmode.
$ nvi file.c
~
~
~
:set gtagsmode
$HOME/.exrc
+----------------------------
|set gtagsmode
You must start nvi under the source tree described in section 2.1 Preparation..
:tag func1
It seemes the same as original nvi, but extended nvi use `GTAGS'
instead of `tags'.
:tag -r func1
Extended nvi use `GRTAGS'.
Suggested .nexrc:
set gtagsmode
map ^N :tagnext^M
map ^P :tagprev^M
:tag -s pat
Extended nvi use `GSYMS'.
:tag -g pat
CTL-T
:tagpop
:tagtop
:display tags
$ nvi -G -t main
You can browse all commands sequentially.
$ nvi -G -t '^[sg]et'
Of course, the following command is also available:
:tag ^[sg]et
$ 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
$ cd /usr/src/lib
$ gtags # probably as a root
$ cd /usr/src/sys
$ gtags
$ export GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
$ 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.
You can use GLOBAL as a tag system of Nvi editor instead of ctags.
First, do the preparation of global. See section 2.1 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 section 2.1 Preparation..
:perl tag qw(func1)
Suggested .nexrc:
ab gtag perl tag qw(
ab gta perl tag qw(
ab gt perl tag qw(
:perl tag qw(-r func1)
Suggested .nexrc:
map ^N :tagnext^M
map ^P :tagprev^M
Suggested .nexrc:
map ^] :perl tag^M
It is similar to CTL-] command.
:perl tag qw(-s pat)
:perl tag qw(-g pat)
:perl tag qw(^[sg]et)
CTL-T
:tagpop
:tagtop
:display tags
Elvis 2.1 has new tagprg and tagprgonce variables for
running an external tag search program. You can use them with GLOBAL.
First, do the preparation of global. See section 2.1 Preparation..
Second, start elvis and execute set tagprg="global -t $1" like this.
$ elvis
~
~
~
~
~
~
:set tagprg="global -t $1"
:tag func1
It seemes the same as original elvis, but elvis execute global -t func1
internally and read it instead of tags file.
:tag -r func1
Elvis executes command like global -t -r func1 internally.
:tag -s lbolt
:tag -g Copyright
: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)
+----------------+----------------+--------------------
:browse -f main.c <- locate definitions in main.c
CTL-]
CTL-T
:tag
:pop
:stack
:stag
:sbrowse
:tag ^put_ <- locate objects start with 'put_'
:browse -g 'fseek(.*L_SET)' <- locate fseek() using L_SET argument
:browse -f *.c <- locate objects in *.c
:browse -P /vm/ <- under vm/ directory
:browse -P \.h$ <- all include files
:browse -P init <- path including 'init'
+----------------+----------------+--------------------
| 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.
In vim 6.2 or later, you can use gtags.vim script.
First, do the preparation of global. See section 2.1 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
: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
:cp
:ccN
:cl
:h quickfix
:Gtags -r func1
vim executes command like global -t -r func1 internally.
:Gtags -s lbolt
:Gtags -g Copyright
: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
:Gtags ^put_ <- locate objects start with 'put_'
:Gtags -g fseek(.*SEEK_SET) <- locate fseek() using SEEK_SET
:Gtags -P /vm/ <- under vm/ directory
:Gtags -P \.h$ <- all include files
:Gtags -P init <- path including 'init'
:Gtags -gi paTtern <- match to both 'PATTERN' and 'pattern'.
About the other options, See section 5.1 global - print the locations of specified object..
:GtagsCursor
Suggested map:
map <C-]> :GtagsCursor<CR>
:Gozilla
Suggested map:
map <C-g> :Gozilla<CR>
$ vim '+Gtags main'
You can use GLOBAL as a tag system of Emacs editor instead of etags.
First, do the preparation of global. See section 2.1 Preparation..
Second, to use global from emacs, you need to load the `gtags.el' and execute gtags-mode function in it.
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)
))
gtags-visit-rootdir.
If you have tag files in /usr/src/sys then please do like this:
Visit root directory: /usr/src/sys
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
gtags-find-rtag.
Find tag (reference): func1
gtags-make-complete-list command before it.
Find tag: fuTAB
Find tag: func1 <- 'nc1' is appended by emacs
+-------------------------------------------------------------
|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.)
gtags-find-symbol.
Find symbol: lbolt <- 'Find symbol:' is a prompt
gtags-find-with-grep.
Find pattern: Copyright
Find tag: ^put_ <- locate tags start with 'put_'
$ 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
$ 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
You can use GLOBAL's facilities from WWW browser.
At first, you must ensure that you have a lot of disk space. Hypertext needs a great amount of disk space. For example, the source code of FreeBSD kernel needs:
source code(/usr/src/sys) 14.0MB
GTAGS 1.5MB
GRTAGS 8.0MB
GSYMS 12.0MB
HTML/ 55MB(!!!)
-------------------------------------------------
total 77MB
Please invoke gtags(1)(see section 5.2 gtags - create tag files for global.) and htags(1)(see section 5.3 htags - generate hypertext from source code.) in order like this:
(at your source directory)
$ gtags # make the tag database(GTAGS,GRTAGS,GSYMS)
$ htags # make the hypertext(HTML/)
Then you will find an `HTML' subdirectory in the current directory.
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.
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
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 section 5. Command References.
You can write new parser and use as a plug-in 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.
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-prog does correct operation as a plug-in 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-prog does wrong operation as a plug-in 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!!!)
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.
global - print the locations of specified object.
global [-aGilnqrstTvx][-e] pattern
global -c[qsv] prefix
global -f[anqrstvx] files
global -g[aGilnoqtvx][-e] pattern
global -I[ailnqtvx][-e] pattern
global -p[qrv]
global -P[aGilnoqtvx][-e] pattern
global -u[qv]
Global find the locations of specified object in C, C++, Yacc, Java, PHP and Assembly source files. Global can treat a source tree, that is, a directory that has subdirectories and source files. You can get the relative path of objects from anywhere within the tree. Global can locate not only function definitions but also function references and other symbols. Duplicate entries are allowed.
In advance of using this command, you must execute gtags(1) at the root directory of the source tree to make tag files. Then you can execute at anywhere in the source tree.
The following commands are available:
The following options are available:
$ ls -F
Makefile src/ lib/
$ gtags
$ global main
src/main.c
$ global -x main
main 10 src/main.c main (argc, argv) {
$ global -x '^[sg]et'
set_num 20 lib/util.c set_num(values)
get_num 30 lib/util.c get_num() {
$ global -rx '^[sg]et'
set_num 113 src/op.c set_num(32);
set_num 225 src/opop.c if (set_num(0) > 0) {
get_num 90 src/op.c while (get_num() > 0) {
$ cd lib
$ global -rx '^[sg]et'
set_num 113 ../src/op.c set_num(32);
set_num 225 ../src/opop.c if (set_num(0) > 0) {
get_num 90 ../src/op.c while (get_num() > 0) {
$ global strlen
$ (cd /usr/src/sys; gtags)
$ export GTAGSLIBPATH=/usr/src/sys
$ global strlen
../../../usr/src/sys/libkern/strlen.c
$ (cd /usr/src/lib; gtags)
$ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
$ global strlen
../../../usr/src/lib/libc/string/strlen.c
The following environment variables affect the execution of global:
default.
The following configuration variables affect the execution of global:
icase_path(boolean)
Global exits with a non 0 value if an error occurred, 0 otherwise.
gtags-parser(1), gtags(1), htags(1), less(1).
GNU GLOBAL source code tag system
(http://www.gnu.org/software/global/).
Tama Communications Corporation.
The global command appeared in FreeBSD 2.2.2.
gtags - create tag files for global.
gtags [-iIqvw][-f file][-n number][dbpath]
Gtags recursively collect the source files under the current directory, pickup symbols and write the cross-reference data into tag files (`GTAGS', `GRTAGS', `GSYMS' and `GPATH'). You should execute this command at the root of the source tree.
C, C++, yacc, java, PHP and Assembly source files are supported. Files whose names end in `.c' or `.h' are assumed to be C source files and are searched for C style routine and macro definitions. Files whose names end in `.c++' `.cc' `.cpp' `.cxx' `.hxx' `.hpp' `.C' `.H' are assumed to be C++ source files. Files whose names end in `.y' are assumed to be YACC source files. Files whose names end in `.java' are assumed to be Java source files. Files whose names end in `.php' `.php3' `.phtml' are assumed to be PHP source files. Files whose names end in `.s' or `.S' are assumed to be Assembler source files. Other files are searched for C style definitions.
The following options are available:
default.
$ ls -F
Makefile src/ lib/
$ gtags -v
$ global -x main
main 10 src/main.c main (argc, argv) {
The following environment variables affect the execution of gtags:
default.
The following configuration variables affect the execution of gtags. You can see the default value for each variable with the `--config' option.
GTAGS(string)
GRTAGS(string)
GSYMS(string)
skip(comma separated list)
skip variables.
If the value ends with '/', it assumed as a directory and gtags skips all files under it.
If the value start with '/', it assumed relative path from the root of source directory.
suffixes(comma separated list)
suffixes variables.
This variable is obsoleted. If the langmap variable is defined
gtags no longer refers this.
icase_path(boolean)
langmap(comma separated list)
Gtags exits with a non 0 value if an error occurred, 0 otherwise.
Verbose message has important level. The most important level is 0, the second is 1 and so on. All the message has level numbers leading blanks.
gtags-parser(1), global(1), htags(1).
GNU GLOBAL source code tag system
(http://www.gnu.org/software/global/).
`GTAGS', `GRTAGS' and `GSYMS' are very large. In advance of using this command, check the space of your disk.
Assembler support is far from complete. It extracts only ENTRY() and ALTENTRY() from source file. Probably valid only for FreeBSD and Linux kernel source.
There is no concurrency control about tag files.
Symbols in Assembly source files are not extracted for `GSYMS'.
Tama Communications Corporation.
The gtags command appeared in FreeBSD 2.2.2.
htags - generate hypertext from source code.
htags [-acDfFghInosTvwx][-d dbpath][-m name][-S cgidir][-t title][dir]
Htags makes hypertext of C, C++, Yacc, Java, PHP and Assembly source code.
In advance of using this command, you must execute gtags(1) from the root directory of the source tree. Then you can execute htags from the same place. Htags makes an directory named `HTML' and generates hypertext in it. You can start browsing from `HTML/index.html'.
Since htags generates static hypertext as long as the `-D' or `-f' option is not specified, you can move it anywhere and browse it with any browser without web server.
You must use same parser for both gtags(1) and htags. If you use the default parser, it is not necessary to consider for it.
The following options are available:
default.
main.
script_alias in `gtags.conf'.
xhtml_version is set to 1.1 then generate
XHTML-1.1 else XHTML 1.0 Transitional.
$ gtags -v $ htags -sanohITvt 'Welcom to XXX source tour!' $ firefox HTML/index.html
The following environment variables affect the execution of htags:
default.
The following configuration variables affect the execution of htags: If the `--xhtml' option is specified then all definitions of HTML tag are ignored. Instead, you can customize the appearance using style sheet file (`style.css').
datadir(string)
htags_options(string)
xhtml_version(1.0|1.1)
body_begin(string)
body_end(string)
table_begin(string)
table_end(string)
title_begin(string)
title_end(string)
comment_begin(string)
comment_end(string)
dynamic(bool)
sharp_begin(string)
sharp_end(string)
brace_begin(string)
brace_end(string)
reserved_begin(string)
reserved_end(string)
position_begin(string)
position_end(string)
colorize_warned_line(boolean)
warned_line_begin and warned_line_end.
The default is false.
warned_line_begin(string)
warned_line_end(string)
hr(string)
ncol(number)
tabs(number)
flist_fields(number)
full_path(boolean)
table_list(boolean)
table_flist(boolean)
normal_suffix(string)
no_map_file(boolean)
gzipped_suffix(string)
script_alias(string)
show_position(boolean)
definition_header(no|before|right|after)
other_files(boolean)
disable_grep(boolean)
enable_idutils(boolean)
include_file_suffixes(comma separated list)
langmap(comma separated list)
copy_files(boolean)
Htags exits with a non 0 value if an error occurred, 0 otherwise.
Verbose message has important level. The most important level is 0, the second it 1 and so on. All the message has level numbers leading blanks.
gtags-parser(1), global(1), gtags(1).
GNU GLOBAL source code tag system
(http://www.gnu.org/software/global/).
Generated hypertext is VERY LARGE. In advance, check the space of your disk.
PHP supprt is far from complete.
Tama Communications Corporation.
The htags command appeared in FreeBSD 2.2.2.
gtags-parser - print cross reference list for gtags.
gtags-parser [-bdenrstvw] file ...
Gtags-parser print cross reference list for gtags(1) from the specified C, C++, yacc, java, PHP and Assembly source to standard output. Each line of output contains the object name, the line number which it appears, the file in which it is defined, and a line image separated by white-space. It's same with the output of ctags(1) with `-x' option.
Depending upon the options provided to gtags-parser, objects will consist of function definitions, function references and other symbols.
Files whose names end in `.c' or `.h' are assumed to be C source files and are searched for C style routine and macro definitions. Files whose names end in `.c++' `.cc' `.cpp' `.cxx' `.hxx' `.hpp' `.C' `.H' are assumed to be C++ source files. Files whose names end in `.y' are assumed to be YACC source files. Files whose names end in `.java' are assumed to be Java source files. Files whose names end in `.php' `.php3' `.phtml' are assumed to be PHP source files. Files whose names end in `.s' or `.S' are assumed to be Assembler source files. Other files are searched for C style definitions.
Yacc files each have a special tag. yyparse is the start of the second section of the yacc file.
This command is the default parser of GLOBAL source code tag system.
The following options are available:
The `-r' and `-s' options override each other; the last one specified determines the method used.
Gtags-parser exits with a non 0 value if an error occurred, 0 otherwise. Duplicate objects are not considered errors.
global(1), gtags(1), htags(1).
GNU GLOBAL source code tag system
(http://www.gnu.org/software/global/).
Gtags-parser relies on the input being well formed, and any syntactical errors will completely confuse it.
Assembler support is far from complete. Probably valid only for FreeBSD and Linux kernel source.
Tama Communications Corporation.
The gtags-parser(gctags) command appeared in FreeBSD 2.2.2.
gozilla - force mozilla to display specified source file.
gozilla [-b browser][-p][+no] file
gozilla [-b browser][-p] -d name
Gozilla force mozilla to display specified source file as a hypertext. Gozilla can be used with other browsers like firefox and epiphany.
In advance of using this command, you must execute gtags(1) and htags(1) at the root directory of the source tree to make tag files. Then you can execute gozilla at anywhere in the source tree.
First form:
You can specify source file and the line number optionally.
Second form:
You can specify definition name directly. Definition name must exist
in `GTAGS' tag file.
Some browsers require you to load it before executing gozilla. Whether or not gozilla waits for exiting of browser depends on browser.
The following options are available:
$ gtags $ htags $ global -x main main 82 ctags.c main(argc, argv) $ mozilla & $ gozilla +82 ctags.c $ firefox & $ gozilla -b firefox +82 ctags.c $ setenv BROWSER 'epiphany --new-tab' $ epiphany & $ gozilla +82 ctags.c
Gozilla exits with a non 0 value if an error occurred, 0 otherwise.
global(1), gtags(1), htags(1), firefox(1), epiphany(1), mozilla(1).
GNU GLOBAL source code tag system
(http://www.gnu.org/software/global/).
Gozilla means 'Global for mozilla'.
Gozilla can treat not only source file but also normal file, directory, HTML file and even URL, because it is omnivorous.
Tama Communications Corporation.
The gozilla command appeared in FreeBSD 2.2.2 but did not installed by default.
gtags-cscope - pseudo cscope which implements the line-oriented interface
gtags-cscope [-Cqv]
Gtags-cscope is a pseudo cscope which implements the line-oriented interface. You can use this command for various clients instead of true cscope.
Since gtags-cscope is intended to make GLOBAL available through cscope interface, the output is not necessarily the same as cscope.
The following options are available:
$ gtags-cscope >> help 0<arg>: Find this C symbol 1<arg>: Find this definition 2<arg>: Find functions called by this function (Not implemented yet.) 3<arg>: Find functions calling this function 4<arg>: Find this text string 6<arg>: Find this egrep pattern 7<arg>: Find this file 8<arg>: Find files #including this file c: Toggle ignore/use letter case r: Rebuild the database q: Quit the session h: Show help >> 1main cscope: 9 lines global/global.c main 158 main(int argc, char **argv) gozilla/gozilla.c main 155 main(int argc, char **argv) gtags-parser/gctags.c main 158 main(int argc, char **argv) gtags-cscope/gtags-cscope.c main 115 main(int argc, char **argv) gtags/gtags.c main 150 main(int argc, char **argv) htags-refkit/htags_path2url.c main 281 main(int argc, char **argv) htags/htags.c main 1400 main(int argc, char **argv) libglibc/getopt.c main 704 main (argc, argv) libglibc/getopt1.c main 93 main (argc, argv) >> q $ _
Gtags-cscope exits with a non 0 value if an error occurred, 0 otherwise.
cscope(1), gtags-parser(1), gtags(1), global(1), htags(1).
GNU GLOBAL source code tag system
(http://www.gnu.org/software/global/).
The second field of the output is almost <unknown> since GLOBAL doesn't recognize it. Command 2 (Find functions called by this function) is not implemented.
Tama Communications Corporation.
The gtags-cscope command appeared in 2006.
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. 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, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Jump to: f
This document was generated on August, 8 2006 using texi2html 1.57.