ghc-tags-plugin: A compiler plugin which generates tags file from GHC parsed syntax tree.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

A GHC compiler plugin which takes parsed Haskell representation HsModule GhcPs, extracts tags information and saves it either in ctags or etags format.


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.1.0, 0.1.2.0, 0.1.2.1, 0.1.3.0, 0.1.4.0, 0.1.5.0, 0.1.6.0, 0.2.0.0, 0.2.1.0, 0.2.1.0, 0.2.2.0, 0.2.3.0, 0.2.4.0, 0.2.4.1, 0.3.0.0, 0.4.0.0, 0.4.0.1, 0.5.0.0, 0.5.1.0, 0.5.2.0, 0.5.3.0, 0.6.0.0, 0.6.0.1, 0.6.1.0
Change log CHANGELOG.md
Dependencies base (>=4.12.0.0 && <4.14), bytestring (>=0.10 && <0.11), directory (>=1.3 && <1.4), filepath (>=1.4 && <1.5), filepath-bytestring (>=1.4 && <1.5), ghc (>=8.4 && <8.9), ghc-tags-core, ghc-tags-plugin, mtl (>=2.2 && <2.3), optparse-applicative (>=0.15.1 && <0.16), pipes (>=4.3 && <4.4), pipes-attoparsec (>=0.5 && <0.6), pipes-bytestring (>=2.1 && <2.2), pipes-safe (>=2.3 && <2.4), text (>=1.2 && <1.3) [details]
License MPL-2.0
Copyright (c) 2020, Marcin Szamotulski
Author Marcin Szamotulski
Maintainer profunctor@pm.me
Category Development
Home page https://github.com/coot/ghc-tags-plugin#readme
Bug tracker https://github.com/coot/ghc-tags-plugin/issues
Source repo head: git clone https://github.com/coot/ghc-tags-plugin
Uploaded by coot at 2020-07-19T15:54:33Z

Modules

[Index] [Quick Jump]

Flags

Automatic Flags
NameDescriptionDefault
gtp-checkDisabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for ghc-tags-plugin-0.2.1.0

[back to package description]

Ghc Tags Compiler Plugin

Haskell Programming Language MPL-2.0 License

A Ghc Compiler Plugin which generates tags for each compiled module or component.

● Requirements

ghc >= 8.6

● Plugin options

Usage: <program> [-e|--etags] [file_path]
  write tags from ghc abstract syntax tree

Available options:
  -e,--etags               produce emacs etags file
  file_path                tags file: default tags or TAGS (when --etags is
                           specified)

It can be an absolute path or relative (to the *.cabal package file rather than cabal.project file), for example:

-fplugin-opt=Plugin.GhcTags:../tags

This is useful if for cabal packages which are located in subdirectories.

● Emacs support

To produce etags file you will need to pass the follwing option

-fplugin-opt=Plugin.GhcTags:--etags

● Editor configuration

By default each generated tags file is put next to the corresponding *.cabal package file. If you just have a repo with a cabal file in the main directory vim default tags setting will work, if you have some modules in subdirectories you will either need to set:

:set tags+=*/tags

or pass an option to modify where tags are written, see below.

● Configuration: Ghc / Cabal / Stack

Configuration of this plugin requires some familiarity with ghc packages. Check out documentation to use -plugin-package or -plugin-package-id. In the examples below we use -plugin-package=ghc-tags-plugin but specifying version -package=ghc-tags-plugin-0.0.0.0 (where 0.0.0.0 is the version you installed), might work better. You can use ghc-pkg latest ghc-tags-plugin (likely with appropriate --package-db flag) to check which version is available.

● Ghc

ghc -plugin-package=ghc-tags-plugin -fplugin=Plugin.GhcTags

You might also need to pass -package-db in which you installed the plugin.

● Cabal

Install the ghc-tags-plugin to cabal store with:

cabal install --lib ghc-tags-plugin

In cabal.project.local file add package stanza for every local package :

project some-project
    ghc-options: -package-db=PACKAGE_DB
                 -plugin-package=ghc-tags-plugin
                 -fplugin=Plugin.GhcTags

PACKAGE_DB is likely to be something like (for ghc-8.6.5) (all environment variables must be expanded):

${HOME}/.cabal/store/ghc-8.6.5/package.db

or on Windows (note the "" syntax)

"C:\\Users\\USER_NAME\\AppData\\Roaming\\cabal\\store\\ghc-8.6.5\\package.db

Note that you can also configure in this way non-local projects. You will likely want to pass -fplugin-opt=Plugin.GhcTags=PATH where PATH is an absolute path to your tags file.

● Stack

This is alternative method, which also could be modified for cabal (but it is not as nice as the previous method where you don't need to modify any files checked in vcs).

Add ghc-tags-plugin to build-depends in your *.cabal files. (You should hide it behind a cabal flag). And add these lines to stack.yaml file:

extra-deps:
  - git: https://github.com/coot/ghc-tags-plugin
    commit: a841dae7fb9c335101f7fa4187d02687d306f972

test-project: -plugin-package=ghc-tags-plugin
              -fplugin=Plugin.GhcTags

● Ghcid

If you follow the cabal configuration as above (using stack should work too)

ghcid --comaand "cabal repl project"

will update tags file as you modify your project.

● Makefile

The Makefile contains some useful commands, e.g. install, uninstall or reinstall the package in a package.db (by default into cabal store). This is mostly for development, but it could be useful in other scenarios as well.

● Exceptions

If a GHC plugin throws an exception, GHC stops. This plugin wraps IOExceptions, to make it obvious that it filed rather than GHC. This might mean you misconfigured the plugin (by passing wrong options). The result might look like this:

ghc: panic! (the 'impossible' happened)
  (GHC version 8.6.5 for x86_64-unknown-linux):
        GhcTagsPluginIOException ../: openFile: inappropriate type (Is a directory)

● Tips

● Security implications of compiler plugins

Such plugins can:

This plugin only reads & writes to tags file (and updates a shared mutable state) as of IO, and does not modify/ the syntax tree.