External editors and the language server

Last updated:

jhdl-lsp is JanusHDL's VHDL language server. It runs JanusHDL's own analyzer on the whole design in your workspace and speaks the Language Server Protocol (LSP), so any editor with an LSP client gets:

• Diagnostics while you type: syntax, names and types, VHDL-1993 to VHDL-2019, each with its rule name (undeclared, type-mismatch, ...) and LRM section, exactly as jhdl reports them. What JanusHDL does not support yet is shown as information, not as an error in your code.
• Go to definition, also into the IEEE and standard packages (their sources are written to a temporary folder, read-only).
• Hover: the declaration of the name under the cursor, and where it is.
• Find references across the design.
• Document symbols (the outline): design units, subprograms, types, signals, constants, variables, labels.

Your editor starts the server itself. It needs to find jhdl-lsp: put JanusHDL's bin folder on your PATH (Installing), or give the editor the program's full path.

How the server finds your design

Names resolve across files and libraries, so the server analyzes every file of the design, in an order their dependencies allow. It finds the files, and their libraries, in the first of these ways that applies:

1. A project or a file list. The file the projectFile option names (relative to the workspace folder); else a JanusHDL project (.jhdlproj) in the workspace's top folder; else a file list jhdl.f there. - A project is used as jhdl run and the window use it (Projects): its sources in their libraries and order, each as its own VHDL version, its library's or the project's, with the project's compatibility mode, PSL comments, conditional analysis identifiers and rule levels. With several projects in the folder, the first by name is used; the server's log says which, and that projectFile chooses another. - A file list is the format jhdl -f reads (File lists): library NAME lines choose the library of the files after them, other lines are paths relative to the file list, # starts a comment.

A project that cannot be read (an error in it, or a projectFile that names no file) is reported in the server's log with what is wrong, and the design is found the next way until it is fixed. 2. UVVM. When the workspace is UVVM, or contains it, its compile orders (COMPONENT/script/compile_order.txt, in the order of script/component_list.txt). The testbenches and demos of each component follow in its library. Set the compat option for UVVM (Options). 3. OSVVM. When the workspace is OSVVM (OsvvmLibraries.pro) or one of its libraries (build.pro), its build scripts. The server reads the commands that choose files (library, analyze, include, build, ChangeWorkingDirectory, if and else), answering OSVVM's questions about the tool as a VHDL-2008 simulator. Scripts that do more need a file list. 4. Any folder. Every .vhd and .vhdl file in the workspace, leaving out what .gitignore excludes. A file is in library NAME if a folder on its path is called NAME and some file says library NAME;; otherwise it is in work.

A file you open that is not part of the design is analyzed into work.

Without a project, every file is analyzed as the one VHDL version the std option gives, and in compatibility mode if the compat option asks for it.

Options

The editor sends these as initialization options:

What the server sees, without an editor

jhdl-lsp --check path/to/design [--project path/to/design.jhdlproj] [--compat]

analyzes the folder as the server would, prints every diagnostic, and ends with a summary that says how it found the design, here from a project in the folder:

2 files from .\counter.jhdlproj: 0 errors, 0 warnings, 0 not supported yet (0.3 s)

--project names a project or a file list to use, as the projectFile option does; --compat analyzes in compatibility mode, as the compat option does.

The exit code is 1 if there are errors. It is a quick way to check that the server finds your files and libraries before you set up an editor, or to check a whole folder in CI.

jhdl-lsp --order FILES.f prints a file list with its files in dependency order (Analysis order).

Setting up your editor

Visual Studio Code

The JanusHDL VHDL extension starts jhdl-lsp for .vhd, .vhdl, .vht and .vho files and adds VHDL highlighting. Its settings:

The command JanusHDL: Restart the language server restarts it, after you change the file list, for example.

Neovim (0.11 and later)

vim.lsp.config('JanusHDL', {
  cmd = { 'jhdl-lsp' },
  filetypes = { 'vhdl' },
  root_markers = { 'jhdl.f', '.git' },
  init_options = { std = '08' },
})
vim.lsp.enable('JanusHDL')

Helix

In languages.toml:

[language-server.JanusHDL]
command = "jhdl-lsp"

[[language]]
name = "vhdl"
language-servers = ["JanusHDL"]

Sublime Text

In the settings of the LSP package:

"clients": {
  "JanusHDL": {
    "enabled": true,
    "command": ["jhdl-lsp"],
    "selector": "source.vhdl"
  }
}

Emacs (eglot)

(add-to-list 'eglot-server-programs '(vhdl-mode "jhdl-lsp"))

Notepad++

With the NppLspClient plugin, add a server for the VHDL language with the command jhdl-lsp.

Other editors

Any editor with an LSP client works: start jhdl-lsp (it talks over its standard input and output) for VHDL files, with the workspace's top folder as the root, and pass projectFile and std as initialization options if you need them.

How it works

When it starts, the server analyzes the whole design; for a library the size of UVVM this takes a few seconds. After that, an edit is analyzed when you pause typing (a quarter of a second), together with every file that uses what the edited file declares, and before the server answers a request about that file, so that its answers always match the text you see. Positions are exchanged in UTF-16 columns, or in bytes when the editor offers UTF-8.

The window's own editor

The JanusHDL window has a code editor of its own, with the same analyzer's diagnostics as you type (The code editor). Use whichever you prefer; many people keep their usual editor for writing code and use the window for running and debugging, where a click on a message or a driver opens the place in the window's editor.