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
+42-22
Original file line number
Diff line number
Diff line change
@@ -90,83 +90,97 @@ 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 under the hood by the [hie-bios](https://github.com/mpickering/hie-bios) application.
94
+
In turn, `hie-bios` needs some configuration to identify all files, GHC options, etc., needed to compile a project.
94
95
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
+
There are several ways to provide this configurationto `hie-bios`, detailed below.
96
97
97
-
At the moment, `haskell-language-server` has support to automatically detect your project build configuration to handle most use cases.
98
+
### Implicit configuration
99
+
If no `hie.yaml` file is present, `haskell-language-server` automatically detects your `hie-bios` configuration.
100
+
**For most cases, this works just fine, and is the recommended way.**
98
101
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`
102
+
See [the hie-bios documentation](https://github.com/haskell/hie-bios#implicit-configuration) for more information on implicit configuration.
103
+
104
+
### Explicit, generated configuration
105
+
Maybe using the implicit configuration does not suit you.
106
+
E.g., it does not work, or you prefer to have explicit configuration in your project.
107
+
In that case, you can automatically generate a `hie.yaml` file, using [implicit-hie](https://github.com/Avi-D-coder/implicit-hie):
108
+
109
+
```shell
110
+
gen-hie > hie.yaml # In the root directory of your project
111
+
```
112
+
113
+
### Explicit, manual configuration
114
+
Maybe using the generated `hie.yaml` file does not suit you.
115
+
E.g., it still does not work, or you want to fine-tune the configuration.
116
+
We recommend to start from the `hie.yaml` file generated by `implicit-hie` (see previous section) and modify it to suit your needs.
100
117
101
-
If the automatic detection fails with that error you can configure `hie-bios` using a `hie.yaml` file in the root of the workspace.
102
-
A `hie.yaml` file **explicitly** describes how to setup the environment to compile the various parts of your project.
103
118
For that you need to know what *components* your project has, and the path associated with each one.
104
119
So you will need some knowledge about
105
120
[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
121
107
-
You also can use [implicit-hie](https://github.com/Avi-D-coder/implicit-hie) to automatically generate `hie.yaml` files for
108
-
the most common stack and cabal configurations
122
+
**For a full explanation of how to configure it manually, refer to the [hie-bios documentation](https://github.com/mpickering/hie-bios/blob/master/README.md).**
123
+
124
+
#### Examples of explicit `hie-yaml` configurations
109
125
110
-
For example, to state that you want to use `stack` then the configuration file
111
-
would look like:
126
+
##### Single Stack component
112
127
113
128
```yaml
114
129
cradle:
115
130
stack:
116
131
component: "haskell-language-server:lib"
117
132
```
118
133
119
-
If you use `cabal` then you probably need to specify which component you want
120
-
to use.
134
+
##### Single Cabal component
121
135
122
136
```yaml
123
137
cradle:
124
138
cabal:
125
139
component: "lib:haskell-language-server"
126
140
```
127
141
128
-
If you have a project with multiple components, you can use a cabal-multi
Project source code should load without `hie.yaml` setup.
111
+
Refer to the [HLS project configuration guidelines](../configuration.md#configuring-your-project-build) as they also apply to the HLS project itself.
112
112
113
-
In other cases:
114
-
115
-
1. Check if `hie.yaml` (& `hie.yml`) files left from previous configurations.
116
-
117
-
2. If the main project needs special configuration, note that other internal subprojects probably also would need configuration.
118
-
119
-
To create an explicit configuration for all projects - use [implicit-hie](https://github.com/Avi-D-coder/implicit-hie) generator directly:
120
-
121
-
```shell
122
-
gen-hie > hie.yaml # into the main HLS directory
123
-
```
124
-
125
-
that configuration should help.
126
-
127
-
3. Inspect & tune configuration explicitly.
128
-
129
-
[Configuring project build](../configuration.md#configuring-your-project-build) applies to HLS project source code loading just as to any other.
130
-
131
-
Note: HLS may implicitly detect codebase as a Stack project (see [hie-bios implicit configuration documentation](https://github.com/haskell/hie-bios/blob/master/README.md#implicit-configuration)). To use Cabal, try creating an `hie.yaml` file:
113
+
Note: HLS implicitly detects the HLS codebase as a Stack project (since there is a `stack.yaml` file).
114
+
If you want HLS to use Cabal, create this `hie.yaml` file at the root of the project:
132
115
133
116
```yaml
134
117
cradle:
135
118
cabal:
136
119
```
137
120
138
-
### Manually testing your hacked HLS
139
-
If you want to test HLS while hacking on it, follow the steps below.
140
-
141
-
#### Using Cabal
121
+
## Manually testing your hacked HLS
122
+
If you want to test HLS while hacking on it (you can even test it on HLS codebase itself, see previous section), you need to:
142
123
143
-
- Whenever you want to build HLS, call `cabal install exe:haskell-language-server --overwrite-policy=always`.
144
-
At the end of the output you will find the path the HLS executable was installed to, i.e.:
124
+
1. (Once) Find the path to the hacked HLS you build
125
+
2. (Once) Configure your editor to use it
126
+
3. (Every time you change the HLS code) Rebuild HLS
127
+
4. (Every time you change the HLS code) Restart the LSP workspace
Note that unless you change the GHC version or the HLS version between builds, the path should remain the same, this is why you need to set it only once.
154
131
155
-
In this example output, the path would be `/home/user/.cabal/bin/haskell-language-server`.
- Open some codebase on which you want to test your local HLS in your favorite editor (it can also be the HLS codebase itself: see previous section for configuration)
158
-
- Configure this editor to use your custom HLS executable by using the path you obtained previously.
159
-
- Restart HLS in your project:
160
-
- With VS Code: Press `CTRL + Shift + P` and type `Haskell: Restart Haskell LSP Server`
When using VS Code you can set up a test project to use a specific HLS executable:
150
+
#### VS Code
151
+
When using VS Code you can set up each project to use a specific HLS executable:
166
152
167
153
- If it doesn't already exist in your project directory, create a directory called `.vscode`.
168
-
- In the `.vscode` directory create a file called `settings.json` with the below contents. The path used here is the one obtained by using the `cabal` install command.
169
-
154
+
- In the `.vscode` directory create a file called `settings.json` with the below contents.
- With Stack: `stack build haskell-language-server:exe:haskell-language-server`
172
+
- With Cabal: `cabal build exe:haskell-language-server`
177
173
178
-
- Open some codebase on which you want to test your local HLS in your favorite editor (it can also be the HLS codebase itself: see previous section for configuration)
179
-
- Configure this editor to use your custom HLS executable
180
-
- To obtain the path to your local HLS executable: `$(stack path --dist-dir)/build/haskell-language-server/haskell-language-server`
0 commit comments