global.txi

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

    $ vim '+Gtags main'

@end example
@end itemize

@c ***************************************************************************
@c Emacs editor
@c ***************************************************************************
@node Emacs editor
@section Extended emacs using global

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

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

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

@itemize @bullet
@item
You can use most of GLOBAL's facilities from the editor.
@item
More intelligent recognition of the current token and its type.
@item
Tag completion is available for input tag name.
@item
Mouse events are supported.
@end itemize

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

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

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

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

@example

    $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]
    +------------------------------------------------------

@end example

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

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

@end example
    
@item Specify the root directory of the source tree using
@code{gtags-visit-rootdir}.
If you have tag files in /usr/src/sys then please do like this:
@example

    Visit root directory: /usr/src/sys

@end example
@end enumerate


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

@itemize @bullet
@item To go to func1, invoke @code{gtags-find-tag}
and you can see a prompt in mini-buffer. Then input the tag name.
@example

    Find tag: func1			<- @r{'Find tag: ' is a prompt}

@end example
@item To go to a point that references func1, invoke @code{gtags-find-rtag}.

@example

    Find tag (reference): func1

@end example

@item Tag name completion is available.
     You need to execute @code{gtags-make-complete-list} command before it.
@example

    Find tag: fu@kbd{TAB}
    
    Find tag: func1                     <- @r{'nc1' is appended by emacs}

@end example

@item If a number of objects are located, emacs goes into @dfn{GTAGS SELECT MODE}
     like this:
@example

    +-------------------------------------------------------------
    |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
    +-------------------------------------------------------------

@end example

You can select a tag line by using any emacs command and pressing @kbd{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 @code{gtags-pop-stack}
and reselect.

@item @code{gtags-find-tag-from-here} command is available.

If current token is a definition, it is equivalent to
@kbd{Find tag (reference): @var{current token}RET},
otherwise it is equivalent to @kbd{Find tag: @var{current token}RET}.
(GLOBAL decides this intelligentlly, but may sometimes misunderstand.)

@item To go to any symbols which are not defined in @file{GTAGS}, try @code{gtags-find-symbol}.
@example

    Find symbol: lbolt		<- @r{'Find symbol:' is a prompt}

@end example
@item To go to any strings other than symbols, try @code{gtags-find-with-grep}.
@example

    Find pattern: Copyright

@end example
@end itemize

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

@itemize @bullet
@item You can use POSIX regular expressions.

@example

    Find tag: ^put_                 <- @r{locate tags start with 'put_'}

@end example

@item If your source files are on a read-only device like a CDROM, 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
    $ emacs -f gtags-mode

@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
    $ emacs -f gtags-mode

@end example

@item 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.
@end itemize
@c ***************************************************************************
@c Web browser
@c ***************************************************************************
@node Web browser
@section Hypertext generator

You can use GLOBAL's facilities from WWW browser.

@menu
* Features(browser)::                   Features.
* Preparation(browser)::                Preparation.
* Usage(browser)::                      Usage.
@end menu

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

@itemize @bullet
@item Htags makes hypertext from C, C++, Yacc and Java source files.
@item Once the hypertext is generated, you need nothing other than a WWW browser.
@item You can move the hypertext to anywhere. It is independent of the source code.
@item You can use all of your browser's functions, such as search,
     history, bookmark, save, frames, windows.
@end itemize

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

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:

@example

    source code(/usr/src/sys)       14.0MB
    
    GTAGS                            1.5MB
    GRTAGS                           8.0MB
    GSYMS                           12.0MB
    HTML/                           55MB(!!!)
    -------------------------------------------------
    total                           77MB

@end example

Please invoke gtags(1)(@pxref{gtags}) and htags(1)(@pxref{htags})
in order like this:

@example

    (at your source directory)
    $ gtags                 # @r{make the tag database(GTAGS,GRTAGS,GSYMS)}
    $ htags                 # @r{make the hypertext(HTML/)}

@end example

Then you will find an @file{HTML} subdirectory in the current directory.


@c ***************************************************************************
@node   Usage(browser)
@subsection Usage.

Please start a web browser like this:

@example

    $ lynx HTML/index.html

@end example

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

    $ mozilla				# @r{load mozilla}
    $ global -x main
    main        10 main.c main(int argc, char *argv[]) @{
    $ gozilla +10 main.c		# @r{usage is similar to vi editor.}
    (show main.c at 10 on mozilla's screen.)
    
@end example
But in this case, you must not move HTML directory from the source directory.

@c ***************************************************************************
@c Doxygen documentation system
@c ***************************************************************************
@node Doxygen documentation system
@section 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.

@example

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

$ doxygen
$ lynx html/index.html

@end example

@c ***************************************************************************
@c Other topics
@c ***************************************************************************
@node Other topics
@chapter Other topics

@menu
* Configuration::                       How to config GLOBAL.
* Plugin::                              How to plug in a parser.
* Compact format::                      Compact format.
* Incremental updating::                Incremental updating.
@end menu

@c ***************************************************************************
@node   Configuration
@section How to config GLOBAL.

You can customize GLOBAL using configuration file.

@example

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

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

@end example

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

@c ***************************************************************************
@node   Plugin
@section How to plug in a parser.

You can write new parser and use as a plugged-in parser.

Copy @file{gtags.conf} to @file{/etc/gtags.conf} or @file{$HOME/.globalrc}.

For example, if you would like to use ctags based on etags (included
by Emacs),

@example

    $ cd /@var{emacs source directory}/lib-src
    $ make ctags
    # cp ctags /usr/local/bin/ctags-emacs
    $ export GTAGSLABEL=ctags-emacs         # @r{see gtags.conf}
    $ gtags
    $ ls G*
    GPATH   GTAGS

@end example

Or if you would like to use exuberant ctags (included by Vim editor),

@example

    $ cd /@var{vim source directory}/src/ctags
    $ cp Makefile.unix Makefile
    $ make
    # cp ctags /usr/local/bin/ctags-exuberant
    $ export GTAGSLABEL=ctags-exuberant     # @r{see gtags.conf}
    $ gtags
    $ ls G*
    GPATH   GTAGS

@end example

@file{GRTAGS} and @file{GSYMS} don't exist, simply because
these parsers don't support the @samp{-r} option and @samp{-s} option like gtags-parser(1) does.
@opindex -r
@opindex -s
All plugged-in parsers must print tag information to standard output
in the same style as @code{ctags -x}, ie.:

@example

    [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

@end example

Otherwise, you can make a suitable wrapper for the plug-in parser.

@page
@c ***************************************************************************
@node   Compact format
@section Compact format.

You can save disk space with the compact format.

@itemize @bullet
@item To specify the use of the compact format on the command line,
     add the @samp{-c} option:
@opindex -c
@example

    $ gtags -c

@end example

@item To specify the use of the compact format in the configuration file:
@example

    +----------------------------
    |...
    |default:\
    |       format=compact:...

@end example

@item If you will publish hypertext generated by htags then use the @samp{-c} option
     of htags too:
@opindex -c
@example

    $ htags -c

@end example

With the @samp{-c} option, htags makes gzipped hypertext.
You need to set up an HTTP server so that gzipped files can be read
(see @file{HTML/.htaccess}).

@example

    Example:
    
            Standard        Compact         Compressed rate
    -------------------------------------------------------
    GTAGS    1744896 bytes   720896 bytes   -59%
    GRTAGS  10133504 bytes  1409024 bytes   -86%
    GSYMS   11911168 bytes  9306112 bytes   -22%
    
            Standard        Compact         Compressed rate
    -------------------------------------------------------
    HTML/   56618 kbytes    15219 kbytes    -73%

@end example
@end itemize

@page
@c ***************************************************************************
@node   Incremental updating
@section Incremental updating.

Modifying some source files, you need not remake whole tag files.
Instead, you can use incremental updating facility (@samp{-u} option).
@opindex -u
@example

    $ gtags
    $ cd kern
    $ vi tty.c                              # @r{modify tty.c}
    ...
    :wq
    $ global -vu                            # @r{-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                            # @r{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.       # @r{do nothing}
    [Sun Dec  6 16:28:52 JST 1998] Done.

@end example

@c ***************************************************************************
@c Reference manual.
@c ***************************************************************************
@node Reference
@chapter Command References
@include reference.txi

@c ***************************************************************************
@c FDL
@c ***************************************************************************
@node Copying This Manual
@appendix Copying This Manual

@menu
* GNU Free Documentation License::      License for copying this manual.
@end menu

@include fdl.txi

@node Index
@unnumbered Option Index
@printindex cp
@contents
@bye