global.txi

代码检索工具GLOBAL源码。可用来浏览分析LINUX源码。

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename global.info
@settitle GNU GLOBAL source code tag system
@comment %**end of header

@include version.texi

@c Define new index for options.
@defcodeindex op
@syncodeindex op cp

@ifinfo
@dircategory Development
@direntry
* GLOBAL: (global).             GNU GLOBAL source code tag system.
@end direntry
@end ifinfo

@ifinfo
This file documents the GNU GLOBAL source code tag system.

Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005
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".
@end ifinfo

@titlepage
@title GNU GLOBAL Source Code Tag System
@subtitle Edition @value{EDITION}, for GNU GLOBAL version @value{VERSION}
@subtitle @value{UPDATED}
@author by Tama Communications Corporation
@c copyright page
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005
Tama Communications Corporation
@sp 2
This is the first edition of the GNU GLOBAL documentation,@*
and is consistent with @value{VERSION}.@*
@sp 2
Published by Tama Communications Corporation @*
Tama-shi, Tokyo, Japan.@*

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".

@end titlepage

@node Top
@top GNU GLOBAL source code tag system

This manual documents version @value{VERSION} of the GNU GLOBAL source code tag system.

@menu
* Introduction::                        Overview of the tools.
* Global::                              Command line GLOBAL.
* Applications::			Various applications.
* Other topics::                        Other topics.
* Reference::                           Command References.
* Copying This Manual::                 Copying This Manual.
* Index::                               Option index.
@end menu

@c ***************************************************************************
@c Introduction
@c ***************************************************************************
@node Introduction
@chapter Overview of the tools

@section What is this?

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 @code{#ifdef} and many @code{main()} functions.

It is similar to ctags or etags but is different from them at the point of
independence of any editor.

@section Concept of project.

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.

@section Features.

GNU GLOBAL has following features:

@itemize @bullet
@item support C, C++, Yacc, Java, PHP4 and assembly.
@item work the same way across diverse environments. Currently, support followings:
	@itemize @minus
	@item Shell command line
	@item Bash shell.
	@item Vi editor clone (nvi, elvis, vim)
	@item Less viewer
	@item Emacs editor (emacs, mule, xemacs)
	@item Glimmer editor
	@item Web browser
	@item Doxygen documentation system
	@end itemize
@item find the locations of a specified object quickly.
@item locate not only object definitions but also object references.
@item allows duplicate objects.
@item locate also path which includes specified pattern.
@item search not only in a source tree but also in library paths.
@item understand POSIX 1003.2 regular expressions.
@item support external search engine (grep and id-utils).
@item generate hypertext of source code.
@item tag files are independent of machine architecture.
@item plugged-in parser is available to treat new language.
@item compact format is available to save disk space.
@item support incremental updating of tag files.
@item support customizing with gtags.conf.
@item generate completion list for completing input method.
@end itemize

@c ***************************************************************************
@c Global
@c ***************************************************************************
@node Global
@chapter 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.

@menu
* Preparation::                         Preparation.
* Basic usage::                         Basic usage.
* Applied usage::                       Applied usage.
@end menu

@c ***************************************************************************
@node   Preparation
@section Preparation.

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

@example

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

@end example

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

@example

    $ ls G*
    GPATH   GRTAGS  GSYMS   GTAGS

@end example

@itemize @bullet
@item @file{GTAGS}
        database of object definitions
@item @file{GRTAGS}
        database of object references
@item @file{GSYMS}
        database of other symbols
@item @file{GPATH}
        database of path names
@end itemize

@page
@c ***************************************************************************
@node   Basic usage
@section Basic usage.

Consider the following source tree:

@example

    ROOT/           <- @r{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();|
                            |@}              |
                            +---------------+

@end example

@itemize @bullet
@item 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.

@example

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

@end example

@item The @samp{-r} option locates object references.
@opindex -r

@example

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

@end example

@item You can use POSIX regular expressions.

@example

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

@end example

@item The @samp{-x} option shows the details.
It is similar to the @samp{-x} option in ctags(1).
@opindex -x

@example

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

@end example

@item The @samp{-a} option produces the absolute path name.
@opindex -a

@example

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

@end example

@item The -s command locates any symbols which are not defined in @file{GTAGS}.
@opindex -s

@example

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

@end example

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

@example

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

@end example

@item The -P command enables you to locate path which includes specified
string.
@opindex -P

@example

    $ 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

@end example

@item The -f command enables you see the list of objects of specified file.
@opindex -f

@example

    $ 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()@{

@end example

@end itemize

@page
@c ***************************************************************************
@node   Applied usage
@section Applied usage.

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

@example


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

@end example

@itemize @bullet
@item When you are in the version1.0 directory, global will only locate objects
that are in version1.0.

@example

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

@end example

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

@example

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

@end example

@item If you are at ROOT/, or you set the @code{GTAGSROOT} environment variable to ROOT,
then global will locate objects in both directories.

@example

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

@end example

@end itemize

There is another usage of @code{GTAGSROOT}.

@itemize @bullet

@item 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:

@example

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

@end example

@item 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 @code{GTAGSLIBPATH} environment
variable.

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

@example

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

@end example

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


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

@example

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

@end example

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

In bash:
@example

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

@end example

In tcsh:
@example

    % set funcs=(`global -c`)
    % complete global 'n/*/$funcs/'
    % global kmem_@kbd{TAB}
    kmem_alloc          kmem_free_wakeup
    kmem_alloc_pageable kmem_init
    kmem_alloc_wait     kmem_malloc
    kmem_free           kmem_suballoc
    % global kmem_s@kbd{TAB}
    % global kmem_suballoc
    ../vm/vm_kern.c

@end example

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

@example

    $ vi `global func1`     # @r{edit fileB.c}

@end example

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

@example

    $ 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            # @r{from now on, go to next tag with 'ZZ'.}

@end example

@end itemize

@c ***************************************************************************
@c Applications
@c ***************************************************************************
@node Applications
@chapter Various applications

@menu
* GloBash::                             Global facility for Bash.
* Less viewer::                         Less using GLOBAL.
* Nvi-1.79 editor::                     Extended nvi-1.79 using GLOBAL.
* Nvi-1.81.5 editor::                   nvi-1.81.5 using GLOBAL.
* Elvis editor::                        Elvis using GLOBAL.
* Vim editor::                          Vim using GLOBAL.
* Emacs editor::                        Extended emacs using GLOBAL.