From 65dd29157d6e035136d4f65ee6b1827262d945fd Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Mon, 20 Dec 2021 17:23:32 +0000 Subject: [PATCH 1/3] Rework troubleshooting section, add basic explainer This is an attempt to make the troubleshooting doc a bit better structured. It's a bit lacking in concrete details for some of the common problems (because I forget exactly how they mainfest), but I hope that we can beef this up as things come up. I also added a short explainer doc which explains some of the key concepts. --- .github/ISSUE_TEMPLATE/bug_report.md | 35 ++---- docs/conf.py | 3 +- docs/index.rst | 3 +- docs/installation.md | 2 + docs/troubleshooting.md | 172 ++++++++++++++++++++------- docs/what-is-hls.md | 58 +++++++++ 6 files changed, 201 insertions(+), 72 deletions(-) create mode 100644 docs/what-is-hls.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 5674ee4522..c986cee430 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -8,17 +8,19 @@ assignees: '' --- ### Your environment Which OS do you use: -Which lsp-client do you use: - +Which LSP client (editor/plugin) do you use: + Describe your project (alternative: link to the project): @@ -32,26 +34,5 @@ Describe your project (alternative: link to the project): ### Include debug information -Execute in the root of your project the command `haskell-language-server-wrapper --debug .` and paste the logs here: -(if you are using the vscode extension check the executable location [here](https://github.com/haskell/vscode-haskell#downloaded-binaries)) -
- -Debug output: - - -``` - -``` -
- -Paste the logs from the lsp-client, you can check instructions about for VS Code [here](https://github.com/haskell/vscode-haskell#troubleshooting) - -
- -LSP logs: - - -``` - -``` -
+ + diff --git a/docs/conf.py b/docs/conf.py index c029a8f21a..638b1c22fd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,7 +57,8 @@ # ones. extensions = [ 'myst_parser', - 'sphinx_rtd_theme' + 'sphinx_rtd_theme', + 'sphinx.ext.autosectionlabel' ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/index.rst b/docs/index.rst index b8c2405762..7a5ce0df59 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,12 @@ haskell-language-server ======================= -Official haskell ide support via language server (LSP). Successor of `ghcide `_ and `haskell-ide-engine `_. Read the `project's background `_. +Official Haskell Language Server implementation. :ref:`Read more`. .. toctree:: :maxdepth: 2 + what-is-hls features installation supported-versions diff --git a/docs/installation.md b/docs/installation.md index 10bd4435f7..38ccab5931 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -39,6 +39,8 @@ choco install haskell-language-server If you are using Visual Studio Code, the [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell) will automatically download and install `haskell-language-server` for you. +If you need to find the binaries, please consult the [documentation](https://github.com/haskell/vscode-haskell#downloaded-binaries) for the extension. + ## Pre-built binaries There are pre-built binaries available from the [releases page](https://github.com/haskell/haskell-language-server/releases) for Linux, Windows and macOS. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 75acdc4fe6..b28dd3c3d4 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,79 +1,165 @@ # Troubleshooting -## Known limitations +## Help, I have no idea what these words mean -### Limited GHC 9 Support -Currently, GHC 9 support in HLS is in beta stage; some features are unavailable with GHC >= 9.0.1 for the time being. -This situation is expected to be resolved in the near future after all the dependent packages support GHC 9. -See issue [#297](https://github.com/haskell/haskell-language-server/issues/297) for the supported features in GHC 9 and the status of migration progress. +If you are new to the project, you may find it helpful to read the [introduction](./what-is-hls.md) page, which explains some of the terminology used on this page. -### Preprocessor -HLS is not yet able to find project preprocessors, which may result in `could not execute: ` errors. This problem is -tracked in https://github.com/haskell/haskell-language-server/issues/176 and originally comes from https://github.com/mpickering/hie-bios/issues/125 +## Getting help -As a workaround, you need to ensure the preprocessor is available in the path (install globally with Stack or Cabal, provide in `shell.nix`, etc.). +### Where to ask -Example with `tasty-discover`: +Many of the developers are active on [IRC](https://web.libera.chat/?channels=#haskell-language-server). +However, the most direct way to get help is to open an [issue](https://github.com/haskell/haskell-language-server/issues). -```haskell -{-# OPTIONS_GHC -F -pgmF tasty-discover #-} -``` +If you can diagnose whether a problem is with HLS or with the client that you are using, then it is helpful to open an issue in the appropriate repository. +But this can be tricky, and if you're not sure then you can always open one in the HLS repository and we'll help you figure out what's going on. -This returns an error in HLS if 'tasty-discover' is not in the path: `could not execute: tasty-discover`. +### What to include -### Problems with multi component (tests suites, executables, benchmarks) support using stack +Please try and give us as much information as you can! +In particular, the more you can diagnose the problem, the better. -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: -- The stack project has to be built succesfully *before* loading it with HLS to get components other than the library work. -- 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 ...` -- See https://github.com/haskell/haskell-language-server/issues/366 for more info about. -## Common issues +## Basic diagnosis steps -### Problems with dynamic linking +### Quick diagnosis checklist -As haskell-language-server prebuilt binaries are statically linked, they don't play well with projects using dynamic linking. -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. +1. Is the server binary running at all? (check process monitors etc.) If not, there may be a client or installation problem. +2. Is the client connecting to the server? (check for indicators in the editor etc.) If not, there may be a client problem. +3. Is the project being built correctly by HLS? (check for "wrong" compilation errors etc.) If not, there may be a cradle problem. +4. Is basic functionality working? (check hover documentation etc.) If not, there may be a server problem. +5. Are there specific files that exhibit problems? If not, there may be a server problem. -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). +### Finding your `haskell-language-server` binary -### Support for Template Haskell +Several of the diagnostic steps require you to run the actual `haskell-language-server` binary that is installed on your computer. -Template Haskell should work fine in Linux and Windows with the distributed binaries. In Mac Os a dynamically linked binary of HLS is required to avoid segmentation faults. The easiest way to obtain a dynamically linked HLS binary is to build it locally. With cabal install this can be done as follows: +Where the binary is will depend on how you installed HLS. +Consult the [installation](./installation.md) page for help. - cabal update && cabal install haskell-language-server --enable-executable-dynamic +As usual, if you installed HLS with the wrapper, you will want to run `haskell-language-server-wrapper` instead. + +### Getting basic information + +Running `haskell-language-server --probe-tools` will produce useful information, such as the version of HLS that you are using. +Including this in issue reports is helpful. -## Troubleshooting the server +### Working out where the problem is -### Diagnostic mode +The most important thing to figure out is whether you are looking at an issue with the _client_ or the _server_. +This can be tricky to work out: if in doubt, open an issue and we'll help you figure it out. -The `haskell-language-server` executable can be run in diagnostic mode, where it will just try to load modules from your project, printing all of its output to stdout. -This makes it much easier to see what's going on and to diagnose build-related problems. +Typical examples of client issues: +- The wrong server binary is being launched +- Diagnostics are being shown in the wrong place -To do this, simply run the executable directly from your shell in the project root. -You can either run it without an argument, in which case it will load random modules, or with a path, in which case it will load modules in that file or directory. +Typical examples of server issues: +- The server crashes on certain files +- A code action doesn't work the way it's supposed to -### Examining the log +Unclear examples: +- Hover documentation looks wrong (the client might be rendering it wrong, or the server might be sending the wrong thing) +- Missing functionality (the client might not support it, or the server might not support it) + +## Diagnosing problems with the server + +### Examining the server log Most clients will launch `haskell-language-server` with `--logfile` to make it write a log file. Please consult the documentation for your client to find out where this is (or how to set it). The log will contain all the messages that are sent to the server and its responses. -This is helpful for low-level debugging: if you expect a certain action to happen, you can look in the log to see if the corresponding messages are -sent, or if there are any errors. +This is helpful for low-level debugging: if you expect a certain action to happen, you can look in the log to see if the corresponding messages are sent, or if there are any errors. + +To get a more verbose log, you can also pass the `--debug` argument to the server. -To get a more verbose, also pass `--debug` to the executable. +### Reproducing failures on the command-line -### Identify which plugin could be the cause of the issue. +The `haskell-language-server` binary can be with a specific file as an argument, which will make it try and load that file specifically. +If you are having trouble loading a file in the editor, then loading it in this way can help make the failure more obvious and reproducible. -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. +This also provides an easy way to get the logs (with or without `--debug`) if you are having trouble finding them when the server is launched by the client. -There is a configuration json snippet which disables all plugins [here](https://github.com/haskell/haskell-language-server/issues/2151#issuecomment-911397030). +### Plugin-related issues -## Troubleshooting the client +Sometimes the issue is related to one of HLS's plugins. +One strategy for diagnosing this is simply disable all plugins, check if the issue is gone and then enable them selectively until the issue is reproduced again. + +There is a configuration JSON snippet which disables all plugins [here](https://github.com/haskell/haskell-language-server/issues/2151#issuecomment-911397030). + +## Diagnosing problems with the client + +The most important thing to do is to consult the client's documentation. +Usually this will provide some information about troubleshooting. + +For example: +- `lsp-mode` has a [troubleshooting page](https://emacs-lsp.github.io/lsp-mode/page/troubleshooting/) +- The VSCode Haskell extension has a [troubleshooting section](https://github.com/haskell/vscode-haskell#investigating-and-reporting-problems) Many clients provide diagnostic information about a LSP session. 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. -For example, `lsp-mode` provides all of these (see its [troubleshooting page](https://emacs-lsp.github.io/lsp-mode/page/troubleshooting/) for details). -For vscode you can read how to access the lsp session log [here])https://github.com/haskell/vscode-haskell#investigating-and-reporting-problems). + +## Common issues + +### Wrong server binary being used + +HLS needs to be compiled against the same version of GHC as is used in the project. +Normally, we ship binaries for multiple versions and `haskell-language-server-wrapper` selects the correct one. + +If you see an error about HLS being compiled with the wrong version of GHC, then you either need to install the correct one (if you installed it yourself), or there is something going wrong with the wrapper selecting the right HLS binary to launch. + +### Unsupported GHC version + +HLS does not support every GHC version - there are a lot of them! +Please see the [supported versions page](./supported-versions.md) for more information. + +In particular, support for GHC 9.0 and 9.2 is only partial; some features are unavailable with GHC >= 9.0.1, and HLS is not available at all for GHC 9.2. + +### Missing server or build tools 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. + +Usually this will be visible in the client's log. + +### Compilation failures + +Sometimes HLS will simply fail to do anything with a file, or give nonsensical error messages. +The most common cause of this is that HLS is using the wrong `hie-bios` cradle to decide how to build the project (e.g., trying to use `stack` instead of `cabal`). +The server log will show which cradle is being chosen. + +Using an explicit `hie.yaml` to configure the cradle can resolve the problem, see the [configuration page](./configuration.md#configuring-your-project-build). + +### Problems with dynamic linking + +The prebuilt binaries which we provide are statically linked, which means that they don't work well with projects which use dynamic linking. +A typical symptom is the presence of errors containing `unknown symbol`, and it is common for users Arch Linux, which ships a dynamically linked version of `ghc`. + +The workaround is to use a version of HLS compiled from source with the `ghc` option `-dynamic` enabled. See more details [here](https://github.com/haskell/haskell-language-server/issues/1160#issuecomment-756566273). + +### Support for Template Haskell + +Template Haskell should work fine in Linux and Windows with the distributed binaries. +In MacOs a dynamically linked binary of HLS is required, otherwise use of TH can lead to segmentation faults. +The easiest way to obtain a dynamically linked HLS binary is to build it locally. +With `cabal` this can be done as follows: + + cabal update && cabal install haskell-language-server --enable-executable-dynamic + +### Preprocessors + +HLS is [not yet](https://github.com/haskell/haskell-language-server/issues/176) able to find project preprocessors, which may result in `could not execute: ` errors. + +As a workaround, you can ensure the preprocessor is available in `PATH` (install globally with Stack or Cabal, provide in `shell.nix`, etc.). + +Example with `tasty-discover`: + +```haskell +{-# OPTIONS_GHC -F -pgmF tasty-discover #-} +``` + +This returns an error in HLS if `tasty-discover`` is not in the path: `could not execute: tasty-discover`. + +### Problems with multi component support using stack + +Due to some limitations in the interaction between HLS and `stack`, there are [issues](https://github.com/haskell/haskell-language-server/issues/366) in projects with multiple components (i.e. a main library and executables, test suites or benchmarks): +- The project has to be built succesfully *before* loading it with HLS to get components other than the library work. +- 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 in order for those components to be loaded correctly. The usual symptom is the editor showing errors like `Could not load module ...` or `Cannot satisfy -package ...`. diff --git a/docs/what-is-hls.md b/docs/what-is-hls.md new file mode 100644 index 0000000000..a9a0d3704c --- /dev/null +++ b/docs/what-is-hls.md @@ -0,0 +1,58 @@ +# What is haskell-language-server? + +The `haskell-language-server` (HLS) project is an implementation of a server (a "language server") for the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP). +A language server talks to a client (typically an editor), which can ask the server to perform various operations, such as reporting errors or providing code completions. +The advantage of this system is that clients and servers can interoperate more easily so long as they all speak the LSP protocol. +In the case of HLS, that means that it can be used with many different editors, since editor support for the LSP protocol is now widespread. + +## Language Server Protocol basics + +### Servers and clients + +HLS is responsible for actually understanding your project and answering the questions that the client asks of it, such as: what completion items could go here? are there any errors in the project? and so on. +HLS provides [many](./features.md) (but not all) of the features that the LSP protocol supports. + +But HLS only provides the server part of the setup. +In order to actually use it you also need a client (editor). +The client is responsible for managing your interaction with the server: launching it, dispatching commands to it, and displaying or implementing responses. +Some clients will even install the server binaries for you! + +Common clients include: +- VSCode (the reference implementation for a LSP client) +- Emacs, with the `lsp-mode`+`lsp-haskell` or `eglot` packages +- Vim/neovim, with the `coc.vim` or `LanguageClient-neovim` packages +- Kate +- ... and more every day! + +### LSP terminology + +Here are a few pieces of jargon that you may come across in the HLS docs or when discussing problems: + +- *Code action*: A code action is a specific action triggered by a user on a particular region of code. Examples might include "add a type signature to this function". +- *Code lens*: A pre-rendered edit or action shown in the body of the document itself, usually triggered with a click. Examples might include "the type signature for a function, which is actually inserted on click". +- *Completion item*: An item that can be inserted into the text, including its metadata. +- *Diagnostic*: Any information about the project that is shown in the editor, including errors, warnings, and hints from tools such as hlint. +- *Semantic highlighting*: Special syntax highlighting performed by the server. + +## The structure of HLS + +### HLS and its wrapper + +HLS is a binary that must be compiled with the same version of GHC as the project you are using it on. +For this reason it is usually distributed as a _collection_ of binaries, along with a `haskell-language-server-wrapper` executable that selects the correct one based on which version of GHC it thinks you are using. + +In general you can use `haskell-language-server-wrapper` wherever you need to run `haskell-language-server`. + +### HLS plugins + +HLS has a plugin architecture, whereby individual pieces of functionality are provided by smaller packages that just do one thing. +Plugins can also be disabled independently to allow users to customize the behaviour of HLS to their liking. + +These plugins all (currently) live in the HLS repository and are developed in tandem with the core HLS functionality. + +### hie-bios + +HLS needs to know how to build your Haskell project: what flags to pass, what packages to provide, etc. +It gets this information from the build system used by your project (typically `cabal` or `stack`). +The tool used to do this is called [`hie-bios`](https://github.com/haskell/hie-bios). +`hie-bios` calls the strategy it uses to get compilation flags (e.g. "ask `cabal`") a "cradle". From f078a9a104062f7ecd2ea1b5bb629f3dada3b6ff Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Tue, 21 Dec 2021 15:10:50 +0000 Subject: [PATCH 2/3] Update docs/troubleshooting.md Co-authored-by: Pepe Iborra --- docs/troubleshooting.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b28dd3c3d4..662c5ca68b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -128,21 +128,19 @@ The server log will show which cradle is being chosen. Using an explicit `hie.yaml` to configure the cradle can resolve the problem, see the [configuration page](./configuration.md#configuring-your-project-build). -### Problems with dynamic linking +### Template Haskell -The prebuilt binaries which we provide are statically linked, which means that they don't work well with projects which use dynamic linking. -A typical symptom is the presence of errors containing `unknown symbol`, and it is common for users Arch Linux, which ships a dynamically linked version of `ghc`. +**tl;dr** Use a dynamically linked HLS binary. -The workaround is to use a version of HLS compiled from source with the `ghc` option `-dynamic` enabled. See more details [here](https://github.com/haskell/haskell-language-server/issues/1160#issuecomment-756566273). +The easiest way to obtain a dynamically linked HLS binary is to build it locally. With `cabal` this can be done as follows: -### Support for Template Haskell + cabal update && cabal install haskell-language-server --enable-executable-dynamic -Template Haskell should work fine in Linux and Windows with the distributed binaries. -In MacOs a dynamically linked binary of HLS is required, otherwise use of TH can lead to segmentation faults. -The easiest way to obtain a dynamically linked HLS binary is to build it locally. -With `cabal` this can be done as follows: +With `stack` you need to manually add the ghc option `-dynamic`. - cabal update && cabal install haskell-language-server --enable-executable-dynamic +Static binaries use the GHC linker for dynamically loading dependencies when typechecking TH code, and this can run into issues when loading shared objects linked against mismatching system libraries, or into GHC linker bugs (mainly the Mach linker used in Mac OS, but also potentially the ELF linker). Dynamically linked binaries (including`ghci`) use the system linker instead of the GHC linker and avoid both issues. + +Note: HLS binaries prior to 1.6.0 were statically linking `glibc` which is not a supported configuration and has been replaced by `musl`. ### Preprocessors From de4213c73b36a547ce1b2f4603fccd4e68fe756b Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Tue, 21 Dec 2021 16:13:19 +0000 Subject: [PATCH 3/3] Reorganize a bit --- docs/troubleshooting.md | 81 +++++++++++++++++++++++++++-------------- docs/what-is-hls.md | 10 +++-- 2 files changed, 61 insertions(+), 30 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 662c5ca68b..ceb1fd1e3c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -21,13 +21,24 @@ In particular, the more you can diagnose the problem, the better. ## Basic diagnosis steps -### Quick diagnosis checklist +This section lists a few basic diagnostic steps that are almost always helpful. -1. Is the server binary running at all? (check process monitors etc.) If not, there may be a client or installation problem. -2. Is the client connecting to the server? (check for indicators in the editor etc.) If not, there may be a client problem. -3. Is the project being built correctly by HLS? (check for "wrong" compilation errors etc.) If not, there may be a cradle problem. -4. Is basic functionality working? (check hover documentation etc.) If not, there may be a server problem. -5. Are there specific files that exhibit problems? If not, there may be a server problem. +Sometimes these checks may be enough to work out where the problem is. +If not, refer to the sections below about diagnosing problems with the server and client, respectively. +That will also require you to figure out is whether you are looking at an issue with the server or the client. +This can be tricky to work out: if in doubt, open an issue and we'll help you figure it out. + +Typical examples of client issues: +- The wrong server binary is being launched +- Diagnostics are being shown in the wrong place + +Typical examples of server issues: +- The server crashes on certain files +- A code action doesn't work the way it's supposed to + +Unclear examples: +- Hover documentation looks wrong (the client might be rendering it wrong, or the server might be sending the wrong thing) +- Missing functionality (the client might not support it, or the server might not support it) ### Finding your `haskell-language-server` binary @@ -38,27 +49,40 @@ Consult the [installation](./installation.md) page for help. As usual, if you installed HLS with the wrapper, you will want to run `haskell-language-server-wrapper` instead. -### Getting basic information +### Getting basic information about your installation Running `haskell-language-server --probe-tools` will produce useful information, such as the version of HLS that you are using. Including this in issue reports is helpful. -### Working out where the problem is +### Checking that the server is running -The most important thing to figure out is whether you are looking at an issue with the _client_ or the _server_. -This can be tricky to work out: if in doubt, open an issue and we'll help you figure it out. +If the server isn't running at all when you are editing a Haskell file in your project, then that suggests that the client is having difficulty launching it. +Often this means that the client is configured to run the wrong binary, or the correct one is not available in your `PATH`. -Typical examples of client issues: -- The wrong server binary is being launched -- Diagnostics are being shown in the wrong place +The easiest way to check whether the server is running is to use an OS process monitor to see if there is a `haskell-language-server` process running. -Typical examples of server issues: -- The server crashes on certain files -- A code action doesn't work the way it's supposed to +### Checking whether the client is connecting to the server -Unclear examples: -- Hover documentation looks wrong (the client might be rendering it wrong, or the server might be sending the wrong thing) -- Missing functionality (the client might not support it, or the server might not support it) +If the server is running, you should see some kind of indicator in your client. +In some clients (e.g. `coc`) you may need to run a command to query the client's beliefs about the server state. +If the client doesn't seem to be connected despite the server running, this may indicate a bug in the client or HLS. + +### Checking whether the project is being built correctly by HLS + +HLS needs to build the project correctly, with the correct flags, and if it does not do so then very little is likely to work. +A typical symptom of this going wrong is "incorrect" compilation errors being sent to the client. + +If this is happening, then it usually indicates a problem in the server's configuration. + +### Checking whether basic functionality is working + +If everything otherwise seems to be fine, then it is useful to check whether basic functionality is working. +Hover documentation (at least including type signatures) is usually a good one to try. + +### Identifying specific files that cause problems + +If possible, identifying specific files that cause problems is helpful. +If you want to be really helpful, minimising the example can really speed up diagnosis. ## Diagnosing problems with the server @@ -74,10 +98,14 @@ To get a more verbose log, you can also pass the `--debug` argument to the serve ### Reproducing failures on the command-line -The `haskell-language-server` binary can be with a specific file as an argument, which will make it try and load that file specifically. -If you are having trouble loading a file in the editor, then loading it in this way can help make the failure more obvious and reproducible. +The `haskell-language-server` binary can be run from the command line. + +If it is run with a specific file as an argument, it will try and load that file specifically. +If it is run without a specific file, it will try and load all the files in the project. -This also provides an easy way to get the logs (with or without `--debug`) if you are having trouble finding them when the server is launched by the client. +If you are having trouble loading one or many files in the editor, then testing it this way can help make the failure more obvious and reproducible. + +Running HLS from the command-line directly also provides an easy way to get the logs (with or without `--debug`). ### Plugin-related issues @@ -128,9 +156,10 @@ The server log will show which cradle is being chosen. Using an explicit `hie.yaml` to configure the cradle can resolve the problem, see the [configuration page](./configuration.md#configuring-your-project-build). -### Template Haskell +### Static binaries -**tl;dr** Use a dynamically linked HLS binary. +Static binaries use the GHC linker for dynamically loading dependencies when typechecking TH code, and this can run into issues when loading shared objects linked against mismatching system libraries, or into GHC linker bugs (mainly the Mach linker used in Mac OS, but also potentially the ELF linker). +Dynamically linked binaries (including`ghci`) use the system linker instead of the GHC linker and avoid both issues. The easiest way to obtain a dynamically linked HLS binary is to build it locally. With `cabal` this can be done as follows: @@ -138,9 +167,7 @@ The easiest way to obtain a dynamically linked HLS binary is to build it locally With `stack` you need to manually add the ghc option `-dynamic`. -Static binaries use the GHC linker for dynamically loading dependencies when typechecking TH code, and this can run into issues when loading shared objects linked against mismatching system libraries, or into GHC linker bugs (mainly the Mach linker used in Mac OS, but also potentially the ELF linker). Dynamically linked binaries (including`ghci`) use the system linker instead of the GHC linker and avoid both issues. - -Note: HLS binaries prior to 1.6.0 were statically linking `glibc` which is not a supported configuration and has been replaced by `musl`. +Note: HLS binaries prior to 1.6.0 were statically linking `glibc` which is not a supported configuration and has been replaced by `musl`. ### Preprocessors diff --git a/docs/what-is-hls.md b/docs/what-is-hls.md index a9a0d3704c..78a5cee124 100644 --- a/docs/what-is-hls.md +++ b/docs/what-is-hls.md @@ -5,7 +5,7 @@ A language server talks to a client (typically an editor), which can ask the ser The advantage of this system is that clients and servers can interoperate more easily so long as they all speak the LSP protocol. In the case of HLS, that means that it can be used with many different editors, since editor support for the LSP protocol is now widespread. -## Language Server Protocol basics +## Language Server Protocol ### Servers and clients @@ -20,7 +20,7 @@ Some clients will even install the server binaries for you! Common clients include: - VSCode (the reference implementation for a LSP client) - Emacs, with the `lsp-mode`+`lsp-haskell` or `eglot` packages -- Vim/neovim, with the `coc.vim` or `LanguageClient-neovim` packages +- Vim/neovim, with the builtin LSP support or `coc.vim` - Kate - ... and more every day! @@ -34,7 +34,7 @@ Here are a few pieces of jargon that you may come across in the HLS docs or when - *Diagnostic*: Any information about the project that is shown in the editor, including errors, warnings, and hints from tools such as hlint. - *Semantic highlighting*: Special syntax highlighting performed by the server. -## The structure of HLS +## haskell-language-server ### HLS and its wrapper @@ -50,9 +50,13 @@ Plugins can also be disabled independently to allow users to customize the behav These plugins all (currently) live in the HLS repository and are developed in tandem with the core HLS functionality. +See the [configuration page](./configuration.md#generic-plugin-configuration) for more on configuring plugins. + ### hie-bios HLS needs to know how to build your Haskell project: what flags to pass, what packages to provide, etc. It gets this information from the build system used by your project (typically `cabal` or `stack`). The tool used to do this is called [`hie-bios`](https://github.com/haskell/hie-bios). `hie-bios` calls the strategy it uses to get compilation flags (e.g. "ask `cabal`") a "cradle". + +See the [configuration page](./configuration.md#configuring-your-project-build) for more on configuring cradles.