README.md

vhdl-ext.el - VHDL Extensions for Emacs

This package provides useful extensions on top of vhdl-mode and vhdl-ts-mode.

• Tree-sitter vhdl-ts-mode support
• Project management
• Improve syntax highlighting
• Find definitions and references
• Auto-completion
• Hierarchy extraction and navigation
• LSP configuration for lsp-bridge, lsp-mode,eglot and lspce
• Support for many linters via flycheck
• Beautify blocks and instances
• Navigate through instances in a entity
• Templates insertion via hydra
• Compilation with colored errors/warnings and jump to file/line
• Improve imenu, detect instances
• Enhanced support for which-func
• Improve code folding via hideshow
• Auto-configure time-stamp
• Port connection utilities

Requirements

• Emacs 29.1+
• Feature-specific binaries

Tree-sitter is optional but recommended and only required if using vhdl-ts-mode for some of the features above.

For more info, see the wiki.

Installation

MELPA

vhdl-ext is available on MELPA.

straight.el

To install it via straight with use-package:

(straight-use-package 'use-package)
(use-package vhdl-ext)

Basic config

The most basic configuration just requires choosing which features you want to load, setup the minor-mode and add it as a hook for vhdl-mode. By default all features are enabled:

;; Can also be set through `M-x RET customize-group RET vhdl-ext':
;; Comment out/remove the ones you do not need
(setq vhdl-ext-feature-list
      '(font-lock
        xref
        capf
        hierarchy
        eglot
        lsp
        lsp-bridge
        lspce
        flycheck
        beautify
        navigation
        template
        compilation
        imenu
        which-func
        hideshow
        time-stamp
        ports))
(require 'vhdl-ext)
(vhdl-ext-mode-setup)
(add-hook 'vhdl-mode-hook #'vhdl-ext-mode)

If installed and loaded via use-package:

(use-package vhdl-ext
  :hook ((vhdl-mode . vhdl-ext-mode))
  :init
  ;; Can also be set through `M-x RET customize-group RET vhdl-ext':
  ;; Comment out/remove the ones you do not need
  (setq vhdl-ext-feature-list
        '(font-lock
          xref
          capf
          hierarchy
          eglot
          lsp
          lsp-bridge
          lspce
          flycheck
          beautify
          navigation
          template
          compilation
          imenu
          which-func
          hideshow
          time-stamp
          ports))
  :config
  (vhdl-ext-mode-setup))

Keybindings

Enabling of vhdl-ext-mode minor-mode creates the following keybindings:

• Features

  • C-M-i vhdl-ext-beautify-block-at-point
  • C-c C-v vhdl-ext-hierarchy-current-buffer
  • C-c C-t vhdl-ext-hydra/body
  • C-c C-f vhdl-ext-flycheck-mode
  • C-c C-u> vhdl-ext-tags-get
  • C-c <f5> vhdl-ext-compile-project-ghdl

• Navigation

  • C-M-f vhdl-ext-forward-sexp
  • C-M-b vhdl-ext-backward-sexp
  • C-M-u vhdl-ext-find-entity-instance-bwd
  • C-M-d vhdl-ext-find-entity-instance-fwd
  • C-M-. vhdl-ext-jump-to-parent-entity
  • C-c M-. vhdl-ext-jump-to-entity-at-point-def
  • C-c M-? vhdl-ext-jump-to-entity-at-point-ref

• Port connections

  • C-c C-c t vhdl-ext-ports-toggle-connect
  • C-c C-c r vhdl-ext-ports-connect-recursively

Features

Tree-sitter

Some of the features that vhdl-ext provides are based either on builtin vhdl-mode Emacs lisp parsing or on tree-sitter vhdl-ts-mode:

• Hierarchy extraction can use both builtin Elisp parsing and tree-sitter
  • Using tree-sitter as a backend is recommended as it is much faster, efficient and accurate
• Tags collection for completion and navigation of definitions and references requires tree-sitter

For information about installation of vhdl-ts-mode check its repo.

Project management

The package provides the variable vhdl-ext-project-alist to select which files belong to a specific project:

(setq vhdl-ext-project-alist
      `(("axi_if_converter" ; Project name
         :root "/home/gonz/Repos/larumbe/axi_if_converter" ; supports remote dirs via Tramp
         :files ("src/my_block.vhd"
                 "src/*.vhd") ; Multiple files can be specified through the glob pattern
         :dirs ("src/tb"
                "-r src/rtl" ; -r to add directories recursively
                "src/syn/*_block"
                "src/**/netlists") ; add all dirs that begin with "src" and end with "netlists"
         :ignore-dirs ("src/ignored_ip")
         :ignore-files ("src/some_ip/ignored_sim_netlist.vhd")
         ;; The ones below are used for GHDL-related features
         :worklib "xil_defaultlib"                     ; Defaults to `work' if not set
         :workdir "library/xil_defaultlib"             ; Output compilation directory for worklib
         :lib-search-path ("/opt/ghdl_Xilinx_lib/")))) ; Extra directories to look for compiled libraries

The different properties for each project entry determine which files will be used for some features of the package, such as completion, xref navigation, hierarchy extraction and compilation.

Syntax highlighting

For configuration information, see the wiki.

Find definitions and references

vhdl-ext provides a builtin xref backend to navigate definitions and references of current project in vhdl-ext-project-alist.

For configuration information, see the wiki.

Auto-completion

Complete with tags from current VHDL project.

For configuration information, see the wiki.

Hierarchy extraction

Hierarchy extraction of entity at current buffer.

For configuration information, see the wiki.

Language Server Protocol

Auto-configure various VHDL language servers for lsp-bridge, lsp-mode, eglot and lspce:

• rust_hdl
• ghdl_language_server
• vhdl-tool
• hdl_checker

For configuration instructions, see the wiki.

Linting

Support via flycheck for the following linters:

• GHDL
• vhdl_lang
• vhdl-tool

For configuration and usage instructions, see the wiki

Beautify blocks and instances

Beautify block and instances at point:

Interactive functions:

• vhdl-ext-beautify-block-at-point: C-M-i
• vhdl-ext-beautify-instance-at-point

Batch-mode functions:

• vhdl-ext-beautify-files
• vhdl-ext-beautify-dir-files: uses tree-sitter if run with prefix arg C-u

Navigation

• Navigate instances inside an entity
• Jump to definition/references of entity at point
• Jump to parent entity

For detailed info see the wiki.

Templates

Snippet selection via hydra.

• vhdl-ext-hydra/body: C-c C-t

Compilation

Provides functions to perform compilations with syntax highlighting and jump to error:

• vhdl-ext-compile-project-ghdl: C-c <f5>

See more info in the wiki.

Imenu

Support detection of instances.

Which-func

Enhanced which-func support: show current block/instance at point in the mode-line

Code folding

Improve code folding via hideshow: add support for if/else/elsif blocks.

Time-stamp

Automatic update of header timestamp after file saving.

• vhdl-ext-time-stamp-mode

For configuration see wiki

Port connections

Toggle connections of ports under instance at point:

• vhdl-ext-ports-toggle-connect: C-c C-c t
• vhdl-ext-ports-connect-recursively: C-c C-c r

Contributing

Contributions are welcome! Just stick to common Elisp conventions and run the ERT suite after testing your changes and before submitting a new PR.

For new functionality add new ERT tests if possible.

Consider sponsoring to help maintaining the project and for the development of new features. Thank you!

Setup

To run the whole ERT test suite change directory to the vhdl-ext root and make sure test-hdl Git submodule has been loaded:

git submodule update --init

Targets

Then run the default target:

$ make

To run a subset of tests (e.g. navigation):

$ make TESTS=navigation

To regenerate all the expected outputs for the tests:

$ make gen

To regenerate the expected outputs for a group of tests (e.g. navigation):

$ make gen TESTS=navigation

Other packages

• verilog-ts-mode: SystemVerilog Tree-sitter mode
• vhdl-ts-mode: VHDL Tree-sitter mode
• verilog-ext: SystemVerilog Extensions
• fpga: FPGA & ASIC Utilities for tools of major vendors and open source
• wavedrom-mode: edit and render WaveJSON files to create timing diagrams
• vunit-mode: Integration of VUnit workflow