2021-12-13 19:38:30 +03:00
|
|
|
# Nickel Language Server
|
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
The Nickel Language Server (NLS) is a [language
|
2022-03-03 19:12:19 +03:00
|
|
|
server](https://en.wikipedia.org/wiki/Language_Server_Protocol) for the
|
|
|
|
[Nickel](https://www.nickel-lang.org/) programming language. NLS offers error
|
2021-12-28 21:24:26 +03:00
|
|
|
messages, type hints, and auto-completion right in your favorite LSP-enabled
|
|
|
|
editor.
|
|
|
|
|
|
|
|
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
|
|
|
|
|
2021-12-29 11:23:48 +03:00
|
|
|
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.
|
2021-12-28 21:24:26 +03:00
|
|
|
|
|
|
|
### Using Nix (flakes)
|
|
|
|
|
2022-03-03 19:12:19 +03:00
|
|
|
The easiest way to install `nls` is using [Nix](https://nixos.org/).
|
2021-12-28 21:24:26 +03:00
|
|
|
|
|
|
|
**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.
|
|
|
|
|
|
|
|
- *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:
|
2022-08-05 12:55:04 +03:00
|
|
|
|
|
|
|
```console
|
|
|
|
nix profile install github:tweag/nickel
|
|
|
|
```
|
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
- *Shell*: Try out for the time of a session. To be dropped in a shell with the
|
|
|
|
`nickel` and `nls` commands available, run:
|
2022-08-05 12:55:04 +03:00
|
|
|
|
|
|
|
```console
|
|
|
|
nix shell github:tweag/nickel
|
|
|
|
```
|
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
- *Local build*: if you just wand to build `nickel`
|
2022-08-05 12:55:04 +03:00
|
|
|
and `nls` without installing them (the executables will be placed in
|
|
|
|
./result/bin/):
|
|
|
|
|
|
|
|
```shell
|
|
|
|
nix build github:tweag/nickel
|
|
|
|
```
|
2021-12-28 21:24:26 +03:00
|
|
|
|
|
|
|
### Using Nix (without flakes)
|
|
|
|
|
2022-05-21 01:45:10 +03:00
|
|
|
Alternatively, you can install `nickel` and `nls` globally on older Nix versions
|
2021-12-28 21:24:26 +03:00
|
|
|
without flakes via `nix-env`:
|
2021-12-15 22:54:09 +03:00
|
|
|
|
2022-08-05 12:55:04 +03:00
|
|
|
```console
|
2022-03-03 19:12:19 +03:00
|
|
|
git clone https://github.com/tweag/nickel.git
|
2021-12-28 21:24:26 +03:00
|
|
|
cd nickel
|
|
|
|
nix-env -f . -i
|
2021-12-15 22:54:09 +03:00
|
|
|
```
|
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
### Using Cargo
|
2021-12-15 22:54:09 +03:00
|
|
|
|
2022-03-12 12:03:26 +03:00
|
|
|
If you already have a working [`cargo`](https://doc.rust-lang.org/cargo/)
|
|
|
|
installation, you can make `nls` available globally without Nix:
|
2021-12-14 20:40:49 +03:00
|
|
|
|
2022-08-05 12:55:04 +03:00
|
|
|
```console
|
2022-03-12 12:03:26 +03:00
|
|
|
cargo install nickel-lang-lsp
|
2021-12-14 20:37:56 +03:00
|
|
|
```
|
|
|
|
|
2022-03-12 12:03:26 +03:00
|
|
|
**WARNING**: the 0.1.0 version of the NLS crate
|
|
|
|
([nickel-lang-lsp](https://crates.io/crates/nickel-lang-lsp)) doesn't
|
|
|
|
correctly define the name of the binary as `nls`. If you can't find `nls` after
|
|
|
|
a successful cargo installation, try to run `nickel-lang-lsp --version`. If this
|
|
|
|
command is available, you'll have to substitute `nls` for `nickel-lang-lsp` in
|
|
|
|
the instructions that follow.
|
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
## Interfacing with editors
|
2021-12-13 19:38:30 +03:00
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
Once the `nls` binary is available, you can proceed with the configuration of
|
|
|
|
your editor.
|
2021-12-13 19:38:30 +03:00
|
|
|
|
|
|
|
### VS Code
|
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
#### Build the extension
|
2021-12-13 19:38:30 +03:00
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
NLS is currently not available through the vscode marketplace, but this
|
2022-08-05 12:55:04 +03:00
|
|
|
repository includes an extension that can be built locally via Nix (see the
|
|
|
|
section about the Nix setup).
|
2021-12-13 19:38:30 +03:00
|
|
|
|
2023-06-28 12:24:39 +03:00
|
|
|
- One-liner:
|
2022-08-05 12:55:04 +03:00
|
|
|
|
|
|
|
```console
|
2023-06-28 12:24:39 +03:00
|
|
|
code --install-extension $(nix build ./\#vscodeExtension --no-link --print-out-paths)/vscode-nickel.vsix
|
2021-12-28 21:24:26 +03:00
|
|
|
```
|
2022-08-05 12:55:04 +03:00
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
- In two steps, going via VSCode:
|
|
|
|
- Build with Nix:
|
2022-08-05 12:55:04 +03:00
|
|
|
|
|
|
|
```console
|
2022-12-05 19:28:45 +03:00
|
|
|
nix build github:tweag/nickel#vscodeExtension
|
2022-08-05 12:55:04 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
- Then, in VSCode, use "Extension: Install from VSIX" in the vscode command
|
2023-06-28 12:24:39 +03:00
|
|
|
palette and choose `./result/vscode-nickel.vsix`.
|
2021-12-13 19:38:30 +03:00
|
|
|
|
|
|
|
#### Configuration
|
|
|
|
|
2022-08-05 12:55:04 +03:00
|
|
|
The VS Code extension offers three configuration options:
|
2021-12-13 19:38:30 +03:00
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
- `nls.server.path`: Path to nickel language server
|
|
|
|
- `nls.server.trace`: Enables performance tracing to the given file
|
2022-08-05 12:55:04 +03:00
|
|
|
- `nls.server.debugLog`: Logs the communication between VS Code and the language
|
|
|
|
server.
|
2021-12-28 21:24:26 +03:00
|
|
|
|
|
|
|
### (Neo)Vim
|
2021-12-14 20:37:56 +03:00
|
|
|
|
2022-08-05 12:55:04 +03:00
|
|
|
Before proceeding install the [Nickel syntax highlighting
|
|
|
|
plugin](https://github.com/nickel-lang/vim-nickel) using your Vim plugin
|
|
|
|
manager. Without this plugin your LSP client may not start NLS on nickel source
|
|
|
|
files.
|
2022-01-18 20:22:57 +03:00
|
|
|
|
|
|
|
With Vim-Plug:
|
2022-08-05 12:55:04 +03:00
|
|
|
|
2022-01-18 20:22:57 +03:00
|
|
|
```vim
|
|
|
|
Plug 'nickel-lang/vim-nickel'
|
|
|
|
```
|
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
#### Neovim builtin LSP
|
2021-12-14 20:37:56 +03:00
|
|
|
|
2021-12-28 21:24:26 +03:00
|
|
|
`nls` is supported in
|
2022-03-03 19:12:19 +03:00
|
|
|
[nvim-lspconfig](https://github.com/neovim/nvim-lspconfig). Using
|
2021-12-28 21:24:26 +03:00
|
|
|
`nvim-lspconfig` setup `nls` like all your other LSP servers as described by the
|
|
|
|
`nvim-lspconfig` ReadMe.
|
2021-12-14 20:37:56 +03:00
|
|
|
|
|
|
|
```lua
|
|
|
|
require('lspconfig')["nickel_ls"].setup {}
|
|
|
|
```
|
|
|
|
|
2021-12-29 11:23:48 +03:00
|
|
|
#### With Coc.nvim
|
2021-12-28 21:24:26 +03:00
|
|
|
|
2022-08-05 12:55:04 +03:00
|
|
|
Add an `nickel_ls` entry to your configuration. Type `:CocConfig` in Neovim (or
|
|
|
|
edit `coc-settings.json`) and add:
|
2021-12-14 20:37:56 +03:00
|
|
|
|
2022-08-05 12:55:04 +03:00
|
|
|
```jsonc
|
2021-12-14 20:37:56 +03:00
|
|
|
{
|
|
|
|
"languageserver": {
|
2022-08-05 12:55:04 +03:00
|
|
|
// Your other language servers configuration
|
|
|
|
// ...,
|
2021-12-14 20:37:56 +03:00
|
|
|
"nickel_ls": {
|
|
|
|
"command": "nls",
|
2022-08-05 12:55:04 +03:00
|
|
|
// You can enable performance tracing with:
|
|
|
|
// "command": "nls --trace <file>",
|
2021-12-14 20:37:56 +03:00
|
|
|
"rootPatterns": [
|
|
|
|
".git"
|
|
|
|
],
|
|
|
|
"filetypes": [
|
2023-06-21 16:08:48 +03:00
|
|
|
"ncl",
|
|
|
|
"nickel"
|
2021-12-14 20:37:56 +03:00
|
|
|
]
|
2022-08-05 12:55:04 +03:00
|
|
|
}
|
2021-12-14 20:37:56 +03:00
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
2021-12-28 21:24:26 +03:00
|
|
|
|
|
|
|
### Emacs
|
|
|
|
|
2023-04-12 16:34:08 +03:00
|
|
|
Follow the instructions on the the `nickel-mode` [repo](https://github.com/nickel-lang/nickel-mode).
|