___________________________________
|      |  |  |     |  _  |     |  |
|  |___|  |  |  |  |    _|  |  |  |    GNU GLOBAL source code tag system
|  |   |  |  |  |  |     |     |  |
|  ~~  |   ~~|     |  ~  |  |  |   ~~|          for all hackers.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Copyright (c) 2000, 2003 Tama Communications Corporation

 This file is free software; as a special exception the author gives
 unlimited permission to copy and/or distribute it, with or without
 modifications, as long as this notice is preserved.

 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

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

Frequentry Asked Questions about GLOBAL.

----------------------------------------------------------------------------
Q1. Htags(1) aborts by short of memory. Why? Any workaround?

	% htags
	Out of memory!
	% _

A1. It seems that Perl4 and some Perl5 leaks memory.
    Please replace it with the latest Perl(currently 5.6.0) and retry.

    If it occurs with Perl-5.6.0 or later, please let me know.
----------------------------------------------------------------------------
Q2. GLOBAL skip some functions.
    For example, GLOBAL skip the function 'func' in this example.

	#define M(a)	static char *string = a;

	M(a)

	func() {		<= GLOBAL skip func().
		...
	}

A2. GLOBAL cannot recognize that pattern, because M(a) seems to be
    a function definition.

    It should be follows.

	#define M(a)	static char *string = a

	M(a);			<= end with ';'

	func() {
		...
	}

    Otherwise, you can tell gtags(1) that by listing the macros in
    '.notfunction' file in current directory.

	[.notfunction]
	+---------------
	|M
	|...

----------------------------------------------------------------------------
Q3. I have set up 'gtags.conf' to use emacs's ctags command with GLOBAL
    but I cannot use htags.

	% gtags
	% htags
	htags: GTAGS and GRTAGS not found. Please make them.
	% ls G*
	GPATH   GTAGS

A3. Emacs's ctags cannot locate function referencies. So, gtags cannot make
    GRTAGS tag file with it. With the result that you cannot use htags and
    global's -r option.

----------------------------------------------------------------------------
Q4. I have built GLOBAL in Windows 32 environment. But gtags(1) failed by sort
    command error.

A4. It seems that MS sort is executed. Please set your path so that unix
    sort will be executed.

----------------------------------------------------------------------------
Q5. I invoked gtags but it failed with a message like this:

	gctags: no input files specified

    What should I do?

A5. Please check what is the gctags? You can check it with this command like.

	% which gctags
	% gctags --version

    If the gctags is not the GLOBAL's one then you should set your PATH
    so that GLOBAL's gctags will be invoked.

----------------------------------------------------------------------------
Q6. It seems that gtags cannot treat files which include blanks in the path.
    Why?

A6. Because it is hard for GLOBAL to treat them correctly with keeping
    upper compatibility. If you can do it, please send the patch to me.

----------------------------------------------------------------------------
Q7. Gtags(1) and htags(1) works only on one directory. So, we cannot refer
    library functions like strlen from my project. Any solutions?

A7. In global(1), you can use GTAGSLIBPATH environment variable.

	[library]	/usr/src/lib
	[your project]	/usr/home/project

	% (cd /usr/src/lib; gtags)
	% setenv GTAGSLIBPATH /usr/src/lib
	% global strlen
	../../../usr/src/lib/libc/string/strlen.c

    In htags(1), you can do it by copying them into your source project.
    For example:

	% cd /usr/home/project
	% cp -r /usr/src/lib .
	% gtags
	% htags

----------------------------------------------------------------------------
Q8. I have updated operating system for my computer and have noticed that
    the speed of GLOBAL became very slow.

A8. Some operating system, for example Redhat9, is shipped with
    internationalized sort command. This reduces the performance of GLOBAL
    remarkably. Please obey one of the followings:

      1. Use C locale.
      2. Replace sort command with one which is not internationalized.

----------------------------------------------------------------------------
Q9. I'm running GLOBAL on Cygwin.
    When I ran htags, it returned the following message: 

        htags: cannot make cache file '/tmp/htagd79287565'.

    Any workaround?

A9. It seems that some Cygwin perl have a bug and the dbmopen() doesn't work
    on FAT file system. You can take the following workaround until Cygwin perl
    is fixed.
   
    With 'no_cache_file' variable set, htags doesn't use dbmopen() any longer.
    Instead, more memory might be requred for execution of htags.

        gtags.conf:
        +-----------------------------------------------------
        |
        |...
        |common:\
        |       :skip=GPATH,GTAGS,GRTAGS,GSYMS,HTML/,tags,...
        |       :format=standard:\
        |       :no_cache_file:                 <== ADD


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

Shigio Yamaguchi