code.delx.au - gnu-emacs-elpa/blob - 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 update Global's tag files when needed with tuning for
  17    large source trees.
  18 #. Build on ``compile.el`` for asynchronicity and its large
  19    feature-set.
  20 #. Intuitive navigation among multiple matches with mode-line display
  21    of current match, total matches and exit status.
  22 #. Manage Global's environment variables on a per-project basis.
  23 #. Support all Global search backends: ``grep``, ``idutils`` etc.
  24 #. Query replace.
  25 #. Highlight (definition) tag at point.
  26 #. Abbreviated display of file names.
  27 #. Support `exuberant ctags <http://ctags.sourceforge.net/>`_ backend.
  28 #. Support all Global's output formats: ``grep``, ``ctags-x``,
  29    ``cscope`` etc.
  30
  31 Why GNU Global
  32 ~~~~~~~~~~~~~~
  33
  34 The opengrok project composed a feature comparison `table
  35 <https://github.com/OpenGrok/OpenGrok/wiki/Comparison-with-Similar-Tools>`_
  36 between a few tools.
  37
  38 Screenshot
  39 ~~~~~~~~~~
  40
  41 .. figure:: http://i.imgur.com/lwED3aD.png
  42    :width: 500px
  43    :target: http://i.imgur.com/lwED3aD.png
  44    :alt: ggtags.png
  45
  46 Config
  47 ~~~~~~
  48
  49 Enable ``ggtags-mode`` for C/C++/Java modes::
  50
  51     (add-hook 'c-mode-common-hook
  52               (lambda ()
  53                 (when (derived-mode-p 'c-mode 'c++-mode 'java-mode)
  54                   (ggtags-mode 1))))
  55
  56 More languages/modes are supported if `GNU Global
  57 <http://www.gnu.org/software/global>`_ is compiled with
  58 ``--with-exuberant-ctags`` to support `exuberant ctags
  59 <http://ctags.sourceforge.net/>`_. Also set the environment variable
  60 ``GTAGSCONF`` to the correct location of ``gtags.conf``. For example::
  61
  62   export GTAGSCONF=/usr/local/share/gtags/gtags.conf
  63
  64 See ``plugin-factory/README`` in GNU Global source for further
  65 information.
  66
  67 Also see https://github.com/leoliu/ggtags/wiki for more examples.
  68
  69 Tutorial
  70 ~~~~~~~~
  71
  72 Type ``M-x ggtags-mode`` to enable the minor mode, or as usual enable
  73 it in your desired major mode hooks. When the mode is on the symbol at
  74 point is underlined if it is a valid (definition) tag.
  75
  76 ``M-.`` finds definitions or references according to the tag at point,
  77 i.e. if point is at a definition tag find references and vice versa.
  78 ``M-]`` finds references.
  79
  80 If multiple matches are found, navigation mode is entered, the
  81 mode-line lighter changed, and a navigation menu-bar entry presented.
  82 In this mode, ``M-n`` and ``M-p`` moves to next and previous match,
  83 ``M-}`` and ``M-{`` to next and previous file respectively. ``M-o``
  84 toggles between full and abbreviated displays of file names in the
  85 auxiliary popup window. When you locate the right match, press RET to
  86 finish which hides the auxiliary window and exits navigation mode. You
  87 can continue the search using ``M-,``. To abort the search press
  88 ``M-*``.
  89
  90 Normally after a few searches a dozen buffers are created visiting
  91 files tracked by GNU Global. ``C-c M-k`` helps clean them up.
  92
  93 Check the menu-bar entry ``Ggtags`` for other useful commands.
  94
  95 Development
  96 ~~~~~~~~~~~
  97
  98 The goal is to make working with GNU Global in Emacs as effortlessly
  99 and intuitively as possible.
 100
 101 Bugs
 102 ~~~~
 103
 104 https://github.com/leoliu/ggtags/issues