# Configuration¶

## Configuring haskell-language-server¶

Language servers like haskell-language-server expose most of their configuration via the client (i.e. the editor). That means that the way in which you configure the settings will depend on the client.

Most clients (editors) already have an opinion about how settings should be configured! For example, in VS Code you use the graphical Settings tab or settings.json, whereas in Emacs you use customization variables. In the editor configuration section we give some pointers for popular editors, but you should consult the documentation for your specific editor if you have trouble.

However, we can say some high-level things about the kinds of configuration haskell-language-server uses, and how to use them. This can sound a bit confusing, but ultimately the client should present you with these options in a user-friendly way that makes sense for that editor.

### Generic server options¶

The LSP protocol is designed to support many useful server configuration options generically. These are sent to the server by the client, and can be controlled without reference to a specific language.

For example, there are protocol methods for highlighting matching identifiers throughout a document. This is a capability which any server can implement, so the client can decide generically whether to ask the server to do it or not. So your editor can provide a setting to turn this on or off globally, for any language server you might use.

Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by lsp-mode.

### Generic editor options¶

Your editor may provide some settings that affect how the information from the language server is used. For example, whether popups are shown, or whether code lenses appear by default.

Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by lsp-mode.

### Language-specific server options¶

A specific language server can also have its own configuration options. These are still sent to the server by the client, but they can only be controlled by a specific client that knows about those options.

For example, haskell-language-server allows you to choose the formatting provider which will be used for formatting Haskell source. This option obviously would not make sense for language servers for other languages, or even for other Haskell language servers (which need not even support formatting).

Here is a list of the additional settings currently supported by haskell-language-server, along with their setting key (you may not need to know this) and default:

• Formatting provider (haskell.formattingProvider, default ormolu): what formatter to use; one of floskell, ormolu, fourmolu, stylish-haskell, or brittany (if compiled with the brittany plugin).

• Format on imports (haskell.formatOnImportOn, default true): whether to format after adding an import.

• Diagnostics on change (haskell.diagnosticsOnChange, default true): (currently unused).

• Completion snippets (haskell.completionSnippetsOn, default true): whether to support completion snippets. Deprecated as it is equivalent to haskell.plugin.ghcide-completions.config.snippetsOn.

• Liquid Haskell (haskell.liquidOn, default false): whether to enable Liquid Haskell support (currently unused until the Liquid Haskell support is functional again, see https://github.com/haskell/haskell-language-server/issues/367).

• Hlint (haskell.hlintOn, default true): whether to enable Hlint support. Deprecated as it is equivalen to haskell.plugin.hlint.globalOn

• Max completions (haskell.maxCompletions, default 40): maximum number of completions sent to the LSP client.

• Check project (haskell.checkProject, default true): whether to typecheck the entire project on load. As it is activated by default could drive to bad perfomance in large projects.

• Check parents (haskell.checkParents, default CheckOnSaveAndClose): when to typecheck reverse dependencies of a file; one of NeverCheck, CheckOnClose, CheckOnSaveAndClose, or AlwaysCheck.

#### Generic plugin configuration¶

Plugins have a generic config to control their behaviour. The schema of such config is:

• haskell.plugin.${pluginName}.globalOn: usually with default true. Whether the plugin is enabled at runtime or it is not. That is the option you might use if you want to disable completely a plugin. • Actual plugin names are: ghcide-code-actions-fill-holes, ghcide-completions, ghcide-hover-and-symbols, ghcide-type-lenses, ghcide-code-actions-type-signatures, ghcide-code-actions-bindings, ghcide-code-actions-imports-exports, eval, moduleName, pragmas, refineImports, importLens, class, tactics (aka wingman), hlint, haddockComments, retrie, splice. • So to disable the import lens with an explicit list of module definitions you could set haskell.plugin.importLens.globalOn: false • haskell.plugin.${pluginName}.${lspCapability}On: usually with default true. Whether a concrete plugin capability is enabled. • Capabilities are the different ways a lsp server can interact with the editor. The current available capabilities of the server are: callHierarchy, codeActions, codeLens, diagnostics, hover, symbols, completion, rename. • Note that usually plugins don’t provide all capabilities but some of them or even only one. • So to disable code changes suggestions from the hlint plugin (but no diagnostics) you could set haskell.plugin.hlint.codeActionsOn: false • Plugin specific configuration: • tactic (aka wingman): • haskell.plugin.tactics.config.auto_gas, default 4: The depth of the search tree when performing “Attempt to fill hole”. Bigger values will be able to derive more solutions, but will take exponentially more time. • haskell.plugin.tactics.config.timeout_duration, default 2: The timeout for Wingman actions, in seconds. • haskell.plugin.tactics.config.hole_severity, default empty: The severity to use when showing hole diagnostics. These are noisy, but some editors don’t allow jumping to all severities. One of error, warning, info, hint, none. • haskell.plugin.tactics.config.max_use_ctor_actions, default 5: Maximum number of Use constructor <x> code actions that can appear. • haskell.plugin.tactics.config.proofstate_styling, default true: Should Wingman emit styling markup when showing metaprogram proof states? • ghcide-completions: • haskell.plugin.ghcide-completions.config.snippetsOn, default true: Inserts snippets when using code completions. • haskell.plugin.ghcide-completions.config.autoExtendOn, default true: Extends the import list automatically when completing a out-of-scope identifier. • ghcide-type-lenses: • haskell.plugin.ghcide-type-lenses.config.mode, default always: Control how type lenses are shown. One of always, exported, diganostics. • hlint: • haskell.plugin.hlint.config.flags, default empty: List of flags used by hlint. This reference of configuration can be outdated at any time but we can query the haskell-server-executable about what configuration is effectively used: • haskell-language-server generate-default-config: will print the json configuration with all default values. It can be used as template to modify it. • haskell-language-server vscode-extension-schema: will print a json schema used to setup the haskell vscode extension. But it is useful to see what range of values can an option take and a description about it. Settings like this are typically provided by the language-specific LSP client support for your editor, for example in Emacs by lsp-haskell. ### Client options¶ A particular client might also have some options of its own, for example to control how the server executable is started. Settings like this are typically be provided by the language-specific LSP client support for your editor, for example in Emacs by lsp-haskell. ## Configuring your project build¶ haskell-language-server has to compile your project in order to give you diagnostics, which means that it needs to know how to do so. This is handled by the hie-bios project. For a full explanation of how hie-bios determines the project build configuration, and how to configure it manually, refer to the hie-bios README. At the moment, haskell-language-server has support to automatically detect your project build configuration to handle most use cases. So using a explicit hie.yaml file will not likely fix your ide setup. It will do it almost only if you see an error like Multi Cradle: No prefixes matched If the automatic detection fails with that error you can configure hie-bios using a hie.yaml file in the root of the workspace. A hie.yaml file explicitly describes how to setup the environment to compile the various parts of your project. For that you need to know what components your project has, and the path associated with each one. So you will need some knowledge about stack or cabal components. You also can use this utility to automatically generate hie.yaml files for the most common stack and cabal configurations For example, to state that you want to use stack then the configuration file would look like: cradle: stack: component: "haskell-language-server:lib"  If you use cabal then you probably need to specify which component you want to use. cradle: cabal: component: "lib:haskell-language-server"  If you have a project with multiple components, you can use a cabal-multi cradle: cradle: cabal: - path: "./test/functional/" component: "haskell-language-server:func-test" - path: "./test/utils/" component: "haskell-language-server:hls-test-utils" - path: "./exe/Main.hs" component: "haskell-language-server:exe:haskell-language-server" - path: "./exe/Wrapper.hs" component: "haskell-language-server:exe:haskell-language-server-wrapper" - path: "./src" component: "lib:haskell-language-server" - path: "./ghcide/src" component: "ghcide:lib:ghcide" - path: "./ghcide/exe" component: "ghcide:exe:ghcide"  Equivalently, you can use stack: cradle: stack: - path: "./test/functional/" component: "haskell-language-server:func-test" - path: "./exe/Main.hs" component: "haskell-language-server:exe:haskell-language-server" - path: "./exe/Wrapper.hs" component: "haskell-language-server:exe:haskell-language-server-wrapper" - path: "./src" component: "haskell-language-server:lib" - path: "./ghcide/src" component: "ghcide:lib:ghcide" - path: "./ghcide/exe" component: "ghcide:exe:ghcide"  Or you can explicitly state the program which should be used to collect the options by supplying the path to the program. It is interpreted relative to the current working directory if it is not an absolute path. cradle: bios: program: ".hie-bios"  The complete configuration is a subset of cradle: cabal: component: "optional component name" stack: component: "optional component name" bios: program: "program to run" dependency-program: "optional program to run" direct: arguments: ["list","of","ghc","arguments"] default: none: dependencies: - someDep  ### How to show local documentation on hover¶ Haskell Language Server can display Haddock documentation on hover and completions if the project and its dependencies have been built with the -haddock GHC flag. • For cabal: • Add to your global config file (e.g. ~/.cabal/config): program-default-options ghc-options: -haddock  • Or, for a single project, run cabal configure --ghc-options=-haddock • For stack, add to global $STACK_ROOT\config.yaml, or project’s stack.yaml:

ghc-options:


### Emacs¶

Emacs support is provided by a combination of the following packages:

You can install these manually if you are using plain Emacs; instructions for some specific flavours are included below.

Make sure to check the READMEs of each of these packages, which explain how to configure the various parts of the Emacs integration. In particular, lsp-haskell provides customization options for the haskell-language-server-specific parts, such as the path to the server executable.

#### doom-emacs¶

Manual installation of packages is not required. Enable the lsp module and the haskell lang module with lsp flag in .doom.d/init.el:

:tools
lsp
;; ...
:lang


then do \$HOME/.emacs.d/bin/doom sync

#### Spacemacs¶

Manual installation of packages is not required. Enable the haskell layer and the lsp layer in your Spacemacs config file:

dotspacemacs-configuration-layers
'(
lsp
;; ...
)


### Kakoune¶

1. Grab a copy of kak-lsp, and follow the setup instructions.

2. Point your kak-lsp.toml to haskell-language-server-wrapper.

[language.haskell]