You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/configuration.md
+10-10
Original file line number
Diff line number
Diff line change
@@ -21,14 +21,14 @@ For example, there are protocol methods for highlighting matching identifiers th
21
21
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.
22
22
So your editor can provide a setting to turn this on or off globally, for any language server you might use.
23
23
24
-
Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by [`lsp-mode`](https://github.com/emacs-lsp/lsp-mode).
24
+
Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by [lsp-mode](https://github.com/emacs-lsp/lsp-mode).
25
25
26
26
### Generic editor options
27
27
28
28
Your editor may provide some settings that affect how the information from the language server is used.
29
29
For example, whether popups are shown, or whether code lenses appear by default.
30
30
31
-
Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by [`lsp-mode`](https://github.com/emacs-lsp/lsp-mode).
31
+
Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by [lsp-mode](https://github.com/emacs-lsp/lsp-mode).
32
32
33
33
### Language-specific server options
34
34
@@ -48,7 +48,7 @@ Here is a list of the additional settings currently supported by `haskell-langua
48
48
- Hlint (`haskell.hlintOn`, default true): whether to enable Hlint support. *Deprecated* as it is equivalen to `haskell.plugin.hlint.globalOn`
49
49
- Max completions (`haskell.maxCompletions`, default 40): maximum number of completions sent to the LSP client.
50
50
- 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.
51
-
- Check parents (`haskell.checkParents`, default `CheckOnSaveAndClose`): when to typecheck reverse dependencies of a file; one of `NeverCheck`, `CheckOnClose`, `CheckOnSaveAndClose`, or `AlwaysCheck`.
51
+
- Check parents (`haskell.checkParents`, default `CheckOnSaveAndClose`): when to typecheck reverse dependencies of a file; one of `NeverCheck`, `CheckOnClose`, `CheckOnSaveAndClose`, or `AlwaysCheck`.
52
52
53
53
#### Generic plugin configuration
54
54
@@ -57,7 +57,7 @@ Plugins have a generic config to control their behaviour. The schema of such con
57
57
-`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.
- So to disable the import lens with an explicit list of module definitions you could set `haskell.plugin.importLens.globalOn: false`
60
-
-`haskell.plugin.${pluginName}.${lspCapability}On`: usually with default true. Whether a concrete plugin capability is enabled.
60
+
-`haskell.plugin.${pluginName}.${lspCapability}On`: usually with default true. Whether a concrete plugin capability is enabled.
61
61
- 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`.
62
62
- Note that usually plugins don't provide all capabilities but some of them or even only one.
63
63
- So to disable code changes suggestions from the `hlint` plugin (but no diagnostics) you could set `haskell.plugin.hlint.codeActionsOn: false`
@@ -78,7 +78,7 @@ Plugins have a generic config to control their behaviour. The schema of such con
78
78
This reference of configuration can be outdated at any time but we can query the `haskell-server-executable` about what configuration is effectively used:
79
79
-`haskell-language-server generate-default-config`: will print the json configuration with all default values. It can be used as template to modify it.
80
80
-`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.
81
-
81
+
82
82
Settings like this are typically provided by the language-specific LSP client support for your editor, for example in Emacs by `lsp-haskell`.
83
83
84
84
### Client options
@@ -90,11 +90,11 @@ Settings like this are typically be provided by the language-specific LSP client
90
90
## Configuring your project build
91
91
92
92
`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.
93
-
This is handled by the [`hie-bios`](https://github.com/mpickering/hie-bios) project.
93
+
This is handled by the [hie-bios](https://github.com/mpickering/hie-bios) project.
94
94
95
-
**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](https://github.com/mpickering/hie-bios/blob/master/README.md).**
95
+
**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](https://github.com/mpickering/hie-bios/blob/master/README.md).**
96
96
97
-
At the moment, `haskell-language-server` has support to automatically detect your project build configuration to handle most use cases.
97
+
At the moment, `haskell-language-server` has support to automatically detect your project build configuration to handle most use cases.
98
98
99
99
*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`
100
100
@@ -104,7 +104,7 @@ For that you need to know what *components* your project has, and the path assoc
104
104
So you will need some knowledge about
105
105
[stack](https://docs.haskellstack.org/en/stable/build_command/#components) or [cabal](https://cabal.readthedocs.io/en/latest/cabal-commands.html?#cabal-v2-build) components.
106
106
107
-
You also can use [this utility](https://github.com/Avi-D-coder/implicit-hie) to automatically generate `hie.yaml` files for
107
+
You also can use [implicit-hie](https://github.com/Avi-D-coder/implicit-hie) to automatically generate `hie.yaml` files for
108
108
the most common stack and cabal configurations
109
109
110
110
For example, to state that you want to use `stack` then the configuration file
@@ -351,7 +351,7 @@ it may also be helpful to also specify root markers:
351
351
let g:LanguageClient_rootMarkers = ['*.cabal', 'stack.yaml']
352
352
```
353
353
354
-
Further configuration can be done by pointing the [`g:LanguageClient_settingsPath`](https://github.com/autozimu/LanguageClient-neovim/blob/0e5c9546bfddbaa2b01e5056389c25aefc8bf989/doc/LanguageClient.txt#L221)
354
+
Further configuration can be done by pointing the `g:LanguageClient_settingsPath` [option](https://github.com/autozimu/LanguageClient-neovim/blob/0e5c9546bfddbaa2b01e5056389c25aefc8bf989/doc/LanguageClient.txt#L221)
355
355
variable to the file in which you want to keep your LSP settings.
Copy file name to clipboardExpand all lines: docs/contributing/contributing.md
+21-16
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ The Haskell tooling dream is near, we need your help!
10
10
- Join the [haskell-tooling channel](https://matrix.to/#/#haskell-tooling:matrix.org) in [matrix](https://matrix.org/).
11
11
- Visit [the project GitHub repo](https://github.com/haskell/haskell-language-server) to view the source code, or open issues or pull requests.
The project can then be built with both `cabal build` and `stack build`.
21
21
22
-
haskell-language-server can also be used with itself. We provide preset samples of `hie.yaml` for Cabal and Stack.
23
-
24
-
Note: the `./install/` folder is not directly tied to the project so it has dedicated `./install/hie.yaml.[cbl|stack]`
25
-
templates.
26
-
27
22
### Using Cabal
28
23
29
24
```shell
30
-
$ cp hie-cabal.yaml hie.yaml
31
-
$ cp install/hie-cabal.yaml install/hie.yaml
25
+
# If you have not run `cabal update` in a while
26
+
$ cabal update
27
+
# Then
28
+
$ cabal build
32
29
```
33
30
34
31
### Using Stack
35
32
36
33
```shell
37
-
$ cp hie-stack.yaml hie.yaml
38
-
$ cp install/hie-stack.yaml install/hie.yaml
39
-
$ cp ghcide/hie-stack.yaml ghcide/hie.yaml
40
-
$ stack build --test --no-run-tests
41
-
$ cd install
42
34
$ stack build
43
35
```
44
36
@@ -119,26 +111,39 @@ An alternative, which only recompiles when tests (or dependencies) change:
119
111
$ cabal run haskell-language-server:func-test -- -p "hlint enables"
120
112
```
121
113
122
-
### Test your hacked HLS in your editor
114
+
## Using HLS on HLS code
115
+
116
+
[HLS project configuration guidelines](../configuration.md#configuring-your-project-build) also apply to the HLS project itself.
117
+
118
+
Note: HLS implicitly detects HLS codebase as a Stack project (see [hie-bios implicit configuration documentation](https://github.com/haskell/hie-bios/blob/master/README.md#implicit-configuration)).
119
+
If you want HLS to use Cabal, you need to create an `hie.yaml` file:
120
+
```yaml
121
+
cradle:
122
+
cabal:
123
+
```
124
+
125
+
Also note that the `install/` subdirectory is a different project, so if you want to work on this part of the code, you may also have to create an `install/hie.yaml` file.
123
126
127
+
### Manually testing your hacked HLS
124
128
If you want to test HLS while hacking on it, follow the steps below.
125
129
126
130
To do once:
127
131
128
-
- Open some codebase on which you want to test your hacked HLS in your favorite editor
132
+
- Open some codebase on which you want to test your hacked HLS in your favorite editor (it can also be HLS codebase itself: see previous section for configuration)
129
133
- Configure this editor to use your custom HLS executable
130
134
- With Cabal:
131
135
- On Unix systems: `cabal exec which haskell-language-server`
132
136
- On Windows: `cabal exec where haskell-language-server`
133
137
- With Stack: `$(stack path --dist-dir)/build/haskell-language-server/haskell-language-server`
134
138
135
-
To do every time you changed code and want to test it:
139
+
To do every time you change HLS code and want to test it:
136
140
137
141
- Build HLS
138
142
- With Cabal: `cabal build exe:haskell-language-server`
139
143
- With Stack: `stack build haskell-language-server:exe:haskell-language-server`
140
144
- Restart HLS
141
145
- With VS Code: `Haskell: Restart Haskell LSP Server`
Copy file name to clipboardExpand all lines: docs/troubleshooting.md
+25-8
Original file line number
Diff line number
Diff line change
@@ -21,19 +21,30 @@ Example with `tasty-discover`:
21
21
22
22
This returns an error in HLS if 'tasty-discover' is not in the path: `could not execute: tasty-discover`.
23
23
24
-
## Common issues
25
-
26
-
### Difficulties with Stack and `Paths_` modules
24
+
### Problems with multi component (tests suites, executables, benchmarks) support using stack
27
25
28
-
These are known to be somewhat buggy at the moment: <https://github.com/haskell/haskell-language-server/issues/478>.
29
-
This issue should be fixed in Stack versions >= 2.5.
26
+
Due to some limitations in the interaction between HLS and stack, there are some issues in projects with a main library and executables, test suites or benchmarks:
27
+
- The stack project has to be built succesfully *before* loading it with HLS to get components other than the library work.
28
+
- Changes in the library are not automatically propagated to other components, especially in the presence of errors in the library, so you have to restart HLS to get those components correctly loaded. The usual symptom is the editor showing errors like `Could not load module ...` or `Cannot satisfy -package ...`
29
+
- See https://github.com/haskell/haskell-language-server/issues/366 for more info about.
30
+
## Common issues
30
31
31
32
### Problems with dynamic linking
32
33
33
34
As haskell-language-server prebuilt binaries are statically linked, they don't play well with projects using dynamic linking.
34
35
An usual symptom is the presence of errors containing `unknown symbol` and it is typical in arch linux, where a dynamically linked version of ghc is used.
35
36
36
-
The workaround is to use a version of haskell-language-server compiled from source with `-dynamic` enabled`. See more details [here](https://github.com/haskell/haskell-language-server/issues/1160#issuecomment-756566273).
37
+
The workaround is to use a version of haskell-language-server compiled from source with the ghc option `-dynamic` enabled. See more details [here](https://github.com/haskell/haskell-language-server/issues/1160#issuecomment-756566273).
38
+
39
+
### Problems with Template Haskell
40
+
41
+
Due to how Template Haskell code is evaluated at compile time and some limitations in the interaction between HLS and GHC, the loading of modules using TH can be problematic.
42
+
43
+
The errors thrown are usually related to linking and usually make HLS crash: `Segmentation fault`, `GHC runtime linker: fatal error`, etc
44
+
45
+
A workaround which has helped in some cases is to compile HLS from source with the ghc option `-dynamic` enabled, as in the previous issue.
46
+
47
+
We have a [dedicated label](https://github.com/haskell/haskell-language-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+template+haskell+related%22) in the issue tracker and an [general issue](https://github.com/haskell/haskell-language-server/issues/1431) tracking support for TH.
37
48
38
49
## Troubleshooting the server
39
50
@@ -56,11 +67,17 @@ sent, or if there are any errors.
56
67
57
68
To get a more verbose, also pass `--debug` to the executable.
58
69
70
+
### Identify which plugin could be the cause of the issue.
71
+
72
+
Sometimes the issue is produced by one of the plugins included in HLS. To diagnose that and help to trace the final cause one possible strategy is simple disable all plugins, check if the issue is gone and then enable them selectively until the issue is reproduced again.
73
+
74
+
There is a configuration json snippet which disables all plugins [here](https://github.com/haskell/haskell-language-server/issues/2151#issuecomment-911397030).
75
+
59
76
## Troubleshooting the client
60
77
61
78
Many clients provide diagnostic information about a LSP session.
62
79
In particular, look for a way to get the status of the server, the server stderr, or a log of the messages that the client has sent to the server.
63
80
For example, `lsp-mode` provides all of these (see its [troubleshooting page](https://emacs-lsp.github.io/lsp-mode/page/troubleshooting/) for details).
81
+
For vscode you can read how to access the lsp session log [here])https://github.com/haskell/vscode-haskell#investigating-and-reporting-problems).
64
82
65
-
The most common client-related problem is the client simply not finding the server executable, so make sure that you have the right `PATH` and you have configured
66
-
it to look for the right executable.
83
+
The most common client-related problem is the client simply not finding the server executable or the tools needed to load Haskell code (`ghc`, `cabal`, or `stack`). So make sure that you have the right `PATH` and you have configured the client to look for the right executables.
0 commit comments