ghc-tags

A command line tool that generates etags (Emacs) and ctags (Vim, VSCode with ctagsx etc.) for efficient code navigation (jump to definition).

Main features:

• Leverages GHC API to obtain accurate information.
• Uses multiple CPU cores when processing source files.
• Supports fast incremental updates.

Supported file extensions:

• .hs
• .hs-boot
• .lhs
• .x (requires alex)
• .hsc (requires hsc2hs)

Usage

For simple projects, i.e. the ones that don't use C pre-processor in non-trivial ways nor include any C sources it should be enough to execute ghc-tags -e (for etags) or ghc-tags -c (for ctags) in the root directory of the project.

For more complicated projects you need to create the configuration file (ghc-tags.yaml or .ghc-tags.yaml by default, the first one that exists is read and a warning is printed when both exist). It can contain the following keys:

• source_paths - a list of paths for ghc-tags to process. Directories are traversed recursively.
• exclude_paths - a list of paths for ghc-tags to exclude from processing.
• language - the flavour of Haskell, one of Haskell98, Haskell2010, GHC2021 or GHC2024.
• extensions - a list of GHC language extensions to enable when parsing. A No prefix disables the extension instead, e.g. NoStarIsType. Note that GHC needs much less extensions for parsing alone, so you should almost never need to override this.
• cpp_includes - include paths for the C pre-processor.
• cpp_options - other options for the C pre-processor, e.g. defines (usually undefined MIN_VERSION_x macros will go here).

If any of these keys is not specified, an appropriate default value will be picked instead. You can inspect the defaults by executing ghc-tags --default.

Note: it is possible to specify multiple project configurations in the configuration file by separating them with ---. For example, here is a configuration for GHC on Linux (the compiler, the boot libraries and haddock):

source_paths:
- compiler

cpp_includes:
- _build/stage1/compiler/build
- compiler

---

source_paths:
- libraries/base
- libraries/ghc-internal

exclude_paths:
- libraries/base/src/System/CPUTime/Javascript.hs
- libraries/base/src/System/CPUTime/Windows.hsc
- libraries/base/tests
- libraries/ghc-internal/src/GHC/Internal/Conc/POSIX/Const.hsc
- libraries/ghc-internal/src/GHC/Internal/Event/Windows.hsc
- libraries/ghc-internal/src/GHC/Internal/Event/Windows/ConsoleEvent.hsc
- libraries/ghc-internal/src/GHC/Internal/Event/Windows/FFI.hsc
- libraries/ghc-internal/src/GHC/Internal/IO/Windows/Handle.hsc
- libraries/ghc-internal/src/GHC/Internal/JS/Prim.hs

cpp_includes:
- _build/stage1/libraries/ghc-internal/build/include
- _build/stage1/rts/build/include
- libraries/ghc-internal/include
- rts/include

cpp_options:
- -DBIGNUM_GMP

---

source_paths:
- libraries/ghc-bignum

exclude_paths:
- libraries/ghc-bignum/src/GHC/Num/Backend/Selected.hs

cpp_includes:
- libraries/ghc-bignum/include

---

source_paths:
- libraries/ghc-boot
- libraries/ghc-boot-th
- libraries/ghc-compact
- libraries/ghc-experimental
- libraries/ghc-prim
- libraries/ghc-platform
- libraries/template-haskell

exclude_paths:
- libraries/ghc-compact/tests
- libraries/ghc-prim/tests

---

source_paths:
- libraries/ghc-heap

cpp_includes:
- _build/stage1/rts/build/include
- rts/include

cpp_options:
- -DMIN_TOOL_VERSION_ghc(x,y,z)=1

exclude_paths:
- libraries/ghc-heap/tests

---

source_paths:
- utils/haddock/haddock
- utils/haddock/haddock-api
- utils/haddock/haddock-library
- utils/haddock/driver

cpp_includes:
- _build/stage1/rts/build/include
- rts/include

exclude_paths:
- utils/haddock/haddock-api/src/Haddock/InterfaceFile.hs
- utils/haddock/haddock-api/src/Haddock/Types.hs

Acknowledgments

Thanks to Marcin Szamotulski for his work on ghc-tags-plugin ghc-tags is based on.