mirror of
https://github.com/tweag/nickel.git
synced 2024-10-26 11:52:13 +03:00
Rework of the LSP Readme
This commit is contained in:
Yann Hamdaoui
parent
140f41a1e7
commit
2b694899ec
137
lsp/README.md
137
lsp/README.md
@ -1,37 +1,54 @@
|
||||
# Nickel Language Server
|
||||
|
||||
NLS is a language server for the nickel programming language. NLS offer error messages, type hints, and auto-completion right in your favorite LSP-enabled editor.
|
||||
The Nickel Language Server (NLS) is a [language
|
||||
server](https://en.wikipedia.org/wiki/Language_Server_Protocol) for the
|
||||
[Nickel](https://www.nickel-lang.org/) programming language. NLS offers error
|
||||
messages, type hints, and auto-completion right in your favorite LSP-enabled
|
||||
editor.
|
||||
|
||||
## Server
|
||||
|
||||
To be editor independent `nls` is made up of two components the server and possible lsp-client configurations that talk to the server directly.
|
||||
Hence, the server has to be installed separately to the client configuration.
|
||||
NLS is a stand-alone binary. Once built, you must then configure you code editor
|
||||
to use it for Nickel source files. This document covers building NLS and using
|
||||
it in VSCode and (Neo)Vim.
|
||||
|
||||
### Installation
|
||||
## Installation
|
||||
|
||||
The easiest way to install `nls` is using nix. `nls` is installed in the same installation as `nickel`:
|
||||
Three installation methods are proposed: Using Nix flakes (**recommended**),
|
||||
Using Nix without flakes (older Nix versions), or using `cargo` if you already
|
||||
use the `Rust` toolchain and don't want to install Nix.
|
||||
|
||||
### Using Nix (flakes)
|
||||
|
||||
To enter a shell with `nickel` and `nls` run
|
||||
The easiest way to install `nls` is using [Nix](https://nixos.org/).
|
||||
|
||||
```
|
||||
nix shell github:tweag/nickel
|
||||
```
|
||||
**Important**: the following of this section assumes that you have a flake-enabled
|
||||
Nix (>= 2.4) and the experimental features `flakes` and `nix-command` enabled.
|
||||
At the time of writing, the current stable version of Nix is flake-enabled. If
|
||||
you haven't enabled any experimental feature globally or don't know what it is
|
||||
even about, just append `--experimental-features "flakes nix-command"` to all of
|
||||
the following commands.
|
||||
|
||||
To install `nickel` and `nls` into your profile run
|
||||
- *Global installation*: if you want to use `nls` on a regular basis, this is
|
||||
what you want to do. To have `nickel` and `nls` available globally, add them
|
||||
into your profile:
|
||||
```
|
||||
nix profile install github:tweag/nickel
|
||||
```
|
||||
- *Shell*: Try out for the time of a session. To be dropped in a shell with the
|
||||
`nickel` and `nls` commands available, run:
|
||||
```
|
||||
nix shell github:tweag/nickel
|
||||
```
|
||||
- *Local build*: if you just wand to build `nickel`
|
||||
and `nls` without installing them:
|
||||
```
|
||||
# The executables will be placed in ./result/bin/
|
||||
nix build github:tweag/nickel
|
||||
```
|
||||
|
||||
```
|
||||
nix profile install github:tweag/nickel
|
||||
```
|
||||
### Using Nix (without flakes)
|
||||
|
||||
To build the `nickel` and `nls` executables run
|
||||
|
||||
```
|
||||
# The executables will be placed in ./result/bin/
|
||||
nix build github:tweag/nickel
|
||||
```
|
||||
|
||||
Alternatively to install without nix flakes using nix run:
|
||||
Alternatively, you can insall `nickel` and `nls` globally on older Nix versions
|
||||
without flakes via `nix-env`:
|
||||
|
||||
```
|
||||
git clone https://github.com/tweag/nickel.git
|
||||
@ -39,51 +56,73 @@ cd nickel
|
||||
nix-env -f . -i
|
||||
```
|
||||
|
||||
## Client
|
||||
### Using Cargo
|
||||
|
||||
If you already have a working `cargo` installation, you can make `nls` available
|
||||
globally (it will be built and stored inside the repository, though) without
|
||||
Nix:
|
||||
|
||||
```
|
||||
git clone https://github.com/tweag/nickel.git
|
||||
cd nickel/lsp/nls
|
||||
cargo install --path .
|
||||
```
|
||||
|
||||
## Interfacing with editors
|
||||
|
||||
Once the `nls` binary is available, you can proceed with the configuration of
|
||||
your editor.
|
||||
|
||||
### VS Code
|
||||
|
||||
NLS is currently not available through the vscode marketplace. In the meantime, it can be built using Nix.
|
||||
#### Build the extension
|
||||
|
||||
Either using the command line (you need to have the [`jq`](https://stedolan.github.io/jq/) command available)
|
||||
NLS is currently not available through the vscode marketplace, but this
|
||||
repository includes an extension that can be built locally via Nix (cf []()
|
||||
about the Nix setup).
|
||||
|
||||
```
|
||||
code --install-extension $(nix build ./\#vscodeExtension --no-link --json | jq ".[0].outputs.vsix")
|
||||
```
|
||||
|
||||
or in two steps, by first building the extension
|
||||
|
||||
```
|
||||
nix build github:tweag/nickel#vscodeExtension.vsix
|
||||
```
|
||||
|
||||
then installing it using `Extension: Install from VSIX` in the vscode command palette and choosing `./result-vsix/nls-client.vsix`.
|
||||
- One-liner (using the [`jq`](https://stedolan.github.io/jq/) command):
|
||||
```
|
||||
code --install-extension $(nix build ./\#vscodeExtension --no-link --json | jq ".[0].outputs.vsix")
|
||||
```
|
||||
- In two steps, going via VSCode:
|
||||
- Build with Nix:
|
||||
```
|
||||
nix build github:tweag/nickel#vscodeExtension.vsix
|
||||
```
|
||||
- Then, in VSCode, use `Extension: Install from VSIX` in the vscode command
|
||||
palette and choose `./result-vsix/nls-client.vsix`.
|
||||
|
||||
#### Configuration
|
||||
|
||||
The VS Code extension offers three configuration options:
|
||||
|
||||
- `"nls.server.path"`: Path to nickel language server
|
||||
- `"nls.server.trace"`: "Enables performance tracing to the given file"
|
||||
- `"nls.server.debugLog"`: "Logs the communication between VS Code and the language server."
|
||||
- `nls.server.path`: Path to nickel language server
|
||||
- `nls.server.trace`: Enables performance tracing to the given file
|
||||
- `nls.server.debugLog`: Logs the communication between VS Code and the language server.
|
||||
|
||||
### Neovim
|
||||
### (Neo)Vim
|
||||
|
||||
After installing `nickel` and `nls`
|
||||
`nls` is supported in [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig).
|
||||
Using `nvim-lspconfig` setup `nls` like all your other LSP servers as described by the `nvim-lspconfig` ReadMe.
|
||||
#### Neovim builtin LSP
|
||||
|
||||
`nls` is supported in
|
||||
[nvim-lspconfig](https://github.com/neovim/nvim-lspconfig). Using
|
||||
`nvim-lspconfig` setup `nls` like all your other LSP servers as described by the
|
||||
`nvim-lspconfig` ReadMe.
|
||||
|
||||
```lua
|
||||
require('lspconfig')["nickel_ls"].setup {}
|
||||
```
|
||||
|
||||
### Neo(Vim) with Coc.nvim
|
||||
### With Coc.nvim
|
||||
|
||||
Add an `nickel_ls` entry to your configuration. Type `:CocConfig` in Neovim (or edit `coc-settings.json`) and add:
|
||||
|
||||
Add the `nickel_ls` `JSON` object to your `:CocConfig`/`coc-settings.json`.
|
||||
```
|
||||
{
|
||||
"languageserver": {
|
||||
// Your other language servers configuration
|
||||
// ...,
|
||||
"nickel_ls": {
|
||||
"command": "nls",
|
||||
// You can enable performance tracing with:
|
||||
@ -94,7 +133,11 @@ Add the `nickel_ls` `JSON` object to your `:CocConfig`/`coc-settings.json`.
|
||||
"filetypes": [
|
||||
"ncl"
|
||||
]
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Emacs
|
||||
|
||||
TODO
|
||||
|
||||
Loading…
Reference in New Issue
Block a user