code.delx.au - gnu-emacs-elpa/blob - packages/ggtags/README.rst

   1 =========================
   2  Use GNU Global in Emacs
   3 =========================
   4
   5 A package for working with `GNU Global
   6 <http://www.gnu.org/software/global>`_ source tagging system in Emacs.
   7
   8 This package is part of `GNU ELPA <http://elpa.gnu.org>`_
   9 (``M-x list-packages``).
  10
  11 Patches, feature requests and bug reports are welcome. Thanks.
  12
  13 Features
  14 ~~~~~~~~
  15
  16 #. Automatically run ``global -u`` when needed
  17 #. Highlight valid tag at point
  18 #. Built on top of ``compile.el`` (asynchonrous and other nice
  19    features)
  20 #. Support `exuberant ctags <http://ctags.sourceforge.net/>`_ backend.
  21 #. Support all  output formats  of ``global``:  ``grep``, ``ctags-x``,
  22    ``cscope`` etc.
  23 #. Abbreviated display of file names
  24
  25 Why GNU Global
  26 ~~~~~~~~~~~~~~
  27
  28 The opengrok project composed a feature comparison `table
  29 <https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
  30 between a few tools.
  31
  32 Screenshot
  33 ~~~~~~~~~~
  34
  35 .. figure:: http://i.imgur.com/d430rmm.png
  36    :width: 500px
  37    :target: http://i.imgur.com/d430rmm.png
  38    :alt: ggtags.png
  39
  40 Config
  41 ~~~~~~
  42
  43 Enable ``ggtags-mode`` for C/C++/Java modes::
  44
  45     (add-hook 'c-mode-common-hook
  46               (lambda ()
  47                 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
  48                   (ggtags-mode 1))))
  49
  50 More languages/modes are supported if `GNU Global
  51 <http://www.gnu.org/software/global>`_ is compiled with
  52 ``--with-exuberant-ctags`` to support `exuberant ctags
  53 <http://ctags.sourceforge.net/>`_. Also set the environment variable
  54 ``GTAGSCONF`` to the correct location of ``gtags.conf``. For example::
  55
  56   export GTAGSCONF=/usr/local/share/gtags/gtags.conf
  57
  58 See ``plugin-factory/README`` in GNU Global source for further
  59 information.
  60
  61 Tutorial
  62 ~~~~~~~~
  63
  64 Type ``M-x ggtags-mode`` to enable the minor mode, or as usual enable
  65 it in your desired major mode hooks. When the mode is on the symbol at
  66 point is underlined if it is a valid (definition) tag.
  67
  68 ``M-.`` finds definitions or references according to the tag at point,
  69 i.e. if point is at a definition tag find references and vice versa.
  70 ``M-]`` finds references.
  71
  72 If multiple matches are found, navigation mode is entered, the
  73 mode-line lighter changed, and a navigation menu-bar entry
  74 presented. In this mode, ``M-n`` and ``M-p`` moves to next and
  75 previous match, ``M-}`` and ``M-{`` to next and previous file
  76 respectively. ``M-o`` toggles between full and abbreviated displays of
  77 file names in the auxiliary popup window. When you locate the right
  78 match, press RET to finish which hides the auxiliary window and exits
  79 navigation mode. You can resume the search using ``M-,``. To abort the
  80 search press ``M-*``.
  81
  82 Normally after a few searches a dozen buffers are created visiting
  83 files tracked by GNU Global. ``C-c M-k`` helps clean them up.
  84
  85 Check the menu-bar entry ``Ggtags`` for other useful commands.
  86
  87 Development
  88 ~~~~~~~~~~~
  89
  90 The goal is to make working with GNU Global in Emacs as effortlessly
  91 and intuitively as possible.
  92
  93 Bugs
  94 ~~~~
  95
  96 https://github.com/leoliu/ggtags/issues
  97
  98 known problems
  99 ++++++++++++++
 100
 101 When there is only one match a window is still popped up to be closed
 102 immediately due to a `bug <http://debbugs.gnu.org/13594>`_ in
 103 ``compile.el``.