head	1.2;
access;
symbols
	RELENG_4_11_0_RELEASE:1.1.1.4.6.1
	RELENG_4_11:1.1.1.4.6.1.0.18
	RELENG_4_11_BP:1.1.1.4.6.1
	RELENG_4_10_0_RELEASE:1.1.1.4.6.1
	RELENG_4_10:1.1.1.4.6.1.0.16
	RELENG_4_10_BP:1.1.1.4.6.1
	RELENG_4_9_0_RELEASE:1.1.1.4.6.1
	RELENG_4_9:1.1.1.4.6.1.0.14
	RELENG_4_9_BP:1.1.1.4.6.1
	RELENG_4_8_0_RELEASE:1.1.1.4.6.1
	RELENG_4_8:1.1.1.4.6.1.0.12
	RELENG_4_8_BP:1.1.1.4.6.1
	RELENG_4_7_0_RELEASE:1.1.1.4.6.1
	RELENG_4_7:1.1.1.4.6.1.0.10
	RELENG_4_7_BP:1.1.1.4.6.1
	RELENG_4_6_2_RELEASE:1.1.1.4.6.1
	RELENG_4_6_1_RELEASE:1.1.1.4.6.1
	RELENG_4_6_0_RELEASE:1.1.1.4.6.1
	RELENG_4_6:1.1.1.4.6.1.0.8
	RELENG_4_6_BP:1.1.1.4.6.1
	RELENG_4_5_0_RELEASE:1.1.1.4.6.1
	RELENG_4_5:1.1.1.4.6.1.0.6
	RELENG_4_5_BP:1.1.1.4.6.1
	RELENG_4_4_0_RELEASE:1.1.1.4.6.1
	RELENG_4_4:1.1.1.4.6.1.0.4
	RELENG_4_4_BP:1.1.1.4.6.1
	RELENG_4_3_0_RELEASE:1.1.1.4.6.1
	RELENG_4_3:1.1.1.4.6.1.0.2
	RELENG_4_3_BP:1.1.1.4.6.1
	RELENG_4_2_0_RELEASE:1.1.1.4.6.1
	RELENG_4_1_1_RELEASE:1.1.1.4
	PRE_SMPNG:1.1.1.4
	RELENG_4_1_0_RELEASE:1.1.1.4
	RELENG_3_5_0_RELEASE:1.1.1.4
	RELENG_4_0_0_RELEASE:1.1.1.4
	RELENG_4:1.1.1.4.0.6
	RELENG_4_BP:1.1.1.4
	RELENG_3_4_0_RELEASE:1.1.1.4
	RELENG_3_3_0_RELEASE:1.1.1.4
	RELENG_3_2_PAO:1.1.1.4.0.4
	RELENG_3_2_PAO_BP:1.1.1.4
	RELENG_3_2_0_RELEASE:1.1.1.4
	RELENG_3_1_0_RELEASE:1.1.1.4
	RELENG_3:1.1.1.4.0.2
	RELENG_3_BP:1.1.1.4
	v3_4_2:1.1.1.4
	RELENG_2_2_8_RELEASE:1.1.1.3.2.1
	RELENG_3_0_0_RELEASE:1.1.1.3
	RELENG_2_2_7_RELEASE:1.1.1.3.2.1
	RELENG_2_2_6_RELEASE:1.1.1.3.2.1
	RELENG_2_2:1.1.1.3.0.2
	v2_2_4:1.1.1.3
	v2_2_1:1.1.1.2
	v2_0:1.1.1.1
	GLOBAL:1.1.1;
locks; strict;
comment	@# @;


1.2
date	2000.10.15.07.01.43;	author obrien;	state dead;
branches;
next	1.1;

1.1
date	97.08.16.04.13.55;	author cwt;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	97.08.16.04.13.55;	author cwt;	state Exp;
branches;
next	1.1.1.2;

1.1.1.2
date	97.12.15.23.08.02;	author cwt;	state Exp;
branches;
next	1.1.1.3;

1.1.1.3
date	98.02.02.05.37.34;	author cwt;	state Exp;
branches
	1.1.1.3.2.1;
next	1.1.1.4;

1.1.1.4
date	99.01.18.06.58.43;	author simokawa;	state Exp;
branches
	1.1.1.4.6.1;
next	;

1.1.1.4.6.1
date	2000.10.16.08.53.27;	author obrien;	state dead;
branches;
next	;

1.1.1.3.2.1
date	98.02.05.04.41.26;	author cwt;	state Exp;
branches;
next	;


desc
@@


1.2
log
@Remove GLOBAL -- it has moved to Ports.

Approved by:	unanimous response on arch@@freebsd.org (June time frame)
@
text
@
           @@@@@@@@@@@@@@=
	 @@=       @@=
	@@=                                          @@=
	@@=            @@=    @@@@@@@@@@= @@@@@@@@@@@@=     @@@@=  @@=
	@@=  F o r   a l l   h a c h e r s.    version 2.0
	@@=     @@@@@@@@@@@@=@@=   @@=    @@= @@@@@@@@@@=   @@= @@=  @@=
	@@=        @@=  @@=   @@=    @@= @@=   @@= @@@@@@@@@@=  @@=
	 @@=       @@=  @@=   @@=    @@= @@=   @@=@@=   @@=  @@=
	  @@@@@@@@@@@@@@@@=   @@@@@@@@= @@@@@@@@@@= @@@@@@@@@@@@=@@@@@@= @@@@@@@@= @@@@@@@@@@@@=

					Shigio Yamaguchi	7-Jul-97

		Copyright 1996, 1997 Shigio Yamaguchi All right resereved.

GLOBAL is a browsing system for C and Yacc source code.
It brings benefits to all hackers.  Enjoy!

		Contents
		--------------------------------
		0. Introduction

		1. Global

		1.1. Features
		1.2. Preparation
		1.3. Basic usage
		1.4. Applied usage

		2. Extended vi using global

		2.1. Features
		2.2. Preparation
		2.3. Basic usage
		2.4. Applied usage

		3. Hypertext generator

		3.1. Features
		3.2. Preparation
		3.3. Usage
		3.4. To make hypertext of kernel

		4. Extended emacs using global

		4.1. Features
		4.2. Preparation
		4.3. Basic usage
		4.4. Applied usage
		--------------------------------

0. Introduction

GLOBAL is a browsing system for C and Yacc source files.
You can locate the specified function in C source files and move there easily.
It is useful to hack a large project containing many subdirectories,
many '#ifdef' and many main() functions like MH, X or BSD kernel.

It supports following environments.

   o shell command line(see '1. Global')
   o vi editor(see '2. Extended vi using global')
   o web browser(see '3. Hypertext generator')
   o emacs editor(see '4. Emacs using global')

GLOBAL is consist of global(1), gtags(1), btreeop(1), gctags(1), htags(1),
extended vi(1) and gtags.el.

	* 'extended' means being entended for GLOBAL.

	* Btreeop and gctags are used internally, so you need not
	  understand about them.

The extended vi is completely upper compatible with original one.
All the functions for GLOBAL are enabled only in 'gtagsmode'.

------------------------------------------------------------------------------

1. Global

1.1. Features

   o Global can find the locations of a specified function quickly.
   o Global can locate not only function definitions but also function references.
   o Global allows duplicate entries.
   o Global can treat a source tree containing subdirectories and you can
     get relative path of objects from anywhere within the tree.
   o Global can understand perl's regular expression.
   o Global can search in not only a source tree but also library paths.
   o Global can treat yacc source file.

   I think these features are useful for a large project containing many
   subdirectories, many '#ifdef' and many main() functions like MH.

1.2. Preparation

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

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

   Gtags traverse subdirectories and makes
   two database at the root of source tree.

	% ls G*TAGS
	GRTAGS  GTAGS
	 
	GTAGS	- database for function definition
	GRTAGS	- database for function reference

   If you cannot find functions that should exist, please try -e option.

	% gtags -e

1.3. Basic usage

   Please think of 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 within
   the source tree.

	% 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

   -r option locates function references.

	% global -r func2
	../DIR1/fileA.c		<- func2() is referred from fileA.c

   You can use perl's regular expression.

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

   -x option shows the detail. It's similar to ctags's -x option.

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

   -a option produces the absolute path name.

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

   You can edit files including specified function directly like this.

	% vi `global func1`	<- edit fileB.c


1.4. 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,GRTAGS)
	|
	|- version1.0/		<- the root of version1.0	(GTAGS,GRTAGS)
	|  |
	|  |- file.c	.....	+---------------+
	|			|func1(){ i++; }|
	|			+---------------+
	|
	|- version2.0/		<- the root of version2.0	(GTAGS,GRTAGS)
	   |
	   |- file.c	.....	+---------------+
	 			|func1(){ i--; }|
	 			+---------------+

   When you are walking in version1.0 directory, global locates functions
   only in version1.0.

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

   When you are walking in version2.0, global locates functions only in
   version2.0.

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

   If you are at ROOT/ or you set GTAGSROOT environment variable to ROOT,
   global locates functions in both version1.0 and version2.0 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 like CDROM, you cannot
   make database on the root of source tree.
   In such case, please do the following.

	% mkdir /var/dbpath
	% cd /cdrom/src			<- the root of source tree
	% gtags /var/dbpath		<- make tag file in /var/dbpath
	% setenv GTAGSROOT `pwd`
	% setenv GTAGSDBPATH /var/dbpath
	% global func

   =-=-=-=

   If you want to treat the references to a function that is not defined
   in the source tree like a library function or system call, 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 it.

	% 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
	% setenv GTAGSLIBPATH /usr/src/lib:/usr/src/sys
	% global strlen
	../../../usr/src/lib/libc/string/strlen.c	<- strlen() is found in library
	% global access
	../../../usr/src/sys/kern/vfs_syscalls.c	<- access() is found in kernel

	Of course, user program doesn't call kernel function directly, but
	at least it is useful.

   =-=-=-=

   If you forget function name, you can use -c (complete) option.

	% 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 -c option with tcsh's complete command.

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

		* <TAB> means tab key or Ctrl-I.

   =-=-=-=

   If you want to browse many files in order, do the followings.

	% global -xr fork | awk '{printf "view +%s %s\n",$2,$3}' | tee /tmp/list
	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'.

2. Extended vi using global

2.1. Features

   o Tag function of extended vi can locate not only function definitions
     but also function references.
   o Extended vi allows duplicate tag entries.
   o Extended vi can understand perl's regular expression as a tag name
     for search.
   o Extended vi is completely upper compatible with original one.
     Above functions are available only in 'gtags mode'.

2.2. Preparation

   First, do the preparation of global. (Please see "1.2. Preparation").

   Second, to use global from vi, you need to get into 'gtagsmode'.
   There are some ways to do it.

   (a) Start vi with -G option

   	% vi -G file.c

   (b) Start vi and execute "set gtagsmode"

   	% vi file.c
   	~
   	~
   	~
   	:set gtagsmode

   (c) Previously write the set command to .exrc or .nexrc file and start vi

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

   You must start vi under the source tree described in "1.2. Preparation".

2.3. Basic usage

   o To go to func1, you can say

	:tag func1

     It seemes same with original vi, but extended vi use GTAGS
     instead of tags.

   o To go to referenced point of func1, add prefix 'r'

   	:rtag func1

     Extended vi use GRTAGS.

   o If a number of functions located, the action of extended vi differs
     up to your nvi's version.

     [Extended vi based 1.34 nvi]

     Vi 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)
	|~
	|~
	|~
	|~
	|~
	|[GTAGS SELECT MODE] 4 lines
	+-------------------------------------------------------------

     You can select a tag line by any vi command and press [RETURN],
     and you can go to the tag's point. In ex mode, type "select"
     instead of [RETURN]. When you want to go to next or previous tag,
     you can return to 'GTAGS SELECT MODE' with <control-T> and reselect.

     Suggested .nexrc:
	set gtagsmode
	set leftright

     [Extended vi based 1.79 nvi]

     Vi goes to the first tag.
     Then you can go to next tag by ':tagnext' or back by ':tagprev'.

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

     == WHY TWO STYLE EXIST ? ==
     1.34 nvi cannot treat duplicate tag entries, so I made 'GTAGS SELECT MODE'
     in it. But 1.79 nvi (1.61 and later) can treat them, so I adapted GLOBAL
     tags to nvi's tag structure.

   o <control-]> command is available.

     In gtagsmode, if you are on the first column of line, it is identical to
     ":rtag <current token>[RETURN]", otherwise ":tag <current token>[RETURN]".

   o Other tag commands are available too.

     <control-T>	- Return to the most recent tag context.
     ":tagpop"		- Pop to the specified tag in the tags stack.
     ":tagtop"		- Pop to the top tag in the tags stack.
     ":display tags"	- Display tags stack.

     Please read online manual.

2.4. Applied usage

   o In large project which include many main() function like MH,
     you can start vi like this.

	% vi -G -t main

     You can browse all commands sequentially.

   o When you want to check functions the name of which start with
     "set" or "get",

	% vi -G -t '^[sg]et'

     Of cause, following command is available too.

	:tag ^[sg]et

   o If your source files are on a read only device like CDROM, please do
     the followings.

	% mkdir /var/dbpath		<- directory for tag file
	% cd /cdrom/src			<- the root of source tree
	% gtags /var/dbpath		<- make tag files in /var/dbpath
	% setenv GTAGSROOT `pwd`
	% setenv GTAGSDBPATH /var/dbpath
	% vi -G -t main

   o If you want to treat the references to the function that is not defined
     in the source tree like library functions or system calls,
     do the followings.
     
	% cd /usr/src/lib
	% gtags				<- probably as a root
	% cd /usr/src/sys
	% gtags
	% setenv GTAGSLIBPATH /usr/src/lib:/usr/src/sys

     If you examine vi's source,

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

     You can start from vi and trip the whole unix world as if using
     hypertext.


3. Hypertext generator

3.1. Features

   o Htags makes hypertext from C source files.
   o Once the hypertext generated, you need nothing other than WWW browser.
   o You can move hypertext to anywhere. It is independent of the source code.
   o You can use all of your browser's functions, for example, search,
     history, bookmark, save, frame, windows and so on.

3.2. Preparation

   At first, you must prepare much disk space. Hypertext needs so much
   disk space. For example, the source code of FreeBSD kernel needs the
   following disk space.

	source code(/usr/src/sys)		14MB
	tag database(GTAGS,GRTAGS)		 9MB(!)
	hypertext(HTML/*)			45MB(!!!)

   Please do the followings.

	(at your source directory)
	% gtags				<- make tag database
	% htags				<- make hypertext

   Then you will find 'HTML' directory in the current directory.

3.3. Usage

   Please start a web browser like this. 

	% lynx HTML/index.html

   You can use any browsers, for example, Lynx, Chimera, Mosaic,
   Netscape Navigator, Internet Explorer and so on. But some browsers
   cannot treat framed index. Then select '[no frame version is here]'.

   You will understand the usage for the looking.
   You can move HTML directory to anywhere. It is independent of
   the source code.

3.4. To make hypertext of kernel

   If you would like to make hypertext of FreeBSD kernel source,
   it is convenient to use systags script in this package.

	% cd /usr/src/sys
	% systags
   then

	% netscape HTML/index.html

   You can use following functions with systags.

	o input form for dynamic index.
	  (This reqires you to setup httpd server for CGI program.)
	o one level nested index.
	o browse assembler source file.

   Of course, you can use above functions without systags.
   Please see gtags(1), htags(1).


4. Extended emacs using global

4.1. Features

   Addition to the extended vi,

   o More intelligent to recongnize current token and its type.
   o Tag completion is available for input tag name.
   o Mouse event is supported.

4.2. Preparation

   First, do the preparation of global. (Please see "1.2. Preparation").

   Second, to use global from emacs, you need to load gtags.el file and
   execute gtags-mode function in it. There are some ways to do it.

   (a) Start emacs, load gtags.el and execute gtags-mode function.

   	% emacs
	
	|
	|J_:-----Mule: *scratch*       (Lisp Interaction)--L16--All----
	|M-x load-library[RET]
	+------------------------------------------------------

	|
	|J_:-----Mule: *scratch*       (Lisp Interaction)--L16--All----
	|Load library: gtags[RET]
	+------------------------------------------------------

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

   (b) Previously write autoload function to $HOME/.emacs file,
       start emacs and execute gtags-mode function.

	$HOME/.emacs
   	+------------------------------------------------------
   	|(autoload 'gtags-mode "gtags" "" t)

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

   (c) Previously write autoload function to $HOME/.emacs file and
       start emacs with -f option

        $HOME/.emacs
        +------------------------------------------------------
        |(autoload 'gtags-mode "gtags" "" t)

   	% emacs -f gtags-mode


   You must start emacs under the source tree described in "1.2. Preparation".

4.3. Basic usage

   It is resemble to the extended vi based nvi-1.34.

   o To go to func1, press 'ESC-t' and you can see a prompt in mini-buffer.
     Then input tag name.

	:tag func1			# ':tag ' is a prompt.
             ~~~~~
   o To go to referenced point of func1, press 'ESC-r'.

   	:rtag func1			# 'rtag ' is a prompt
              ~~~~~

   o Tag name completion is available.

   	:tag fu<TAB>

   	:tag func1			# 'nc1' is appended by emacs

   o If a number of functions 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 any emacs command and press [RETURN],
     and you can go to the tag's point. When you want to go to next or
     previous tag, you can return to 'GTAGS SELECT MODE' with <control-T>
     and reselect.

   o <control-]> command is available.

     If current token is a definition, it is identical to
     ":rtag <current token>[RETURN]", otherwise ":tag <current token>[RETURN]".
     (GLOBAL decides this intelligentlly, but may sometimes misunderstand.)

4.4. Applied usage

   o You can use perl's regular expression.

	:tag ^put_			# locate tags start with 'put_'.

   o If your source files are on a read only device like CDROM, please do
     the followings.

	% mkdir /var/dbpath		<- directory for tag file
	% cd /cdrom/src			<- the root of source tree
	% gtags /var/dbpath		<- make tag files in /var/dbpath
	% setenv GTAGSROOT `pwd`
	% setenv GTAGSDBPATH /var/dbpath
	% mule -f gtags-mode

   o If you want to treat the references to the function that is not defined
     in the source tree like library functions or system calls,
     do the followings.
     
	% cd /usr/src/lib
	% gtags				<- probably as a root
	% cd /usr/src/sys
	% gtags
	% setenv GTAGSLIBPATH /usr/src/lib:/usr/src/sys
	% mule -f gtags-mode

   o mouse command is avalable.

     If you use X version emacs, try this.
     (But xemacs doesn't work well. I don't know why.)

     Move mouse cursor to a function name and click center button. And you
     will go to function's definition or references depending on the context.
     In 'GTAGS SELECT MODE', move mouse cursor to a line and click center
     button.

     To return to the previous position, click right button.

Thank you for your reading of my poor english.
And of course, I'm grateful to all excellent tools (vi, emacs, perl, C, db,
mozilla ...) and its authors.
----------------------------------------------------------------------------
E-Mail: <shigio@@wafu.netgate.net>
WWW: <http://wafu.netgate.net/tama/unix/indexe.html>
	(You can find the latest version here.)
----------------------------------------------------------------------------
@


1.1
log
@Initial revision
@
text
@@


1.1.1.1
log
@Import global v2.0 as contributed software.  We will maintain it this
way, retiring the sources from usr.bin/global shortly.

Reviewed by: jdp
Discussed-with: obrien
@
text
@@


1.1.1.2
log
@Import of virgin Global v2_2_1 sources
@
text
@d6 1
a6 1
	@@=  F o r   a l l   h a c k e r s.    version 2.21
d12 1
a12 1
					Shigio Yamaguchi	11-Dec-97
a15 10
	----------------------------------------------------------
	Note:
		This version of GLOBAL makes 'GSYMS' tag file for
		searching symbols other than functions.
		(Try global(1) with -s option.)
		But the tag file is very large. If you hope not to
		make the file, please use gtags with -o (old) option.
		Htags(1) doesn't use 'GSYMS'.
	----------------------------------------------------------

a18 1

a42 1
		3.5. Gozilla
d67 1
a67 1
extended vi(1), gtags.el and gozilla(1).
d88 1
a88 1
   o Global can understand POSIX 1003.2 regular expression (extension).
d112 3
d165 1
a165 1
   You can use POSIX regular expression (extension).
a184 5
   -s option locates any symbols other than function.

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

d322 2
a323 2
   o Extended vi can understand POSIX regular expression (extension)
     as a tag name for search.
d491 3
a493 8
	source code(/usr/src/sys)	14.0MB

	GTAGS				 1.5MB
	GRTAGS				 8.0MB
	GSYMS				12.0MB
	HTML/				55MB(!!!)
	-------------------------------------------------
	total				77MB
d498 2
a499 2
	% gtags			<- make tag database(GTAGS,GRTAGS,GSYMS)
	% htags			<- make hypertext(HTML/)
a537 35
3.5. Gozilla

   If you use Netscape Navigator, you can control the browser from command
   line by gozilla(1).

	% gtags
	% htags
	% global -x fork
	fork              60 kern/kern_fork.c fork(p, uap, retval)
	% gozilla +60 kern/kern_fork.c
	%

   Then you can see the hypertext about fork function directly on Netscape
   Navigator. If the browser has not been loaded, gozilla loads it.

   If you use another browser like lynx, try this.

	% gozilla -b lynx +60 kern/kern_fork.c

	or

	% setenv BROWSER lynx
	% gozilla +60 kern/kern_fork.c

   You can send remote command to Netscape Navigator too. Try this.

	% gozilla -C pagedown
	% gozilla -C pageup

   The remote commands are undocumented, but you can see the hint in the
   resource file. (Netscape.ad file)

   NOTES:
   Netscape Navigator is a registered trademark of Netscape Communications
   Corporation in the United States and other countries.
a648 9
   o To go to any symbols other than function, try 'ESC-s'.

	Find symbol: lbolt
	             ~~~~~
   o To go to any strings other than symbol, try 'ESC-g'.

	Find pattern: Copyright
	              ~~~~~~~~~

d651 1
a651 1
   o You can use POSIX regular expression (extension).
@


1.1.1.3
log
@Global v2.24
@
text
@d6 1
a6 1
	@@=  F o r   a l l   h a c k e r s.
d12 1
a12 1
					Shigio Yamaguchi	20-Jan-98
d14 1
a14 2
		Copyright 1996, 1997, 1998
			Shigio Yamaguchi All right resereved.
@


1.1.1.4
log
@Import Global v3_4_2 sources.

Ok'd by: peter
Discussed with: msmith
@
text
@d2 24
a25 16
           @@@@@@@@@@@@@@=)))
         @@=)))    @@=)))                             @@=)))
        @@=)))                                       @@=)))
        @@=)))         @@=))) @@@@@@@@@@=)@@@@@@@@@@@@=)))  @@@@=) @@=)))
        @@=))F o r   a l l)) h a c k e r s.))) @@=@@=))@@=)))
        @@=)))  @@@@@@@@@@@@=@@=)))@@=))) @@=)@@@@@@@@@@=)))@@= @@=))@@=)))
        @@=)))     @@=))@@=)))@@=))) @@=)@@=)))@@=)@@@@@@@@@@=))@@=)))
         @@=)))    @@=))@@=)))@@=))) @@=)@@=)))@@=@@=)))@@=))@@=)))
          @@@@@@@@@@@@@@@@=)))@@@@@@@@=)@@@@@@@@@@=)@@@@@@@@@@@@=@@@@@@=)@@@@@@@@=)@@@@@@@@@@@@=)))

					Shigio Yamaguchi	10-Dec-98

	Copyright 1996, 1997, 1998 Shigio Yamaguchi All right resereved.

GLOBAL is a source code tag system that works the same way across diverse
environments. It supports C, Yacc and Java source code.
d27 1
d42 1
a42 1
		2. Extended nvi using global
d49 1
a49 1
		3. Extended emacs using global
d53 3
a55 2
		3.3. Basic usage
		3.4. Applied usage
d57 1
a57 1
		4. Hypertext generator
d61 2
a62 17
		4.3. Usage
		4.4. Making hypertext of the kernel
		4.5. Gozilla

		5. Elvis using global

		5.1. Features
		5.2. Preparation
		5.3. Basic usage
		5.4. Applied usage

		A. Other topics

		A.1. How to plug in a parser
		A.2. How to use compact format
		A.3. Incremental updating
		A.4. Plans for the furture
d67 11
a77 2
GLOBAL is a source code tag system that works the same way across diverse
environments. Currently, it supports the following:
d79 2
a80 10
   o Shell command line(see '1. Global')
   o nvi editor(see '2. Extended nvi using global')
   o emacs editor(see '3. Emacs using global')
   o Web browser(see '4. Hypertext generator')
   o Elvis editor(see '5. Elvis using global')

Supported languages are C/Yacc and Java.
You can locate a specified function 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, like MH, X or BSD kernel.
d82 1
a82 2
GLOBAL consists of global(1), gtags(1), btreeop(1), gctags(1), htags(1),
extended nvi(1), gtags.el and gozilla(1).
d84 2
a85 1
	* 'extended' means being entended for GLOBAL.
d87 2
a88 2
	* Btreeop and gctags are used internally, so you do not need to
	  understand them.
d96 8
a103 13
   o Global can find the locations of a specified object quickly.
   o Global can locate not only object definitions but also object references.
   o Global allows duplicate objects.
   o Global can treat a source tree containing subdirectories as a logical
     scope.  You can get the relative path of objects from anywhere within
     that scope.
   o Global allows duplicate objects.
   o Global can understand POSIX 1003.2 regular expressions.
   o Global can search not only in a source tree but also in library paths.
   o Tag files are indepent of machine architecture.
   o Global can use a plugged in parser with the global.conf
     (or $HOME/.globalrc).
   o Global can use a tag file in a compact format to save disk space.
d106 1
a106 2
   subdirectories, many '#ifdef' and many main() functions like MH, mozilla,
   X and kernels.
d111 1
a111 1
   For example, if you want to browse vi's source code:
d117 1
a117 1
   three databases at the root of the source tree.
d120 1
a120 1
	GRTAGS  GTAGS   GSYMS
d122 2
a123 3
	GTAGS	- database of function definitions
	GRTAGS	- database of function references
	GSYMS	- database of other symbols
d128 1
a128 1
   Consider the following source tree:
d157 2
a158 3
   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.
d170 1
a170 1
   The -r option locates function references.
d175 1
a175 1
   You can use POSIX regular expressions.
d182 1
a182 2
   The -x option shows the details. It is similar to the -x option
   in ctags(1).
d190 1
a190 1
   The -a option produces the absolute path name.
d195 1
a195 1
   The -s command locates any symbols other than functions.
d200 1
a200 8
   The -g command locates any patterns including symbols.
   It is similar to grep(1).

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

   You can edit all files that include a specified function by typing
   one command, for example:
d224 2
a225 2
   When you are in the version1.0 directory, global will only locate functions
   that are in version1.0.
d231 2
a232 2
   When you are in the version2.0, global will only locate functions that
   are in version2.0.
d238 2
a239 2
   If you are at ROOT/, or you set the GTAGSROOT environment variable to ROOT,
   then global will locate functions in both directories.
d249 3
a251 3
   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:
d262 3
a264 4
   If you want all references to a function 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.
d266 1
a266 1
   If GTAGS is not found in a directory, global ignores that directory.
d284 2
a285 2
	Of course, the user program does not call kernel functions directly,
	but at least it is useful.
d289 1
a289 1
   If you forget a function name, you can use the -c (complete) command.
d303 1
a303 1
   You can use the -c command with tcsh's complete command.
d314 1
a314 1
		* <TAB> means the tab key or Ctrl-I.
d318 1
a318 1
   If you want to browse many files in order, do the following:
d330 1
a330 1
2. Extended nvi using global
d334 1
a334 1
   o The tag function of extended vi can locate not only function definitions
d336 5
a340 5
   o Extended nvi allows duplicate tag entries.
   o Extended nvi can understand POSIX regular expressions
     as a tag name for the search.
   o Extended nvi is completely backward-compatible with the original nvi.
     The above functions are available only in 'gtags mode'.
d347 1
a347 1
   There are several ways to do this:
d361 1
a361 1
   (c) Write the above set command to the .exrc or .nexrc file and start vi
d375 2
a376 2
     It seemes the same as original vi, but extended vi use GTAGS instead of
     tags.
d378 1
a378 1
   o To go to the referenced point of func1, add the prefix 'r'
d382 30
a411 1
     Extended nvi use GRTAGS.
d413 4
a416 2
   o If a number of functions are located, extended vi goes to the first tag.
     You can go to next tag by typing ':tagnext' and back by typing ':tagprev'.
d423 5
d430 2
a431 3
     In gtags mode, if you are in the first column of a line,
     it is equivalent to ":rtag <current token>", otherwise it is equivalent
     to ":tag <current token>".
d433 1
a433 1
   o Other tag commands are also available:
d436 3
a438 3
     ":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.
d440 1
a440 1
     Please read the online manual.
d444 2
a445 2
   o In large projects that include many main() function like MH,
     you can start vi like this:
d451 2
a452 2
   o When you want to check functions the name of which start with "set"
     or "get", use:
d456 1
a456 1
     Of course, the following command is also available:
d460 2
a461 2
   o If your source files are on a read only device like a CD-ROM, please do
     the following:
d463 2
a464 2
	% mkdir /var/dbpath		<- directory for the tag file
	% cd /cdrom/src			<- the root of the source tree
d470 4
a473 4
   o If you want all references to function that are not defined in the source
     tree to be treated as references to library functions or as system calls,
     do the following:

d486 3
a488 2
     You can start from vi and browse the whole unix world as if you were
     using hypertext.
d490 1
a490 1
3. Extended emacs using global
d494 104
d600 1
a600 1
   o More intelligent recognition of the current token and its type.
d602 1
a602 2
   o Symbol search and pattern search are available.
   o Mouse events are supported.
d604 1
a604 1
3.2. Preparation
d608 2
a609 3
   Second, to use global from emacs, you need to load the gtags.el file
   and execute gtags-mode function in it. There are several ways to
   do this:
d630 2
a631 2
   (b) Write the autoload function to the $HOME/.emacs file, start emacs
       and execute the gtags-mode function.
d644 2
a645 3
   (c) Write the autoload function to the $HOME/.emacs file and start emacs
       with the -f option.

d653 1
d656 3
a658 1
3.3. Basic usage
d661 1
a661 1
     Then input the tag name.
d665 1
a665 1
   o To go to a point that references func1, press 'ESC-r'.
d676 2
a677 2
   o If a number of functions are located, emacs goes into 'GTAGS SELECT MODE'
     like this:
d693 3
a695 3
     You can select a tag line by using any emacs command and pressing [RETURN],
     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 <control-T>
d700 2
a701 3
     If current token is a definition, it is equivalent to
     ":rtag <current token>[RETURN]", otherwise it is equivalent to
     ":tag <current token>[RETURN]".
d708 1
a708 1
   o To go to any strings other than symbols, try 'ESC-g'.
d713 1
a713 1
3.4. Applied usage
d715 1
a715 1
   o You can use POSIX regular expressions.
d719 2
a720 2
   o If your source files are on a read-only device like a CDROM, please do
     the following:
d722 2
a723 2
	% mkdir /var/dbpath		<- directory for the tag file
	% cd /cdrom/src			<- the root of the source tree
d727 1
a727 1
	% emacs -f gtags-mode
d729 3
a731 3
   o If you want all references to functions that are not defined in the
     source tree to be treated as references to library functions or
     as system calls, do the following:
d738 1
a738 319
	% emacs -f gtags-mode

   o Mouse command is avalable.

     If you use X version emacs, try the following
     (but it doesn't work well in xemacs; I don't know why).

     Move the mouse cursor to a function name and click the middle button.
     You will then go to the function'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.

4. Hypertext generator

4.1. Features

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

4.2. 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:

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

	GTAGS				 1.5MB
	GRTAGS				 8.0MB
	GSYMS				12.0MB
	HTML/				55MB(!!!)
	-------------------------------------------------
	total				77MB

   Please do the following:

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

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

4.4. Making hypertext of the kernel

   If you would like to make hypertext of the FreeBSD kernel source, it is
   convenient to use the systags script in this package.

	% cd /usr/src/sys
	% systags
   then

	% netscape HTML/index.html

   You can use following functions with systags:

	o An input form for a dynamic index.
	  (this reqires you to set up an httpd server for the CGI program.)
	o Unlimited nested index.

   Of course, you can use the above functions without systags. Please
   see gtags(1) and htags(1).

4.5. Gozilla

   If you use Netscape Navigator, you can control the browser from the command
   line by using gozilla(1).

	% gtags
	% htags
	% global -x fork
	fork              60 kern/kern_fork.c fork(p, uap, retval)
	% gozilla +60 kern/kern_fork.c
	%

   Then you can see the hypertext specified around the fork function directly
   on Netscape Navigator. If the browser has not been loaded, gozilla loads it.

   If you use another browser like lynx, try this:

	% gozilla -b lynx +60 kern/kern_fork.c

	or

	% setenv BROWSER lynx
	% gozilla +60 kern/kern_fork.c

   You can send a remote command to Netscape Navigator too. Try this:

	% gozilla -C pagedown
	% gozilla -C pageup

   The remote commands are undocumented, but you can see the hint in the
   resource file (Netscape.ad).

   NOTES:
   Netscape Navigator is a registered trademark of Netscape Communications
   Corporation in the United States and other countries.


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

5.1. Features

   o The tag function of elvis+GLOBAL can locate not only function definitions
     but also function references.
   o Elvis+GLOBAL allows duplicate tag entries.
   o Elvis+GLOBAL can understand POSIX regular expressions
     as a tag name for the search.
   o Symbol search and pattern search are available.
   o Mouse events are supported.

5.2. Preparation

   First, do the preparation of global. (Please see "1.2. Preparation").

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

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

5.3. Basic usage

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

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

	:tag -r func1

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

   o To go to any symbols other than function, try this.

	:tag -s lbolt

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

	:tag -g Copyright

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

   o To get list of functions in a file, use -f command.

	:browse -f main.c		# locate functions in main.c.

   o Other tag commands are also available:

	<control-]>	- go to the definition of current token.
	<control-T>     - return to the most recent tag context.
	":tag"		- without argment, 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.

5.4. Applied usage

   o You can use POSIX regular expressions.

	:tag ^put_			# locate functions start with 'put_'.

	:browse -g 'fseek(.*L_SET)'	# locate fseek() using L_SET argment.

   o You can browse functions list of many files.

	:browse -f *.c			# locate functions in *.c.

   o You can browse project files which includs specified pattern.

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

   o 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 function name and double click on the
      left button and you can go to the point that the function is defined.
      To come back, double click on the right button.

A. Other topics

A.1. How to plug in a parser

   You can use a plugged-in parser. Copy global.conf to /etc/global.conf
   or $HOME/.globalrc.

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

	% cd /<emacs source directory>/lib-src
	% make ctags
	# cp ctags /usr/local/bin/ctags-emacs
	% setenv GTAGSLABEL ctags-emacs		<- see global.conf
	% gtags
	% ls G*
	GPATH   GTAGS

   Or 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
	% setenv GTAGSLABEL ctags-exuberant	<- see global.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 gctags(1) does.
   All plugged-in parsers 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 argment path name.
	[4] line image

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

A.2. Compact format.

   You can save disk space with the compact format. The compact format
   needs source files.

   o To specify the use of the compact format on the command line,
     add the -c option:

	% gtags -c

   o To specify the use of the compact format in the configuration file:

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

   o If you will publish hypertext generated by htags then use the -c option
     of htags too:

        % htags -c

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


   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%

A.3. Incremental updating

   Modifying some source files, you need not remake whole tag files.
   Instead, you can use incremental updating facility (-i option).
d740 1
a740 18
        % gtags
	% cd kern
        % vi tty.c                              # modify tty.c.
        ...
        :wq
        % global -vi                            # -v means verbose.
        [Sun Dec  6 16:27:47 JST 1998] Gtags started
         Tag found in '/usr/src/sys'.
         Incremental update.
         Updating tags of 'kern/tty.c' ...GTAGS..GRTAGS..GSYMS.. Done.
         Global databases have been modified.
        [Sun Dec  6 16:28:30 JST 1998] Done.
        % global -vi                            # 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.
d742 2
a743 1
A.4. Plans for the furture
d745 4
a748 1
   Please see GLOBAL home page.
d750 1
a750 1
	<http://wafu.netgate.net/tama/unix/global.html>
d752 3
a754 3
Thank you for your reading.
And of course, I'm also grateful to all excellent tools (vi, ctags, emacs,
perl, C, db, mozilla ...) and its authors.
@


1.1.1.4.6.1
log
@MFC: Remove GLOBAL -- it has moved to Ports.
@
text
@@


1.1.1.3.2.1
log
@global v2.24 from -current
@
text
@@
