[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

New editor integrations for Debian packaging files (LSP support)



Hi

Sent to d-devel and d-mentors, since the members of both lists are the target audience. If you reply, please consider whether both lists should see the message (and prune the recipient list accordingly as necessary).


In response to a recent thread on debian-devel about editor support for Debian packaging files, I have spend some time providing better experience when working with Debian packaging files. Concretely, I have added a Language Server (per LSP spec) to `debputy` that supports files like "debian/control" and "debian/copyright" (machine readable variant only).


With this language server and a LSP capable editor, you will get:


 * Online diagnostics (in editor linting result).
   - Instant gratification for common or simple errors. No need to wait
     for a package build to run `lintian`. Also, if `debputy` knows a
     solution, it will provide quick-fixes for the issue.


 * Online documentation ("hover docs") for relevant fields and values.
   - You do not have to remember what things mean nor context switch
     to look up documentation! It is served directly in your editor
     when you request it via your editors "hover doc" feature.


 * Context-based completion suggestions for known value or fields.
   - As an example, the completion will not suggest completion for a
     field already in the current stanza of debian/control (since
     that would lead to an error).


 * Automatic pruning of trailing white spaces!
   - If your editor supports the "on save" feature, the language server
     will trim away trailing white space in the Debian packaging files.
     (it is a small thing, but it is still one paper cut less!)


The diagnostics can also be used without the language server. Which can be used for CI or when you do not have an LSP capable editor. It works _without_ building the package first (unlike lintian) and it does have an --auto-fix option (also, unlike lintian). On the other hand, the diagnotics/linter is not a replacement for lintian. The `debputy` LSP/Linter is solely aimed at providing editor support Debian packaging files, which is a much narrower scope than lintian.


For those interested, there are some screenshots from emacs with this language server at: https://people.debian.org/~nthykier/lsp-screenshots/

As mentioned, any LSP capable editor should work. Which includes:
 * neovim
 * vim (with `vim-youcompleteme`)
 * atom/pulsar
 * VS Code (unsurpsingly, since Microsoft created the LSP spec)
 * Eclipse (via the `lsp4e` plugin)
 * ... and many other editors


# Getting started

To use these new features, you will need:

    # Preferably, 0.1.26 (unstable)
    # Though, dh-debputy/0.1.24 (testing) will do
    $ apt install dh-debputy python3-lsprotocol python3-pygls

    # If you want online spellchecking, then add:
    $ apt install python3-hunspell hunspell-en-us

    # Check if debputy has config glue suggestions for your editor
    # - note: the output may contain additional editor specific
    #   dependencies.
    $ debputy lsp editor-config
    $ debputy lsp editor-config EDITOR_NAME

    # Once your editor is configured correctly, it should start the
    # language server on its own when you open a relevant file.

    # Using the diagnostics without the language server.
    #  - Check --help for additional features.
    $ debputy lint

Additionally, for the editor features, you will need an LSP capable editor and relevant editor configuration glue for said editor. The `debputy lsp editor-config` command will list known editors and `debputy lsp editor-config EDITOR` will provide an example editor glue. These examples are maintained on a "best-effort" basis.

At the moment, `debputy` knows about `emacs` with `eglot` (built-in in emacs/29) and `vim` with `vim-youcompleteme`. For other editors, you will have to figure out the glue config - though, feel free to submit a MR against the `debputy` repo, so others can benefit from it.

If you end up having to do your own editor config glue, you can start the language server via `debputy lsp server` (check `--help` if you need TCP or WS integration).



## Supported files

For the full list, please see `debputy lsp features`. The `diagnostics (lint)` lines also explain where `debputy lint` has support.

Version 0.1.26 of dh-debputy adds support for `debian/tests/control`. For `emacs`, the next version of dpkg-dev-el (RFS'ed in #1068427) is also needed for `debian/tests/control` support.


# Future work

 * There will be bugs. Lots of bugs.
   - Issues and MRs are welcome at
     https://salsa.debian.org/debian/debputy/-/issues
   - BTS bugs (with or without patches) also work. 🙂

 * There are lot more diagnostics that could be triggered.  Feature
   requests welcome (see above).

 * Most of the hover documentation could probably use a review.

 * Most of the editor glue provided via `debputy lsp editor-config`
   should probably end up in packages somehow.

 * All this requires Debian testing or unstable.
   - If you are interested in support for current stable (etc.), please
     see https://salsa.debian.org/debian/debputy/-/issues/76 🙂

 * We should "assign" proper language IDs to some of our packaging
   files. Right now, `debputy` "misuses" the makefile and yaml language
   for Debian specific formats (for `debian/rules` and
   `debian/debputy.manifest`), because those are the IDs that editors
   would or can use for those files.


## Known issues and limitations

 * Some editors (at least emacs and vim) does not seem to integrate
   properly with the language server when no language binding is
   active for the buffer. YMMV for other editors.
   - Vim comes bindings built-in for most files (`debian/tests/control`
     a notable omission)
   - For emacs, you will want `elpa-dpkg-dev-el`. Emacs seems to use the
     major mode as language ID for Debian packaging files. If you use
     your own custom mode, the language server might be become confused.

 * emacs: When using `eglot-ensure` with `debian/changelog` and the
   `debian-changelog-mode`, it triggers a stall (that eventually times
   out) due to some interaction between `imenu` and `eglot`. This is
   involves the pair sending a request to the language server, it did
   not announce support for (bug!). But I am none the wiser if it is
   the mode being set up incorrectly or just `imenu` + `eglot` being
   crazy on their own. If you are an emacs expert, and have time to
   debug this, it would be lovely to get rid of this bug.

 * The editor may still provide its own features on top"of the
   language server. As an example, youcompleteme can suggest
   completions for words that are already used previously in the
   document. These suggestions appears to come in addition to those
   provided by the language server and its beyond the control of the
   language server. Though the end result is that you may still see
   invalid suggestions in such cases when the editor has two or more
   sources for a given feature.


As mentioned, feedback on this new editor support feature is very welcome. I have also included a small section on troubleshooting below my signature in case it becomes relevant.


I hope you will find this makes Debian packaging files easier to work with!


Best regards,
Niels




# Troubleshooting

A small section on troubleshooting.

## Debugging the language server

Often your editor will have a special window or command for showing the language server logs. Though, you can also re-configure your editor to use the TCP integration. In this case, you start the language server manually a terminal (via `debputy lsp server --tcp`) and the editor will connect to it. This also enables you do use your own wrapper around the language server (such as a python debugger) or do redirects its stderr to a file for later review.


## I do not get feature X / Notes on Editor Feature support

The specification allows a lot of optional features. Most editors only provide a subset of all the features. Depending on the editor, some features may require extra dependencies or special configuration to be supported.

As an example, `emacs` only seems to work with proper major modes active (see Known issues above). Additionally, `emacs` supports only plaintext hover docs out of the box. If you want `markdown` highlighting to work, you have to install `elpa-markdown-mode`.

For vim + vim-youcompleteme, it supports the "semantic tokens" feature, where `debputy` can tell it "this part is a keyword", "this part is a known value" (etc.). However, this requires special configuration to get the highlighting to work (and then, it is added on top of `vim` built-in syntax highlighting, which does not make it easier to understand).

None of the editors have tested so far seemed to have (working) support for "folding ranges" (or, in vim's case, if it does, I did not know how to activate it). The language server will identify multi-line comments in deb822 files and report a folding range for them, so the editor knows it can "squash" into a single line visually.



Reply to: