Support for many languages is included in ycmd using various completion engines.
Not all are supported out of the box in Debian though. The following provides
an overview about which languages are supported and/or need additional packages
and which are currently not supported.


| Language       | Engine                 | Status                     |
|----------------|------------------------|----------------------------|
| C/C++          | clangd                 | Supported out of the box   |
| C/C++          | libclang1              | Supported out of the box   |
| C/C++          | ccls                   | Supported out of the box*  |
| Python 2 & 3   | python3-jedi           | Supported out of the box   |
| TypeScript     | node-typescript        | Supported out of the box   |
| JavaScript     | node-typescript or tern| Supported out of the box   |
| Fortran        | fortran-language-server| Supported out of the box*  |
| GDScript       | godot3                 | Supported out of the box*  |
| Go             | gopls                  | Supported out of the box   |
| debian/ files  | dh-debputy             | Supported out of the box*  |
| Perl           | perlnavigator          | Supported out of the box*  |
| C#             | OmniSharp-roslyn       | Untested 3rdparty install  |
| Java           | jdt.ls                 | Unsupported                |
| Rust           | rust-analyzer          | Unsupported                |

A few more can be added with 3rdparty installs and `language_server` setting.
See https://github.com/ycm-core/lsp-examples for examples, but note that these
are neither supported by upstream nor by Debian and can be quite buggy.

The languages marked in the status column with a star(*) are not supported
by upstream directly, but integrated via patches from the mentioned examples
repository as generic LSP completers as the needed tools are packaged and
available in Debian.


Configuring ycmd
----------------

Upstream ycmd is intended to be configured by each client individually.
If we refer here to a config option it will be the one named in
`/usr/lib/ycmd/ycmd/default_settings.json`, but do NOT modify that file –
desperate what its name suggests it will be ignored by most clients.
You will have to check the configuration of your client for how the option
is named there, but they are usually quite similar. vim-youcompleteme e.g.
uses `g:ycm_` as prefix so `use_clangd` is `g:ycm_use_clangd` there.


C/C++
-----

The package contains the libclang1-based engine, but prefers (as upstream does)
the newer clangd-based engine if available. Install the `clangd` package for this.
You can disable this preference with the option `use_clangd` set to `0`. If you
want to use a version-specific clangd you need to set `clangd_binary_path`
(A fitting versioned clangd will be picked only by default if an unversioned
 clangd is not found).

You can also use `ccls` (via a Debian patch) but you will need to set `use_clang`
and `use_clangd` to `0` and – of course – install the `ccls` package (Note that
`use_clang` is a Debian-specific option).


TypeScript & JavaScript completion
----------------------------------

Support for the old Tern-based completer you could install with npm in your
home directory is still included and will be used if present for backward-
compatibility, but upstream recommends and uses for new users the tsserver-
based completer provided by the `node-typescript` package in Debian.


Fortran completion
------------------

You just need to install the `fortran-language-server` package. Note that ycmd
upstream does not officially support this completer. It is also producing
messages on stderr, but it seems like these can be ignored. Note that
diagnostics are only updated when files are saved or opened/closed as
indicated by the README of the fortran-language-server project.


GDScript completion
-------------------

At least since Godot 3.4 the internal language server seems to be enabled by
default, so all you need to do is start Godot before starting YCM. There is
no automatic (re)connect in case you (re)start Godot after YCM, so in this
case you might have to trigger a restart from your editor manually.
In vim-youcompleteme that can be achieved with `:YcmCompleter RestartServer`.
Note that ycmd upstream does not officially support this completer.


Go completion
-------------

You need to install the `gopls` package which this version will prefer to use.
If not available it will try to pick up an installation from your home directory
in `~/go/bin/gopls` with `GO111MODULE=on go get golang.org/x/tools/gopls@latest`
as that was supported in previous versions of this package.


debian/{control,changelog,copyright,rules,debputy.manifest} files completion
----------------------------------------------------------------------------

You just need to install the `dh-debputy` package along with the packages it
suggests (mainly `python3-lsprotocol` and `python3-pygls`); the needed
ycm_language_server settings are built-in via a Debian-specific patch.

Depending on your editor you may need additional settings to e.g. have certain
files recognized correctly.  See `debputy lsp editor-config`. Note that ycmd
upstream does not support this Debian-centric completer. Note also that files
like `debian/rules` (make) and `debian/debputy.manifest` (yaml) have generic
file types for which debputy will be loaded, but not offer generic support.
This also means that if you have configured other language servers for these
file types they will be used instead.


C# completion
-------------

You will need at least `mono` and `OmniSharp.exe` from the omnisharp-roslyn project.
A patch is included to allow the exe to be placed in `/usr/local/bin`, but this
completion is currently not tested for Debian. Feel free to provide feedback
if you made it work.


Java completion
---------------

The jdt.ls engine is currently not packaged in Debian so far and even
supporting unpackaged versions seems difficult. If you are interested and
willing to supply a patch you are more than welcome.


Rust completion
---------------

rust-analyzer is not being available in Debian so far,
so Rust completion is currently not tested nor supported in Debian.
If you are interested and willing to supply a patch you are more than welcome.
