spacemacs/layers/+tags/gtags/README.org

#+TITLE: Helm Gtags layer

* Table of Contents                                         :TOC_4_org:noexport:
 - [[Description][Description]]
 - [[Features][Features]]
 - [[Install][Install]]
   - [[GNU Global (gtags)][GNU Global (gtags)]]
     - [[Install on OSX using Homebrew][Install on OSX using Homebrew]]
     - [[Install on *nix from source][Install on *nix from source]]
       - [[Install recommended dependencies][Install recommended dependencies]]
       - [[Install with recommended features][Install with recommended features]]
       - [[Configure your environment to use pygments and ctags][Configure your environment to use pygments and ctags]]
   - [[Emacs Configuration][Emacs Configuration]]
 - [[Usage][Usage]]
     - [[Language Support][Language Support]]
       - [[Built-in languages][Built-in languages]]
       - [[Exuberant ctags languages][Exuberant ctags languages]]
       - [[Universal ctags languages][Universal ctags languages]]
       - [[Pygments languages (plus symbol and reference tags)][Pygments languages (plus symbol and reference tags)]]
   - [[Eldoc integration][Eldoc integration]]
 - [[Key bindings][Key bindings]]

* Description

 =helm-gtags= and =ggtags= are clients for GNU Global. GNU Global is a source
  code tagging system that allows querying symbol locations in source code, such
  as definitions or references. Adding the =gtags= layer enables both of these modes.

* Features

  - Select any tag in a project retrieves by gtags
  - Resume previous helm-gtags session
  - Jump to a location based on context
  - Find definitions
  - Find references
  - Present tags in current function only
  - Create a tag database
  - Jump to definitions in file
  - Show stack of visited locations
  - Manually update tag database
  - Jump to next location in context stack
  - Jump to previous location in context stack
  - Jump to a file in tag database
  - Enables =eldoc= in modes that otherwise might not support it.
  - Enables =company complete= in modes that otherwise might not support it.

* Install

** GNU Global (gtags)

   To use =gtags=, you first have to install [[https://www.gnu.org/software/global/download.html][GNU Global]].

   You can install =global= from the software repository of your OS; however,
   many OS distributions are out of date, and you will probably be missing
   support for =pygments= and =exuberant ctags=, and thus support for many
   languages. We recommend installing from source. If not for example to install
   on Ubuntu:

   #+begin_src sh
     sudo apt-get install global
   #+end_src

*** Install on OSX using Homebrew

    #+begin_src sh options
      brew install global --with-pygments --with-ctags
    #+end_src

*** Install on *nix from source

**** Install recommended dependencies

    To take full advantage of global you should install 2 extra packages in
    addition to global: pygments and ctags (exuberant). You can do this using
    your normal OS package manager, e.g., on Ubuntu

    #+BEGIN_SRC sh
      sudo apt-get install exuberant-ctags python-pygments
    #+END_SRC

    or e.g., Archlinux:

    #+BEGIN_SRC sh
      sudo pacman -S ctags python-pygments
    #+END_SRC

**** Install with recommended features

    Download the latest tar.gz archive, then run these commands:

    #+BEGIN_SRC sh
      tar xvf global-6.5.3.tar.gz
      cd global-6.5.3
      ./configure --with-exuberant-ctags=/usr/bin/ctags
      make
      sudo make install
    #+END_SRC

**** Configure your environment to use pygments and ctags

    To be able to use =pygments= and =ctags=, you need to copy the sample
 =gtags.conf= either to =/etc/gtags.conf= or =$HOME/.globalrc=. For example:

    #+begin_src sh
      cp gtags.conf ~/.globalrc
    #+end_src

    Additionally you should define GTAGSLABEL in your shell startup file e.g.
    with sh/ksh:

    #+begin_src sh
      echo export GTAGSLABEL=pygments >> .profile
    #+end_src

** Emacs Configuration

    To use this configuration layer, add it to your =~/.spacemacs=. You
    will need to add =gtags= to the existing =dotspacemacs-configuration-layers=.

    #+begin_src emacs-lisp
      (setq dotspacemacs-configuration-layers
            '( ;; ...
              gtags
               ;; ...
              ))
    #+end_src

* Usage

  Before using the =gtags=, remember to create a GTAGS database by the following
  methods:

  - From within Emacs, runs the command =helm-gtags-create-tags=, which is bound
    to ~SPC m g c~. If the language is not directly supported by GNU Global, you
    can choose =ctags= or =pygments= as a backend to generate tag database.

  - From inside terminal, runs gtags at your project root in terminal:

  #+BEGIN_SRC sh
    cd /path/to/project/root
    gtags
  #+END_SRC

  If the language is not directly supported by =gtags=, and you have not set the
  GTAGSLABEL environment variable, use this command instead:

  #+BEGIN_SRC sh
    gtags --gtagslabel=pygments
  #+END_SRC

*** Language Support

**** Built-in languages

     If you do not have =ctags= or =pygments= enabled gtags will only produce
     tags for the following languages:

     - asm
     - c/c++
     - java
     - php
     - yacc
     -
**** Exuberant ctags languages

     If you have enabled =exuberant ctags= and use that as the backend (i.e.,
     GTAGSLABEL=ctags or --gtagslabel=ctags) the following additional languages
     will have tags created for them:

     - c#
     - erlang
     - javascript
     - common-lisp
     - emacs-lisp
     - lua
     - ocaml
     - python
     - ruby
     - scheme
     - vimscript
     - windows-scripts (.bat .cmd files)

**** Universal ctags languages

     If instead you installed you the newer/beta =universal ctags= and use that
     as the backend (i.e., GTAGSLABEL=ctags or --gtagslabel=ctags) the following
     additional languages will have tags created for them:

     - clojure
     - d
     - go
     - rust

**** Pygments languages (plus symbol and reference tags)

     In order to look up symbol references for any language not in the built in
     parser you must use the pygments backend. When this backend is used global
     actually uses both ctags and pygments to find the definitions and uses of
     functions and variables as well as "other symbols".

     If you enabled pygments (the best choice) and use that as the backend (i.e.,
     GTAGSLABEL=pygments or --gtagslabel=pygments) the following additional
     languages will have tags created for them:

     - exlixir
     - fsharp
     - haskell
     - octave
     - racket
     - scala
     - shell-scripts
     - tex

** Eldoc integration

   This layer also integrates =ggtags= for its Eldoc feature. That means, when
   writing code, you can look at the minibuffer (at the bottom) and see variable
   and function definition of the symbol the cursor is on. However, this feature is
   only activated for programming modes that are not one of these languages:

   - C mode
   - C++ mode
   - Common Lisp
   - Emacs Lisp
   - Python
   - Ruby-mode

   Since these modes have better Eldoc integration already.

   In addition, if output from =compile= (bound to ~SPC c C~), =shell-command=
   (bound to ~SPC !~ and ~M-!~) or =async-shell-command= (bound to ~M-&~) commands
   contains symbol in your project, you move cursor on such symbol and use any of
   the gtags commands.

* Key bindings

| Key Binding | Description                                               |
|-------------+-----------------------------------------------------------|
| ~SPC m g c~ | create a tag database                                     |
| ~SPC m g f~ | jump to a file in tag database                            |
| ~SPC m g g~ | jump to a location based on context                       |
| ~SPC m g G~ | jump to a location based on context (open another window) |
| ~SPC m g d~ | find definitions                                          |
| ~SPC m g i~ | present tags in current function only                     |
| ~SPC m g l~ | jump to definitions in file                               |
| ~SPC m g n~ | jump to next location in context stack                    |
| ~SPC m g p~ | jump to previous location in context stack                |
| ~SPC m g r~ | find references                                           |
| ~SPC m g R~ | resume previous helm-gtags session                        |
| ~SPC m g s~ | select any tag in a project retrieved by gtags            |
| ~SPC m g S~ | show stack of visited locations                           |
| ~SPC m g u~ | manually update tag database                              |