# ghc-tags
[](https://github.com/arybczak/ghc-tags/actions?query=branch%3Amaster)
[](https://hackage.haskell.org/package/ghc-tags)
A command line tool that generates etags
([Emacs](https://www.gnu.org/software/emacs)) and ctags
([Vim](https://www.vim.org), [VSCode](https://code.visualstudio.com) with
[ctagsx](https://marketplace.visualstudio.com/items?itemName=jtanx.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):
```yaml
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](https://github.com/coot/ghc-tags-plugin) `ghc-tags` is based on.