hdevtools
Persistent GHC powered background server for FAST haskell development tools
https://github.com/hdevtools/hdevtools/
Version on this page: | 0.1.7.0 |
LTS Haskell 11.22: | 0.1.7.0 |
Stackage Nightly 2018-09-28: | 0.1.7.0 |
Latest on Hackage: | 0.1.8.0 |
hdevtools-0.1.7.0@sha256:6057c855a804af1e8d83e31fd11d5a35f4f67cf8619564f6bf6278fdb8365637,3515
Module documentation for 0.1.7.0
There are no documented modules for this package.
hdevtools
Persistent GHC powered background server for FAST Haskell development tools
About
hdevtools
is a backend for text editor plugins, to allow for things such as
syntax and type checking of Haskell code, and retrieving type information, all
directly from within your text editor.
The advantage that hdevtools
has over competitors, is that it runs silently
in a persistent background process, and therefore is able to keeps all of your
Haskell modules and dependent libraries loaded in memory. This way, when you
change only a single source file, only it needs to be reloaded and rechecked,
instead of having to reload everything.
This makes hdevtools
very fast for checking syntax and type errors (runs just
as fast as the :reload
command in GHCi).
In fact, syntax and type checking is so fast, that you can safely enable auto checking on every save. Even for huge projects, checking is nearly instant.
Once you start using hdevtools
and you get used to having your errors shown
to you instantly (without having to switch back and forth between GHCi and your
editor), and shown directly on your code, in your editor (without having to
wait forever for GHC to run) you will wonder how you ever lived without it.
In addition to checking Haskell source code for errors, hdevtools
has tools
for getting info about identifiers, and getting type information for snippets
of code.
Text Editor Integration
hdevtools
is designed to be integrated into text editors. The list of current
editor plugins that supply this integration is below.
But before you do anything, you must first install hdevtools
itself. The
easiest way is from Stackage using stack:
$ stack install hdevtools
Note: hdevtools
automatically discovers compiler and libraries installed
via stack.
Alternatively one can install from Hackage via cabal install:
$ cabal install hdevtools
Then you should install one or more of the following editor plugins:
Vim - Syntastic
Syntastic is a popular syntax checking plugin for Vim, and is the
recommended Vim integration of hdevtools
syntax and type checking. Recent
versions of Syntastic(since Sep. 2012) have builtin support for hdevtools
.
Simply install hdevtools
(as above) and Syntastic, and it will
automatically check your Haskell files.
Syntastic will respect the g:hdevtools_options
variable (the same one as
used by vim-hdevtools, see below). See the section “Specifying GHC
Options” below for details how to use it.
Vim - vim-hdevtools
In addition to Syntastic, it is recommended that you also use
vim-hdevtools
for additional functionality.
vim-hdevtools
offers integration with the rest of the hdevtools
tools,
including retrieving info about the identifier under the cursor, and getting
the type of the code under the cursor. Refer to its documentation for more
details.
Emacs - flycheck
Flycheck is a modern batteries-included syntax checker for Emacs, and there is a flycheck-hdevtools checker available.
Atom - linter
There are two packages for the Atom editor:
- linter-hdevtools quickly finds and underlines type errors in Haskell files,
- hover-tooltips-hdevtools displays the types of identifiers under the mouse.
Sublime - SublimeLinter
SublimeLinter is a plugin for Sublime Text 3 that provides a framework
for linting code. The SublimeLinter-contrib-hdevtools plugin uses
hdevtools
to typecheck Haskell code.
Manual Editor Integration for any Editor
Most editors allow you to run a make
command, and will then parse the output
for errors and show line numbers, allowing you to jump between errors.
The hdevtools check
command is suitable for such usage.
For example, in Vim something like this will work:
:let &makeprg='hdevtools check %'
(Vim will replace the %
character with the name of the current file). Then
you can run
:make
And Vim will invoke hdevtools
to check the current file for errors, and then
show a list of them and allow jumping to them.
See the “Command Line Usage” section below for more information.
Command Line Usage
Note: When using one of the above editor plugins, you don’t really need to know this.
Available Commands and Help
For the list of commands available, run:
$ hdevtools --help
To get help for a specific command, run:
$ hdevtools [COMMAND] --help
For example:
$ hdevtools check --help
The hdevtools
background process
The first time hdevtools
runs a command, it will spawn a background process
that will remain running forever. You can check the status of this background
process by running:
$ hdevtools --status
You can shutdown the background process by running:
$ hdevtools --stop-server
Communication with the background process is done through a unix socket file.
The default name is .hdevtools.sock
, in the current directory. This allows
you to use hdevtools
with multiple projects simultaneously, without the
background processes getting in the way of each other.
You can use a different socket file name with the --socket
option, which
should be used for each invocation of hdevtools
. Remember that when telling
hdevtools
to check a Haskell file, paths are relative to the path of the
background process, not your current directory. This can cause problems, and
therefore it is recommended that you leave the socket file as the default, and
always run hdevtools
from the same directory.
You can specify the path to a target file with the --path
option. This is
useful for integration with IDEs that submit a copy of the original source
file (in a temporary directory) to hdevtools
making it impossible to extract
the .cabal
information for the file’s project. In such cases, you can run as:
$ hdevtools check -p /path/to/file.hs /tmp/file.hs
and hdevtools
will use the given path to obtain the .cabal
information.
Specifying GHC Options
For most non-trivial projects, you will need to tell hdevtools
about
additional GHC options that your project requires.
All hdevtools
commands accept a -g
flag for this purpose.
For example:
- Your project source code is in the directory
src
- You want to use the GHC option
-Wall
- You want to hide the package
transformers
to prevent conflicts
Invoke hdevtools
with something like this:
$ hdevtools check -g -isrc -g -Wall -g -hide-package -g transformers Foo.hs
Notice that a -g
flag is inserted before each GHC option. Don’t try to string
multiple GHC options together after a single -g
flag:
This won’t work:
$ hdevtools check -g '-hide-package transformers' Foo.hs
In general, you will need to pass to hdevtools
the same GHC options that you
would pass to GHCi.
For projects with custom build systems, you can prevent hdevtools
from
detecting a global stack.yaml
configuration with the argument --nostack
.
Specifying GHC Options in Vim
The Vim plugins allow setting GHC options in the g:hdevtools_options
variable. For example, for the above project, put the following in your
.vimrc
:
let g:hdevtools_options = '-g -isrc -g -Wall -g -hide-package -g transformers'
Specifying GHC Options with .hdevtoolsrc
If an .hdevtoolsrc
file is present, then hdevtools
will
parse arguments from the .hdevtoolsrc
file after arguments from the command
line.
For example, for the above project, the .hdevtoolsrc
file would contain:
-g -isrc -g -Wall -g -hide-package -g transformers
The .hdevtoolsrc
file will be searched for in the target path and all parents
of the target path, or, if the hdevtools
command has no target, in $PWD
and
all parents of $PWD
.
Credits
hdevtools
was inspired by ghcmod.- development moved here from bitc/hdevtools and schell/hdevtools.
Changes
Changelog
0.1.7.0 - 2018-08-08
- Add support for ghc-8.4 and Cabal-2.2.
0.1.6.1 - 2017-12-17
- Fixed
moduleinfo
command to load targets correctly. - Print version on
-v
command line option. - Fixed build with ghc-8.2.0.
0.1.6.0 - 2017-08-21
- Added handling of source errors: GHC
SourceError
and other exceptions are now correctly sent to the frontend process. This enableshdevtools
to correctly report haskell syntax errors and improves visibility of exceptions leading the backend process to die. .hdevtoolsrc
file for project-specific configuration.- Use of
stack
can be turned off with--nostack
.
0.1.5.0 - 2016-12-23
- (Re-)added template haskell support when required. Can be turned off using
--noth
. - Fixed system installed GHC libdir paths using stack.
0.1.4.1 - 2016-09-04
- Do not try to execute
stack
commands if not available.
0.1.4.0 - 2016-08-08
- Determine GHC libdir and binaries using stack.
0.1.3.2 - 2016-06-09
- Added GHC 8.0.x support
0.1.3.1 - 2016-05-13
- Added support for new Cabal versions
- Do not generate code, fixing inline-c modules typechecking
0.1.3.0 - 2016-02-29
- Improved performance in stack projects: The stack configuration is
updated only when the passed path implies a different
stack.yaml
. Performance improved substantially from roughly ~1s to ~0.3s.
0.1.2.2 - 2016-01-11
- Added type checking support for tests and benchmarks in stack projects.