This project provides support under Emacs in terms of navigation of VHDL sources.

Table of Contents

1 About

Vhdl-tools provides an extra layer in the form of a minor mode intended to be used along with emacs vhdl-mode. It adds specific functionality on top of ggtags, projectile, imenu and outshine to ease navigating vhdl sources. It expects a working setup of ggtags, completing it with

  • Jumping into instances
  • Jump to upper level
  • Searching for references
  • Link and headings management
  • Custom use of imenu
  • Custom smartscan
  • Org / vhdl coupling

2 Install

Manual installation: as usual, download it, add to path and require after loading vhdl-mode

(with-eval-after-load 'vhdl-mode
		  (add-to-list 'load-path "...")
		  (require 'vhdl-tools))

This package is available fom Melpa too, you may install it by calling

M-x package-install RET vhdl-tools

Then, activate the minor mode by completing the vhdl-mode hook.

(add-hook 'vhdl-mode-hook
		  (lambda ()
		  (vhdl-tools-mode 1)))

When this minor mode is active, a lighter #vhdl will be shown in the mode line.

3 Setup

VHDL-tools expects a correct setup of the packages it relies on

Then, if you plan to use outshine by setting vhdl-tools-use-outshine to true, just don’t forget to

(require 'outshine)
(add-hook 'outline-minor-mode-hook 'outshine-hook-function)

before activating vhdl-tools. Remember to

(add-to-list 'company-begin-commands 'outshine-self-insert-command)

otherwise company idle completion using the capf backed won’t work (see related utilities section below).

Additionally, setting vhdl-tools-manage-folding (off by default) to true will allow auto folding when jumping around, and vhdl-tools-recenter-nb-lines will be used as number of lines from top after jumping.

Finally, have a look at all customization possibilities with M-x customize-group vhdl-tools.

4 Use

4.1 Headings

Following the status of the vhdl-tools-use-outshine flag (off by default), when the mode is enabled, vhdl-tools will activate outline-minor-mode locally and outshine globally, setting vhdl-tools-outline-regexp as the regexp used to locate headings.

This enables using this kind of headings

-- * Header Level 1

-- ** Header Level 2
MyInstance : MyComponent
port map ( ...
		  

to delimit code blocks.

Then, call outshine-speed-command-help to get an overview over the available functionality and the keybindings. Additionally, the following keybinds are provided to navigate headings

  • C-c C-n get to next header
  • C-c C-p get to previous header

Setting vhdl-tools-manage-folding (off by default) to true will allow auto folding upon jumping.

Finally, to browse all headings use imenu as shown in next section.

4.2 Custom Imenu

The following keybinds are made available to browse current buffer contents

  • C-x c i m standard imenu
  • C-x c i i instances
  • C-x c i c components
  • C-x c i p processes
  • C-x c i SPC headings (with a prefix argument use ido instead)
  • C-x c i a all items

4.3 Custom SmartScan

Following the status of the vhdl-tools-remap-smartscan and vhdl-tools-use-outshine flags (off by default), vhdl-tools will customize the behaviour of smartscan-symbol-go-forward and smartscan-symbol-go-backward, so that they manage folding/unfolding of section headings. This way, upon jumping, only the relevant section is shown.

4.4 Jumping around

The following keybinds are available

  • C-c M-D jumps to the definition of symbol at point

  • C-c M-w store a link
  • C-c M-y paste a link
  • C-c M-j follows the link at point

  • C-c M-. jumps into the instance at point and move point to current signal

  • C-c M-a moves point to first appearance of symbol at point

  • C-c M-u jumps to upper hierarchy level

Cursor will jump to the target if there is one, searching packages too. The ring mark is push after jumping, so to get back, press C-c C-p or M-, (default binds under ggtags) if corresponding definition has been found. Works better for files with correct syntax: think vhdl-beautify-buffer before using vhdl-tools.

4.5 Misc

  • C-c M-b beautify current block (module, etc.)

5 vOrg

5.1 Features

Following the literate programming paradigm, it is possible to tangle an org-mode file containing source code blocks to a source code file. This helps documenting code, for example, and provides lots of other benefits. An example project following this approach may be found here.

In order to ease handling this workflow, this package defines an ancillary minor mode called vOrg intended to be used along with org major mode. When this minor mode is active, a lighter vOrg will be shown in the mode line.

To auto activate vOrg, one may hook org mode

(add-hook 'org-mode-hook
		    (lambda ()
		    (when (and (buffer-file-name)
                    (file-exists-p (format "%s.vhd" (file-name-base (buffer-file-name)))))
		    (require 'vhdl-tools)
		    (vhdl-tools-vorg-mode 1))))

Otherwise, it is to be enabled manually.

When the vOrg file exists it is possible to jump from the vhdl file to the vOrg file -assuming its names are identical and only its extension changes- with help of

  • C-C M-^ jump from vhdl to vOrg

Once vOrg minor mode is active the following keys are made available

  • C-c M- jump from vOrg to vhdl
  • C-c C-n get to next header
  • C-c C-p get to previous header
  • C-c C-v t tangle vOrg file and beautify resulting buffer
  • C-c C-v _ tangle all vOrg files in current dir and beautify resulting buffers
  • C-c M-b beautify code block at point

Setting vhdl-tools-manage-folding (off by default) to true will allow auto folding upon jumping.

Finally, when editing source code blocks in the vOrg file, the minor mode will auto set proper indentation, whitespace fixup and alignment of source code.

5.2 Tangling

Org mode includes special infrastructure to tangle org files containing source code. As explained in the org manual, extra comments may be inserted in the tangled code file. In particular, the “comments:link” option provides pointers back to the original org file, as a reference for jumping back and forth between vorg and vhdl.

This behaviour is activated by setting the vhdl-tools-tangle-comments-link flag. Otherwise, only code is extracted from the vOrg file. The variables vhdl-tools-vorg-tangle-comment-format-beg and vhdl-tools-vorg-tangle-comment-format-end are used to format inserted comments in tangled code files.

Once the code is tangled from the vorg file, the reference comments around in the source vhdl file may be put out of sight with help of

(add-hook 'vhdl-mode-hook #'vhdl-tools--cleanup-tangled)

Note that even if the vhdl-tools-tangle-comments-link flag is not set, the jumping features in vOrg minor mode may be used, except that in this case, a regular text search of text in current file is used to locate the point to jump to.

5.3 Tangling extras

  • Dynamically defining source code block header arguments is possible in org. This may achieved by setting “header-args:vhdl” in the properties drawer of the topmost heading, which will propagate to all lower level headings
(add-hook 'vhdl-tools-vorg-mode-hook
		    (lambda ()
		    (save-excursion
		    (beginning-of-buffer)
		    (while (equal (car (org-get-tags-at (point) t)) "TOC")
                    (org-next-visible-heading 1))
		    (org-set-property "header-args:vhdl"
		    ":prologue (prologue-defun) :tangle (tangle-defun)"))))

In this example, upon activation of the vOrg minor mode, a property is set at the first heading, avoiding any heading containing the “TOC” tag. Here, the “prologue-defun” and “tangle-defun” will get evaluated for each code block.

  • Conditionally tangling code blocks is feasible using the previous feature. This might be useful for code reuse between projects. This may achieved by using the “vhdl-tools-vorg-tangle-header-argument” provided function and setting a tag in the heading above the code block.
(add-hook 'vhdl-tools-vorg-mode-hook
		    (lambda ()
		    (save-excursion
		    (beginning-of-buffer)
		    (while (equal (car (org-get-tags-at (point) t)) "TOC")
                    (org-next-visible-heading 1))
		    (org-set-property "header-args:vhdl"
		    ":prologue (prologue-defun) :tangle (vhdl-tools-vorg-tangle-header-argument)"))))

This function acts as a filter, and provides a means to only tangle code blocks with tags in the variable “vhdl-tools-vorg-tangle-header-argument-var”, to be defined as a buffer local variable. As an example, setting a heading tag to “altera” will allow tangling this block only if the previous variable includes “altera”. Note that when no tag is defined, all blocks are tangled.

  • Heading inclusion in tangled code is also possible by using the “vhdl-tools-vorg-prologue-header-argument” provided function
(add-hook 'vhdl-tools-vorg-mode-hook
		    (lambda ()
		    (save-excursion
		    (beginning-of-buffer)
		    (while (equal (car (org-get-tags-at (point) t)) "TOC")
                    (org-next-visible-heading 1))
		    (org-set-property "header-args:vhdl"
		    ":prologue (vhdl-tools-vorg-prologue-header-argument) :tangle (tangle-defun)"))))

This provides a way to replicate the file structure of the org file in the source code file.

6 Related utilities

Some additional emacs packages useful in this context

smart scan
Jumps between other symbols found at point in Emacs
beacon
A light that follows your cursor around so you don't lose it!
aggressive-indent-mode
Emacs minor mode that keeps your code always indented. More reliable than electric-indent-mode
VDHL capf
emacs completion at point function (capf) backend for use with company
toc org
up-to-date table of contents in org files

7 Coding

Sparse list of projects intended at improving coding

8 Configurations

For an example configuration, see my personal setup.

9 License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.