2015-12-02 14:23:39 +00:00
|
|
|
|
#+TITLE: Helm Gtags layer
|
2016-03-31 02:59:55 +00:00
|
|
|
|
|
2018-09-19 03:54:47 +00:00
|
|
|
|
* Table of Contents :TOC_4_gh:noexport:
|
2017-05-22 14:16:12 +00:00
|
|
|
|
- [[#description][Description]]
|
2017-08-28 21:58:10 +00:00
|
|
|
|
- [[#features][Features:]]
|
2017-05-22 14:16:12 +00:00
|
|
|
|
- [[#install][Install]]
|
|
|
|
|
- [[#gnu-global-gtags][GNU Global (gtags)]]
|
2018-08-18 21:18:47 +00:00
|
|
|
|
- [[#install-on-ubuntu][Install on Ubuntu]]
|
2017-05-22 14:16:12 +00:00
|
|
|
|
- [[#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]]
|
|
|
|
|
- [[#conflict-between-ctags-and-emacss-etags-binary][Conflict between =ctags= and emacs's =etags= binary]]
|
|
|
|
|
- [[#emacs-configuration][Emacs Configuration]]
|
|
|
|
|
- [[#disabling-by-default][Disabling by default]]
|
|
|
|
|
- [[#usage][Usage]]
|
2017-12-31 00:39:19 +00:00
|
|
|
|
- [[#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)]]
|
2017-05-22 14:16:12 +00:00
|
|
|
|
- [[#eldoc-integration][Eldoc integration]]
|
|
|
|
|
- [[#key-bindings][Key bindings]]
|
2017-08-26 21:18:09 +00:00
|
|
|
|
- [[#helm][Helm]]
|
|
|
|
|
- [[#ivy][Ivy]]
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
|
|
|
|
* Description
|
2017-08-26 21:18:09 +00:00
|
|
|
|
=counsel-gtags=, =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.
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2017-08-28 21:58:10 +00:00
|
|
|
|
** Features:
|
2016-07-17 15:36:07 +00:00
|
|
|
|
- Select any tag in a project retrieved 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.
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
|
|
|
|
* Install
|
2016-04-05 04:08:34 +00:00
|
|
|
|
** GNU Global (gtags)
|
2016-07-17 15:36:07 +00:00
|
|
|
|
To use gtags, you first have to install [[https://www.gnu.org/software/global/download.html][GNU Global]].
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2016-07-17 15:36:07 +00:00
|
|
|
|
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
|
2018-08-18 21:18:47 +00:00
|
|
|
|
recommend installing from source.
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2018-08-18 21:18:47 +00:00
|
|
|
|
*** Install on Ubuntu
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
2016-07-17 15:36:07 +00:00
|
|
|
|
sudo apt-get install global
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+END_SRC
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2016-04-05 04:08:34 +00:00
|
|
|
|
*** Install on OSX using Homebrew
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
2016-07-17 15:36:07 +00:00
|
|
|
|
brew install global --with-pygments --with-ctags
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+END_SRC
|
2015-06-24 04:40:30 +00:00
|
|
|
|
|
2016-04-05 04:08:34 +00:00
|
|
|
|
*** Install on *nix from source
|
|
|
|
|
**** Install recommended dependencies
|
2016-07-17 15:36:07 +00:00
|
|
|
|
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
|
2018-08-18 21:18:47 +00:00
|
|
|
|
your normal OS package manager, e.g. on Ubuntu
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2016-07-17 15:36:07 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
|
|
|
|
sudo apt-get install exuberant-ctags python-pygments
|
|
|
|
|
#+END_SRC
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2018-08-18 21:18:47 +00:00
|
|
|
|
or e.g. Archlinux:
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2016-07-17 15:36:07 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
|
|
|
|
sudo pacman -S ctags python-pygments
|
|
|
|
|
#+END_SRC
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
|
|
|
|
**** Install with recommended features
|
2016-07-17 15:36:07 +00:00
|
|
|
|
Download the latest tar.gz archive, then run these commands:
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2016-07-17 15:36:07 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
2018-08-18 21:18:47 +00:00
|
|
|
|
tar xvf global-<version>.tar.gz
|
|
|
|
|
cd global-<version>
|
2016-07-17 15:36:07 +00:00
|
|
|
|
./configure --with-exuberant-ctags=/usr/bin/ctags
|
|
|
|
|
make
|
|
|
|
|
sudo make install
|
|
|
|
|
#+END_SRC
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2016-04-05 04:08:34 +00:00
|
|
|
|
**** Configure your environment to use pygments and ctags
|
2016-07-17 15:36:07 +00:00
|
|
|
|
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:
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
2016-07-17 15:36:07 +00:00
|
|
|
|
cp gtags.conf ~/.globalrc
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+END_SRC
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2016-07-17 15:36:07 +00:00
|
|
|
|
Additionally you should define GTAGSLABEL in your shell startup file e.g.
|
|
|
|
|
with sh/ksh:
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
2016-07-17 15:36:07 +00:00
|
|
|
|
echo export GTAGSLABEL=pygments >> .profile
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+END_SRC
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2018-08-18 21:18:47 +00:00
|
|
|
|
With fish:
|
|
|
|
|
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
2018-08-18 21:18:47 +00:00
|
|
|
|
echo export set -x GTAGSLABEL pygments >> ${HOME}/.config/fish/config.fish
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+END_SRC
|
2018-08-18 21:18:47 +00:00
|
|
|
|
|
2017-04-10 11:26:47 +00:00
|
|
|
|
*** Conflict between =ctags= and emacs's =etags= binary
|
|
|
|
|
If you installed =emacs= from source after =ctags=, your original =ctags= binary
|
2018-09-19 03:54:47 +00:00
|
|
|
|
is probably replaced by emacs’s =etags=. To get around this you will need to
|
2017-04-10 11:26:47 +00:00
|
|
|
|
configure =emacs= as following before installing:
|
|
|
|
|
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
2017-04-10 11:26:47 +00:00
|
|
|
|
./configure --program-transform-name='s/^ctags$/ctags.emacs/'
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+END_SRC
|
2017-04-10 11:26:47 +00:00
|
|
|
|
|
|
|
|
|
To check if you have the correct version of =ctags= execute:
|
|
|
|
|
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
2017-04-10 11:26:47 +00:00
|
|
|
|
ctags --version | grep Exuberant
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+END_SRC
|
2017-04-10 11:26:47 +00:00
|
|
|
|
|
2018-08-18 21:18:47 +00:00
|
|
|
|
If there is no output you have the wrong =ctags= executable and you need to
|
|
|
|
|
reinstall =ctags= from your package manager.
|
2017-04-10 11:26:47 +00:00
|
|
|
|
|
2016-04-05 04:08:34 +00:00
|
|
|
|
** Emacs Configuration
|
2018-08-18 21:18:47 +00:00
|
|
|
|
To use this configuration layer, add it to your =~/.spacemacs= file. You
|
2016-07-17 15:36:07 +00:00
|
|
|
|
will need to add =gtags= to the existing =dotspacemacs-configuration-layers=.
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
2016-07-17 15:36:07 +00:00
|
|
|
|
(setq dotspacemacs-configuration-layers
|
|
|
|
|
'( ;; ...
|
|
|
|
|
gtags
|
|
|
|
|
;; ...
|
|
|
|
|
))
|
2018-09-19 03:54:47 +00:00
|
|
|
|
#+END_SRC
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2016-08-15 19:24:44 +00:00
|
|
|
|
*** Disabling by default
|
|
|
|
|
If =ggtags-mode= is too intrusive you can disable it by default, by setting the
|
|
|
|
|
layer variable =gtags-enable-by-default= to =nil=.
|
|
|
|
|
|
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
|
|
|
(setq-default dotspacemacs-configuration-layers
|
|
|
|
|
'((gtags :variables gtags-enable-by-default t)))
|
|
|
|
|
#+END_SRC
|
|
|
|
|
|
|
|
|
|
This variable can also be set as a file-local or directory-local variable for
|
2018-08-18 21:18:47 +00:00
|
|
|
|
additional control on a per project basis.
|
2016-08-15 19:24:44 +00:00
|
|
|
|
|
2016-04-05 04:08:34 +00:00
|
|
|
|
* Usage
|
2018-08-18 21:18:47 +00:00
|
|
|
|
Before using =gtags=, remember to create a GTAGS database by one of the following
|
2016-07-17 15:36:07 +00:00
|
|
|
|
methods:
|
2017-08-26 21:18:09 +00:00
|
|
|
|
- From within Emacs, run either =counsel-gtags-create-tags= or
|
|
|
|
|
=helm-gtags-create-tags=, which are bound to ~SPC m g c~. If the language is
|
|
|
|
|
not directly supported by GNU Global, you can choose =ctags= or =pygments= as
|
2018-08-18 21:18:47 +00:00
|
|
|
|
a backend to generate the database.
|
|
|
|
|
- From inside a terminal:
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2016-07-17 15:36:07 +00:00
|
|
|
|
#+BEGIN_SRC sh
|
|
|
|
|
cd /path/to/project/root
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2018-08-18 21:18:47 +00:00
|
|
|
|
# If the language is not directly supported and GTAGSLABEL is not set
|
2016-07-17 15:36:07 +00:00
|
|
|
|
gtags --gtagslabel=pygments
|
2018-08-18 21:18:47 +00:00
|
|
|
|
|
|
|
|
|
# Otherwise
|
|
|
|
|
gtags
|
2016-07-17 15:36:07 +00:00
|
|
|
|
#+END_SRC
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2017-12-31 00:39:19 +00:00
|
|
|
|
** Language Support
|
|
|
|
|
*** Built-in languages
|
2016-07-17 15:36:07 +00:00
|
|
|
|
If you do not have =ctags= or =pygments= enabled gtags will only produce
|
|
|
|
|
tags for the following languages:
|
|
|
|
|
- asm
|
|
|
|
|
- c/c++
|
|
|
|
|
- java
|
|
|
|
|
- php
|
|
|
|
|
- yacc
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2017-12-31 00:39:19 +00:00
|
|
|
|
*** Exuberant ctags languages
|
2018-08-18 21:18:47 +00:00
|
|
|
|
If you have enabled =exuberant ctags= and use that as the backend
|
|
|
|
|
(i.e. =GTAGSLABEL=ctags= or =--gtagslabel=ctags=) the following additional languages
|
|
|
|
|
are supported:
|
2016-07-17 15:36:07 +00:00
|
|
|
|
- c#
|
|
|
|
|
- erlang
|
|
|
|
|
- javascript
|
|
|
|
|
- common-lisp
|
|
|
|
|
- emacs-lisp
|
|
|
|
|
- lua
|
|
|
|
|
- ocaml
|
|
|
|
|
- python
|
|
|
|
|
- ruby
|
|
|
|
|
- scheme
|
|
|
|
|
- vimscript
|
|
|
|
|
- windows-scripts (.bat .cmd files)
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2017-12-31 00:39:19 +00:00
|
|
|
|
*** Universal ctags languages
|
2018-08-18 21:18:47 +00:00
|
|
|
|
If you have installed [[https://github.com/universal-ctags/ctags][universal ctags]] and use that as the backend
|
|
|
|
|
(i.e. GTAGSLABEL=ctags or --gtagslabel=ctags) the following additional
|
|
|
|
|
languages are supported:
|
2016-07-17 15:36:07 +00:00
|
|
|
|
- clojure
|
|
|
|
|
- d
|
|
|
|
|
- go
|
|
|
|
|
- rust
|
2016-04-05 04:08:34 +00:00
|
|
|
|
|
2017-12-31 00:39:19 +00:00
|
|
|
|
*** Pygments languages (plus symbol and reference tags)
|
2016-07-17 15:36:07 +00:00
|
|
|
|
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
|
2018-09-19 03:54:47 +00:00
|
|
|
|
functions and variables as well as “other symbols”.
|
2016-07-17 15:36:07 +00:00
|
|
|
|
|
2018-08-18 21:18:47 +00:00
|
|
|
|
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 be supported:
|
2016-07-17 15:36:07 +00:00
|
|
|
|
- elixir
|
|
|
|
|
- fsharp
|
|
|
|
|
- haskell
|
|
|
|
|
- octave
|
|
|
|
|
- racket
|
|
|
|
|
- scala
|
|
|
|
|
- shell-scripts
|
|
|
|
|
- tex
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
|
|
|
|
** Eldoc integration
|
2016-07-17 15:36:07 +00:00
|
|
|
|
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
|
2018-08-18 21:18:47 +00:00
|
|
|
|
and function definitions of the symbol under point. However, this feature is
|
|
|
|
|
only activated for languages which are not:
|
2016-07-17 15:36:07 +00:00
|
|
|
|
- C
|
|
|
|
|
- C++
|
|
|
|
|
- Common Lisp
|
|
|
|
|
- Emacs Lisp
|
|
|
|
|
- Python
|
|
|
|
|
- Ruby
|
|
|
|
|
|
|
|
|
|
Since these modes have better Eldoc integration already.
|
|
|
|
|
|
2018-08-18 21:18:47 +00:00
|
|
|
|
In addition =gtags= commands are also supported for symbols in the
|
|
|
|
|
=compile=, =shell-command= and =async-shell-command= buffers.
|
2015-06-10 16:44:30 +00:00
|
|
|
|
|
|
|
|
|
* Key bindings
|
|
|
|
|
|
2018-08-18 21:18:47 +00:00
|
|
|
|
| Key Binding | Description |
|
|
|
|
|
|-------------+--------------------------------------------------|
|
|
|
|
|
| ~g d~ | jump to definition or references of selected tag |
|
2017-08-26 21:18:09 +00:00
|
|
|
|
|
|
|
|
|
** Helm
|
|
|
|
|
|
2015-06-10 16:44:30 +00:00
|
|
|
|
| Key Binding | Description |
|
|
|
|
|
|-------------+-----------------------------------------------------------|
|
2017-03-31 02:00:21 +00:00
|
|
|
|
| ~SPC m g C~ | create a tag database |
|
2015-06-10 16:44:30 +00:00
|
|
|
|
| ~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 |
|
2017-05-11 15:47:45 +00:00
|
|
|
|
| ~SPC m g y~ | find symbols |
|
2015-06-10 16:44:30 +00:00
|
|
|
|
| ~SPC m g u~ | manually update tag database |
|
2017-08-26 21:18:09 +00:00
|
|
|
|
|
|
|
|
|
** Ivy
|
|
|
|
|
=counsel-gtags= is currently missing a few minor features compared to
|
|
|
|
|
=helm-gtags=.
|
|
|
|
|
|
|
|
|
|
| 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 d~ | find definitions |
|
|
|
|
|
| ~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 s~ | select any tag in a project retrieved by gtags |
|
|
|
|
|
| ~SPC m g y~ | find symbols |
|
|
|
|
|
| ~SPC m g u~ | manually update tag database |
|