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

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