Add Editor Setup Instructions for Neovim

[sabine]

We have editor Setup instructions for VSCode, Emacs, and Vim. However we keep encountering Neovim users who tell us how it was not obvious how to set up OCaml support (too many choices?).

It would be great if we had some instructions in the Get Started > Editor Setup pages.

ETA: relevant file: https://github.com/ocaml/ocaml.org/blob/main/data/tutorials/getting-started/2_00_editor_setup.md

[daemonfire300]

FYI: Regarding ocamlformat, my experience was and it always bit me, you have to have https://github.com/ocaml-ppx/ocamlformat/blob/main/.ocamlformat a .ocamlformat in your project. Just having ocamlformat installed and registered did not suffice. At least that was my experience, without it, it does not assume some default. Maybe this has changed in the meantime.

[beajeanm]

From my point of view, there is nothing special about ocaml in neovim, it's all about how you configure neovim to be a good dev environment, but if it can help, I've done this: https://github.com/beajeanm/neovim-ocaml-quickstart.
It should give a good start to anybody needing a quick way to get up and running with neovim.

[edwintorok]

For some reason ocamlformat doesn't get called by the default vim.lsp.formatexpr, but rebinding gq to call vim.lsp.buf.format works (or using a separate plugin like you did).

A separate package manager is not strictly needed, especially that the latest version of NeoVim includes the equivalent of impatient.nvim to cache Lua code (e.g. if you're already using git to track your config files, then you can use git submodules to track plugins):

git clone https://github.com/neovim/nvim-lspconfig $HOME/.config/nvim/pack/nvim/start/nvim-lspconfig
git clone https://github.com/nvim-treesitter/nvim-treesitter $HOME/.config/nvim/pack/nvim/start/nvim-treesitter -b main

There is still quite a bit of boilerplate to enable LSP in NeoVim (but that applies to all languages), once you have a basic framework you can extend it to add OCaml support with just a couple of lines.

Here is a fully working config:

.config/nvim/init.lua

-- LSP {{{1

-- LSP: OCaml-specific configuration {{{2

-- enable configured language servers
-- you can find server configurations from lsp/*.lua files
local lsps = {
    'ocamllsp',
}
-- }}}

-- LSP: Optional: enable more OCaml-LSP features {{{2
vim.lsp.config('ocamllsp', {
    settings = {
        codelens = { enable = false },
        inlayHints = { hintPatternVariables = true, hintLetBindings = false, hintFunctionParams = true },
        syntaxDocumentation = { enable = true },
    }
})
-- }}}

-- LSP: generic configuration {{{2
-- :h lsp-config
-- enable lsp completion
vim.api.nvim_create_autocmd("LspAttach", {
    group = vim.api.nvim_create_augroup("UserLspAttach", { clear = true }),
    callback = function(args)
        local client = vim.lsp.get_client_by_id(args.data.client_id)

        if not client then
            return
        end

        -- Enable auto-completion. Note: Use CTRL-Y to select an item. |complete_CTRL-Y|
        if client.server_capabilities.completionProvider then
            vim.lsp.completion.enable(true, client.id, args.buf, { autotrigger = true })
        end

        if client.server_capabilities.inlayHintProvider then
            vim.lsp.inlay_hint.enable(true)
        end

        if client.server_capabilities.foldingRangeProvider then
            local win = vim.api.nvim_get_current_win()
            vim.wo[win][0].foldexpr = 'v:lua.vim.lsp.foldexpr()'
        end

       -- vim.bo[args.buf].formatexpr = 'v:lua.vim.lsp.formatexpr()'
       -- workaround for lsp.formatexpr not working with ocamllsp, but calling buf.format works
       vim.keymap.set({'n', 'x'}, 'gq', '<cmd>lua vim.lsp.buf.format({async = true})<cr>')
    end,
})

-- Avoid the buffer jumping when LSP shows warnings
vim.wo.signcolumn = "yes:1" -- always show sign column

vim.lsp.enable(lsps)
-- }}}

-- LSP: generic diagnostic configuration {{{2
-- Virtual lines are useful for long error messages
-- See :h vim.diagnostic.Opts
vim.diagnostic.config {
    severity_sort = true,
    float = { border = 'rounded', source = 'if_many' },
    underline = { severity = vim.diagnostic.severity.ERROR },
    virtual_text = {
        source = 'if_many',
        spacing = 2,
        current_line = true,
    },
    virtual_lines = {
        current_line = true
    }
}

-- }}}

-- }}}

-- Tree-sitter configuration {{{1

-- Tree-sitter: OCaml specific configuration {{{2
local treesitter_langs = {
 'menhir', 'ocaml', 'ocaml_interface', 'ocamllex'
}
-- }}}

-- Tree-sitter: generic configuration {{{2
require('nvim-treesitter').install(treesitter_langs)

-- See https://github.com/nvim-treesitter/nvim-treesitter/tree/main?tab=readme-ov-file#highlighting
-- This is a pcall, because not all filetypes have treesitter support
vim.api.nvim_create_autocmd('FileType', {
    callback = function() pcall(vim.treesitter.start) end,
})
-- }}}

-- }}}

-- Optional: OCaml indentation is usually 2 {{{1
vim.api.nvim_create_autocmd('FileType', {
    pattern = "ocaml",
    callback = function(_)
        vim.bo.shiftwidth = 2
    end
})
-- }}}

The parts the are OCaml specific:

• declaring the appropriately named LSP and tree-sitter configuration names to use
• adding the ocamlformat workaround

You can then enable various features that are not on by default (inlay hints, virtual text/lines), change the default indent depth, but that is all optional.

Probably needs a bit more documentation on what LSP features are actually available and how to enable/use them on nvim (e.g. the default the keybindings are documented in the NeoVim manual, but might be useful to show that gra brings up the code action menu, which, depending on context can allow you to create an mli/etc.)

It might also be possible to do this without using any plugins (if you are a minimalist), e.g by copying the ocamllsp.lua to .config/nvim/lsp/, but currently that file has a few dependencies on nvim-lspconfig itself for some utility functions.

In the past this required a lot more configuration, but newer versions of NeoVim incorporated more LSP features (e.g. the lsp/<file>.lua is fairly recent).

[chrstntdd]

There's a few moving pieces to get right here. I have settled on a config that's been adapted from kickstart.nvim and @dmmulroy's neovim config as well as some other community members.

First, there's general neovim configuration you will want such as having treesitter setup properly and configured to have Ocaml support so you get syntax highlighting for .ml and .mli files ref

Next is LSP configuration.

With the recent changes in neovim's LSP setup introduced in version 0.11, I ended up having to not use Mason (LSP package manager) to install the LSP itself, but rather rely on installing ocaml-lsp-server via opam. This is a good thing as it is likely to have conflicts between the ocaml-lsp-server version from Mason and the latest one that you'd want for a new project.

There are plenty of ways to do this, but I ended up following the kickstart config to define a separate entry (others) on the lsp config object and then enabling them explicitly

From what I could tell, it ended up being the manual_install = true option on the config that got it all working properly.

Last is setup for each individual project.

My workflow has been:

1. Create the project with dune init project $name

2. Setup the switch with the latest compiler with opam switch create . 5.3.0 --deps-only

3. Install dev deps with opam

     opam install dune ocaml-lsp-server ocamlformat

4. Create an .ocamlformat file at the root of the project with the matching version to what was installed

    echo "version = 0.27.0" > .ocamlformat

5. Build with dune build

6. Open neovim and check for the proper LSP integration, format on save, and syntax highlighting

ocaml-nvim-setup-demo.mov

[edwintorok]

• adding the ocamlformat workaround

I figured out why ocamlformat doesn't work by default with the LSP.

NeoVim binds gq to formatexpr if the LSP supports textDocument/rangeFormatting, but ocaml-lsp doesn't support that (according to ocaml/ocaml-lsp#89 (comment) requires ocaml-ppx/ocamlformat#1188, but that feature got removed from ocamlformat ocaml-ppx/ocamlformat#2333.

NeoVim does detect that textDocument/formatting is supported (formatting an entire file), and thus calling vim.lsp.buf.format() works, but there is no default keybinding for it.

Following neovim/neovim#35478 (reply in thread) and the conventions in https://github.com/kana/vim-textobj-entire a possible keybinding could be gqae :

vim.keymap.set({'n', 'x'}, 'gqae', '<cmd>lua vim.lsp.buf.format({async = false})<cr>')

(or you can configure formatting on save, but I usually don't like reindenting files if I don't explicitly intend to, because then reformatting changes get mixed with regular changes. Instead I've configured my version control system to fix up formatting with jj fix and ocamlformat)

[edwintorok]

Some small suggestions:

There are plenty of ways to do this, but I ended up following the kickstart config to define a separate entry (others) on the lsp config object and then enabling them explicitly

Are you sure want to use dune exec ocamllsp, and not opam exec ocamllsp? (or dune tools exec ocamllsp if you're using the preview version of dune)

5. Build with dune build

dune build @check is usually enough to create the files needed by the LSP, and is faster on large projects.
You could also run it in watch mode (in a separate terminal): dune build @check --watch, and then you can avoid the No config found for file <somenewfile.ml>. Try calling 'dune build' error every time you create a new module (you still have to save the file at least once).

[chrstntdd]

Are you sure want to use dune exec ocamllsp, and not opam exec ocamllsp? (or dune tools exec ocamllsp if you're using the preview version of dune)

What's the difference between the two?

dune build @check is usually enough to create the files needed by the LSP, and is faster on large projects.
You could also run it in watch mode (in a separate terminal): dune build @check --watch, and then you can avoid the No config found for file <somenewfile.ml>. Try calling 'dune build' error every time you create a new module (you still have to save the file at least once).

Oh that's a good call. That would probably be a good option for an autocommand, yeah?