global.txi

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

* Web browser::                         Hypertext generator.
* Doxygen documentation system::	Doxygen using GLOBAL.
@end menu

@c ***************************************************************************
@c GloBash
@c ***************************************************************************
@node GloBash
@section Global facility for Bash

Special support for bash is available.

@menu
* Features(globash)::			Features.
* Preparation(globash)::		Preparation.
* Basic usage(globash)::		Basic usage.
* Applied usage(globash)::		Applied usage.
@end menu

@c ***************************************************************************
@node   Features(globash)
@subsection Features.

@itemize @bullet
@item
Vi-like tag stack is available.
@item
Emacs-like tag name completion is available.
@item
Editor or viewer is automatically invoked.
@item
Tag mark facility is available.
@item
Yor can manage directory list by cookie facility.
@end itemize

@c ***************************************************************************
@node   Preparation(globash)
@subsection Preparation.

First, do the preparation of global. @xref{Preparation}.
And you can invoke bash(1) with ---rcfile option.
@example

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

@end example

You will see a prompt like this:
@example

    [/usr/src/sys]/kern _

@end example

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

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

@end example

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

If you need help then please type 'ghelp'.

@c ***************************************************************************
@node   Basic usage(globash)
@subsection Basic usage.

@itemize @bullet
@item Almost global(1)(@pxref{global})'s command character is available as a command.
@example

    [/usr/src/sys] x fork               <- @r{(global -x fork)}
    >    1  fork              94 kern/kern_fork.c fork(p, uap)
    [/usr/src/sys] r                    <- @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              <- @r{(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                    <- @r{(global -xg lbolt)}
    >    1  lbolt            1210 i386/isa/wd_cd.c     tsleep((cad
    ...
    [/usr/src/sys] P init               <- @r{(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] _

@end example

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

@item You can select a tag by show command.
@example

    [/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.)

@end example

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

@example

    [/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.)

@end example

@item You can use vi-like tag stack. You can return previous tag list by
pop or @kbd{CTL-T} command.
@example

    [/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          <- @r{push new tag on tag stack.}
    >    1  fork              94 kern/kern_fork.c fork(p, uap)
    [/usr/src/sys] pop             <- @r{pop tag stack.}
    [/usr/src/sys] show
    (Load editor and show boot/alpha/boot1/boot1.c at line 227.)

@end example

@end itemize
@c ***************************************************************************
@node   Applied usage(globash)
@subsection Applied usage.

@itemize @bullet
@item You can memory tags using 'mark' command.
@example

    [/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              <- @r{show marker list.}
         1  fork              94 kern/kern_fork.c fork(p, uap)
    [/usr/src/sys] mark 1               <- @r{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()
    ....
@end example

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

@item You can memory directories using 'cookie' command.
@example

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

@end example

Cookie directories are valid until you delete them.

@end itemize

@c ***************************************************************************
@c Less viewer
@c ***************************************************************************
@node Less viewer
@section Less using GLOBAL.

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

@menu
* Features(less)::                       Features.
* Preparation(less)::                    Preparation.
* Basic usage(less)::                    Basic usage.
* Applied usage(less)::                  Applied usage.
@end menu

@c ***************************************************************************
@node   Features(less)
@subsection Features.

@itemize @bullet
@item
You can use most of GLOBAL's facilities from less-370 or the later.
@item
Less viewer support duplicated tag.
@end itemize

@c ***************************************************************************
@node   Preparation(less)
@subsection Preparation.

First, do the preparation of global. @xref{Preparation}.

Second, to use global from less, you need to set environment variable
@code{LESSGLOBALTAGS} to "global".

@example

    $ export LESSGLOBALTAGS=global

@end example

@c ***************************************************************************
@node   Basic usage(less)
@subsection Basic usage.

@itemize @bullet
@item To go to func1, you can say
@example

    $ less -t func1

@end example

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

@example

    $ less -TGTAGS -t func1

@end example

@item To go to the referenced point of func1, please specify @file{GRTAGS}.
@example

    $ less -TGRTAGS -t func1

@end example

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

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

@table @code
@item @kbd{t}
go to next tag.
@item @kbd{T}
go to previous tag.
@end table

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

@end itemize

@c ***************************************************************************
@node   Applied usage(less)
@subsection Applied usage.

@itemize @bullet
@item With @kbd{-T-} option, less read standard input as tag file.
It is very valuable. You can connect global and less with pipe line.
@example

    $ global -x func | less -T-

@end example

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

@example
    # 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-
@end example

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

@example
    # 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)]
@end example

@end itemize

@c ***************************************************************************
@c Nvi editor
@c ***************************************************************************
@node Nvi-1.79 editor
@section Extended nvi-1.79 using GLOBAL.

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

@menu
* Features(nvi-1.79)::			Features.
* Preparation(nvi-1.79)::               Preparation.
* Basic usage(nvi-1.79)::               Basic usage.
* Applied usage(nvi-1.79)::             Applied usage.
@end menu

@c ***************************************************************************
@node   Features(nvi-1.79)
@subsection Features.

@itemize @bullet
@item
You can use most of GLOBAL's facilities from the editor.
@item
Recognition of the current token and its type.
@item
Extended nvi is completely backward-compatible with the original nvi.
You can use GLOBAL's facilities only in 'gtags mode'.
@end itemize

@c ***************************************************************************
@node   Preparation(nvi-1.79)
@subsection Preparation.

First, do the preparation of global. @xref{Preparation}.

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

@enumerate
@item
Start nvi with @samp{-G} option

@example

    $ nvi -G file.c

@end example

@item
Start nvi and execute @code{set gtagsmode}.

@example

    $ nvi file.c
    ~
    ~
    ~
    :set gtagsmode

@end example

@item
Write the above set command to the @file{.exrc} or @file{.nexrc} and start nvi

@example

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

@end example

You must start nvi under the source tree described in @ref{Preparation}.
@end enumerate

@c ***************************************************************************
@node   Basic usage(nvi-1.79)
@subsection Basic usage.

@itemize @bullet
@item To go to func1, you can say
@example

    :tag func1

@end example

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

@item To go to the referenced point of func1, add the option @kbd{-r}
@example

    :tag -r func1

@end example

Extended nvi use @file{GRTAGS}.

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

@example

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

@end example

@item @kbd{CTL-]} command is available.
In gtags mode, if current token is not a function then it is equivalent to
@kbd{:tag -s @var{current token}}.
Otherwise, if you are in the first column of a line,
it is equivalent to @kbd{:tag -r @var{current token}} else it is equivalent
to @kbd{:tag @var{current token}}.

@item You can use the @kbd{-s} option. It locates any symbols which are not
defined in @file{GTAGS}.
@example

    :tag -s pat

@end example
Extended nvi use @file{GSYMS}.

@item The @kbd{-g}, @kbd{-f} and @kbd{-P} option are also available.
It works like command line. Extended nvi use no index file.
@example

    :tag -g pat

@end example
@item Other tag commands are also available:
@table @code
@item @kbd{CTL-T}
Return to the most recent tag context.
@item @kbd{:tagpop}
Go to the specified tag in the tags stack.
@item @kbd{:tagtop}
Go to the top tag in the tags stack.
@item @kbd{:display tags}
Display the tags stack.
@end table
@end itemize


@c ***************************************************************************
@node   Applied usage(nvi-1.79)
@subsection Applied usage.

@itemize @bullet
@item In large projects that include many main() function like MH, you can start nvi like this:
@example

    $ nvi -G -t main

@end example
You can browse all commands sequentially.

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

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

@end example

Of course, the following command is also available:
@example

    :tag ^[sg]et

@end example

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

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

@end example

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

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