2017-01-22 23:31:14 +00:00
|
|
|
# ghc-mod: Happy Haskell Hacking
|
|
|
|
|
[](https://gitlab.com/dxld/ghc-mod/commits/master)
|
2013-05-22 03:04:05 +00:00
|
|
|
|
2017-07-10 00:57:15 +00:00
|
|
|
ghc-mod provides editors/IDEs with support for Haskell compiler features. It
|
2017-03-09 10:34:17 +00:00
|
|
|
supports both Cabal and Stack based projects and integrations exist for Emacs,
|
|
|
|
|
Vim, Atom, IntelliJ and VSCode.
|
2013-05-22 03:04:05 +00:00
|
|
|
|
2017-01-22 23:31:14 +00:00
|
|
|
- for [all Haskell developers (Using ghc-mod in your development environment)](#using-ghc-mod-in-your-development-environment)
|
|
|
|
|
- for [people developing Haskell IDEs (Using ghc-mod as an IDE backend program)](#using-ghc-mod-as-an-ide-backend-program)
|
|
|
|
|
- for [developing Haskell tooling (Using ghc-mod as a library)](#using-ghc-mod-as-a-library)
|
2014-05-19 07:42:34 +00:00
|
|
|
|
2017-01-22 23:31:14 +00:00
|
|
|
## Overview
|
2014-09-12 05:02:34 +00:00
|
|
|
|
2017-03-09 10:34:17 +00:00
|
|
|
### Using ghc-mod in your Development Environment
|
2014-05-19 07:25:38 +00:00
|
|
|
|
2017-01-22 23:31:14 +00:00
|
|
|
To use `ghc-mod` in your development environment of choice you need two things:
|
2014-05-19 07:25:38 +00:00
|
|
|
|
2017-01-22 23:31:14 +00:00
|
|
|
- The `ghc-mod` program included in the package of the same name, see [Installing](https://github.com/DanielG/ghc-mod/wiki/Installing)
|
|
|
|
|
- A ghc-mod frontend to integrate it into your development environment, see [Frontend](https://github.com/DanielG/ghc-mod/wiki/Frontend)
|
2014-05-19 07:25:38 +00:00
|
|
|
|
2017-03-09 10:34:17 +00:00
|
|
|
### Using ghc-mod as an IDE Backend Program
|
2014-05-19 07:35:38 +00:00
|
|
|
|
2017-03-09 10:34:17 +00:00
|
|
|
We provide two modes of operation for frontends: interactive and single shot
|
2017-07-10 00:57:15 +00:00
|
|
|
mode. The former is accessed by calling `$ ghc-mod legacy-interactive`. This will
|
|
|
|
|
sit and wait for you to type a command, exiting when an empty line is
|
|
|
|
|
entered. Interactive mode is pretty much always faster than single shot mode,
|
2017-03-09 10:34:17 +00:00
|
|
|
since it gives ghc-mod the ability to cache the compiler session between
|
2017-07-10 00:57:15 +00:00
|
|
|
commands. On the other hand, it needs more memory because it keeps these things
|
2017-03-09 10:34:17 +00:00
|
|
|
cached.
|
2014-12-16 20:34:04 +00:00
|
|
|
|
2017-03-09 10:34:17 +00:00
|
|
|
Single shot mode is pretty much only there for (backwards) compatibility with
|
2017-07-10 00:57:15 +00:00
|
|
|
Vim, since it only recently got the ability to talk to background processes
|
|
|
|
|
without installing some external plugin. You can use single shot mode by simply
|
|
|
|
|
calling the sub-commands of the `ghc-mod` program. Since recompiling large
|
|
|
|
|
projects can be really, really slow, you really should prefer interactive mode.
|
|
|
|
|
|
|
|
|
|
As a rule of thumb, all commands available in single shot mode are available in
|
|
|
|
|
interactive mode. A list of the former can be obtained by running
|
2017-03-09 10:34:17 +00:00
|
|
|
`$ ghc-mod --help`.
|
|
|
|
|
|
2017-07-10 00:57:15 +00:00
|
|
|
If you're developing a new ghc-mod frontend, we'd love to hear from you! Please
|
|
|
|
|
open an issue or e-mail the maintainer. Also, we invite you to add installation
|
2017-03-09 10:34:17 +00:00
|
|
|
and configuration instructions to
|
|
|
|
|
[Frontend](https://github.com/DanielG/ghc-mod/wiki/Frontend).
|
|
|
|
|
|
|
|
|
|
### Using ghc-mod as a Library
|
2014-09-12 05:02:34 +00:00
|
|
|
|
2017-07-10 00:57:15 +00:00
|
|
|
Internally, ghc-mod uses the Glasgow Haskell Compiler's API to implement most of
|
|
|
|
|
its functionality.
|
2014-09-12 05:02:34 +00:00
|
|
|
|
2017-07-10 00:57:15 +00:00
|
|
|
In order to provide a hassle-free experience to users, ghc-mod tries hard to
|
|
|
|
|
automatically, and correctly, detect and, if necessary, tweak the environment GHC
|
2017-01-22 23:31:14 +00:00
|
|
|
needs. It also handles some of the more cumbersome parts of getting a working
|
|
|
|
|
compiler session up and running.
|
2014-09-12 05:02:34 +00:00
|
|
|
|
2017-07-10 00:57:15 +00:00
|
|
|
This functionality can be very useful to all kinds of Haskell development tools.
|
|
|
|
|
Therefore, we want to expose all the useful abstractions ghc-mod provides.
|
2014-09-12 05:02:34 +00:00
|
|
|
|
2017-07-10 00:57:15 +00:00
|
|
|
Right now the ghc-mod API is pretty messy; a result of major internal rewrite
|
2017-03-09 10:34:17 +00:00
|
|
|
and reorganization coupled with too little time for cleanups over the course of
|
2017-01-22 23:31:14 +00:00
|
|
|
almost 100 releases! We would like to make a cut during v6.0 or so and
|
2017-07-10 00:57:15 +00:00
|
|
|
completely redo the API, but we need more input from downstream tool writers to
|
2017-01-22 23:31:14 +00:00
|
|
|
do that properly, see [Library API Redesign](Library-API-Redesign.md).
|
2015-03-03 11:18:54 +00:00
|
|
|
|
2017-07-10 00:57:15 +00:00
|
|
|
For example, [The Haskell Refactorer (HaRe)](https://github.com/alanz/HaRe) uses
|
|
|
|
|
the build environment abstraction ghc-mod provides so it can concentrate on its
|
2017-03-09 10:34:17 +00:00
|
|
|
core functionality instead of worrying about build environments and compiler
|
|
|
|
|
session setup.
|
2015-03-03 11:18:54 +00:00
|
|
|
|
2017-03-09 10:34:17 +00:00
|
|
|
Recently the
|
2017-01-22 23:31:14 +00:00
|
|
|
[`haskell-ide-engine`](https://github.com/haskell/haskell-ide-engine) project
|
2017-07-10 00:57:15 +00:00
|
|
|
has sprung up, and if you're planning to write any kind of tool that needs editor
|
|
|
|
|
integration eventually you should definitely look into that. `haskell-ide-engine`
|
|
|
|
|
uses `ghc-mod` at its core, so you'll want to be familliar with it either way.
|
2017-01-22 23:31:14 +00:00
|
|
|
|
|
|
|
|
API "documentation" is here:
|
2017-01-22 23:36:57 +00:00
|
|
|
[Hackage docs](https://hackage.haskell.org/package/ghc-mod#modules).
|
2015-03-03 11:18:54 +00:00
|
|
|
|
2017-03-09 10:34:17 +00:00
|
|
|
## Reporting Bugs
|
|
|
|
|
|
|
|
|
|
Please report bugs on the GitHub issue tracker for ghc-mod:
|
|
|
|
|
https://github.com/DanielG/ghc-mod/issues
|
|
|
|
|
|
|
|
|
|
Including general environment information like the operating system
|
|
|
|
|
(distribution, version) you're using and the output of `$ ghc-mod debug` run in
|
|
|
|
|
your project directory is probably a good idea.
|
|
|
|
|
|
2014-09-12 05:02:34 +00:00
|
|
|
## IRC
|
2014-05-19 07:35:38 +00:00
|
|
|
|
2014-09-12 05:02:34 +00:00
|
|
|
If you have any problems, suggestions, comments swing by
|
2015-03-28 01:35:36 +00:00
|
|
|
[\#ghc-mod (web client)](https://kiwiirc.com/client/irc.freenode.org/ghc-mod) on
|
|
|
|
|
Freenode. If you're reporting a bug please also create an issue
|
2017-03-09 10:34:17 +00:00
|
|
|
[here (GitHub issue tracker)](https://github.com/DanielG/ghc-mod/issues) so we
|
|
|
|
|
have a way to contact you if you don't have time to stay.
|
2015-03-05 15:52:11 +00:00
|
|
|
|
2017-07-10 00:57:15 +00:00
|
|
|
Do hang around for a while if no one answers, and repeat your question if you
|
2017-03-09 10:34:17 +00:00
|
|
|
still haven't gotten any answer after a day or so (the maintainer was probably
|
|
|
|
|
asleep). You're most likely to get an answer during the day in GMT+1.
|
