This extension adds language support for Haskell, powered by the Haskell Language Server. As almost all features are provided by the server you might find interesting read its documentation.
This Extension comes with "batteries"-included and can manage your Haskell Language Server installations for you, powered by GHCup. Installation of GHCup can not happen automatically, so if you want your HLS installations to be managed by the Extension, you will have to follow the installation instructions for GHCup.
Note: Make sure you have a working ghcup
installation, before launching the Extension.
You can watch demos for some of these features here.
.hs
/.lhs
files, ghc must be installed and on the PATH. The easiest way to install it is with ghcup.For a general picture about the server configuration, including the project setup, you can consult the server documentation about the topic.
For information on how to set configuration in VSCode, see here.
If your server is manually installed and not on your path, you can also manually set the path to the executable.
"haskell.serverExecutablePath": "~/.local/bin/haskell-language-server"
There are a few placeholders which will be expanded:
~
, ${HOME}
and ${home}
will be expanded into your users' home folder.${workspaceFolder}
and ${workspaceRoot}
will expand into your current project root.The option has machine-overridable
scope so it can be changed per workspace.
This supposes it could be used to execute arbitrary programs adding a .vscode/settings.json
in the workspace folder including this option with the appropriate path.
See #387 for more details.
You can add additional environment variables for the lsp server using the configuration option haskell.serverEnvironment
. For example, to change the cache directory used by the server you could set:
{ "haskell.serverEnvironment": { "XDG_CACHE_HOME": "/path/to/my/cache" } }
as the server uses the XDG specification for cache directories.
The environment only will be visible for the lsp server, not for other extension tasks like find the server executable.
This extension will download haskell-language-server
binaries and the rest of the toolchain if you selected to use GHCup during
first start. Check the haskell.manageHLS
setting.
It will then download the newest version of haskell-language-server which has support for the required ghc. That means it could use an older version than the latest one, without the last features and bug fixes. For example, if a project needs ghc-8.10.4 the extension will download and use haskell-language-server-1.4.0, the latest version which supported ghc-8.10.4. Even if the latest global haskell language-server version is 1.5.1.
If you have disk space issues, check ghcup gc --help
.
You can also instruct the extension to use a different installation directory for the toolchain, e.g. to not interfere with system GHCup installation. Depending on your platform, add the full resolved path like so:
"haskell.serverEnvironment": {
"GHCUP_INSTALL_BASE_PREFIX": "/home/foo/.config/Code/User/globalStorage/haskell.haskell/"
}
The internal storage paths for the extension depend on the platform:
Platform | Path |
---|---|
macOS | ~/Library/Application\ Support/Code/User/globalStorage/haskell.haskell/.ghcup |
Windows | %APPDATA%\Code\User\globalStorage\haskell.haskell\ghcup |
Linux | $HOME/.config/Code/User/globalStorage/haskell.haskell/.ghcup |
If you want to manage HLS yourself, set haskell.manageHLS
to PATH
and make sure HLS is in your PATH
or set haskell.serverExecutablePath
(overrides all other settings) to a valid executable.
If you need to set mirrors for ghcup download info, check the settings haskell.metadataURL
and haskell.releasesURL
.
When manageHLS
is set to GHCup
, you can define a specific toolchain (hls
, ghc
, cabal
and stack
),
either globally or per project. E.g.:
{
"haskell.toolchain": {
"hls": "1.6.1.1",
"cabal": "recommended",
"stack": null
}
}
This means:
ghc
version corresponding to the project (default, because it's omitted)hls
1.6.1.1cabal
version from ghcupstack
versionAnother config could be:
{
"haskell.toolchain": {
"ghc": "9.2.2",
"hls": "latest",
"cabal": "recommended"
}
}
Meaning:
ghc
9.2.2 regardless of what the project requireshls
, even if it doesn't support the given GHC versioncabal
stack
(default, because it's omitted)The defaults (when omitted) are as follows:
ghc
(corresponding to with-compiler
setting in cabal.project
for example)hls
version that supports the project required ghc versioncabal
stack
When a the value is null
, the extension will refrain from installing it.
At last, if you don't want ghcup
to manage any of the external tools except hls
, you can use:
{
"haskell.toolchain": {
"ghc": null,
"cabal": null,
"stack": null
}
}
You can check each GHC version's support status and the policy followed for deprecations here.
Building from source may support more versions!
The exact list of binaries can be checked in the last release of haskell-language-server: https://github.com/haskell/haskell-language-server/releases/latest
First, check out what multi-root workspaces are. The idea of using multi-root workspaces, is to be able to work on several different Haskell projects, where the GHC version or stackage LTS could differ, and have it work smoothly.
The language server is now started for each workspace folder you have in your multi-root workspace, and several configurations are on a resource (i.e. folder) scope, instead of window (i.e. global) scope.
Haskell
and choose Extensions Settings
Haskell › Trace: Server
and set it to messages
.Haskell › Trace: Client
to debug
. It will print all the environment variables so take care it does not contain any sensitive information before sharing it.View -> Output
(Ctrl + Shift + U
)Haskell (<your project>)
Please include the output when filing any issues on the haskell-language-server issue tracker.
Failed to get project GHC version
on darwin M1 with stackIf you have installed stack via the official cannels, the binary will not be M1 native, but x86 and trigger the rosetta compatibility layer. GHCup provides real stack/HLS M1 binaries, so make sure you install stack via GHCup. Also see https://github.com/haskell/haskell-language-server/issues/2864
GHC ABIs don't match
If you are using certain versions of GHC (such as 9.0.2 or 9.2.4) while running Stack, you may encounter this issue due to an outdated GHC bindist installed by Stack. The vscode-haskell extension does not support the use of GHC binaries managed by Stack. Therefore, it is recommended to configure Stack to allow GHCup to install these binaries instead. Please refer to the instructions provided by ghcup for this purpose.
If you really want to use GHC 9.0.2 managed by Stack, force it to install the fixed bindist (that includes profiling libs) by adding this to your stack.yaml (depending on your platform):
setup-info:
ghc:
linux64-tinfo6:
9.0.2:
url: 'https://downloads.haskell.org/ghc/9.0.2/ghc-9.0.2a-x86_64-fedora27-linux.tar.xz'
Now make sure to remove cached/installed libraries to avoid getting segfaults at runtime.
As a final workaround, you can try to compile HLS from source (the extension should pick it up) via ghcup, see https://haskell-language-server.readthedocs.io/en/stable/installation.html#ghcup. In any case, the recommended approach is to let GHCup install the GHC binaries.
hGetContents: invalid argument (invalid byte sequence)
This problem was encountered on darwin M2 with ghcup.
Should you see the error that the "Haskell server crashed 5 times in the last 3 minutes," you can check the Haskell output to see whether this was due to an error mentioning hGetContents: invalid argument (invalid byte sequence)
.
If this is the case, setting terminal.integrated.detectLocale
to off
might resolve your issue.
If something just doesn't work, but you recall an old configuration that did, you may try forcing a particular setting, e.g. by disabling all automatic installations except HLS:
"haskell.toolchain": {
"hls": "1.6.1.0",
"ghc": null,
"cabal": null,
"stack": null
}
Also make sure GHCup is installed and in $PATH
. If you're not starting VSCode from the terminal, you might need to add ${HOME}/.ghcup/bin
to PATH like so:
"haskell.serverEnvironment": {
"PATH": "${HOME}/.ghcup/bin:$PATH"
}
If you want to help, get started by reading Contributing for more details.
See the Changelog for more details.