Home

CatiROC test firmware

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

Table of Contents

• About
• Install
• Setup
• Use
  • Headings
  • Custom Imenu
  • Custom SmartScan
  • Jumping around
  • Misc
• vOrg
  • Features
  • Tangling
  • Tangling extras
• Related utilities
• Coding
• Example configuration
• License

About

VHDL-tools originates as a collection of missing, necessary functionalities to my workflow. It provides an extra layer in the form of two derived major modes, vhdl-tools-mode which completes the default emacs vhdl-mode. and vhdl-tools-vorg-mode which lies on top of the powerful org-mode. It adds vhdl-specific functionality based on packages as ggtags, projectile, imenu and outshine to ease navigating vhdl sources.

VHDL-tools 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

Source code: https://github.com/csantosb/vhdl-tools

tar: https://github.com/csantosb/vhdl-tools/tarball/master

zip: https://github.com/csantosb/vhdl-tools/zipball/master

Install

Manual installation: as usual, download it, add to path and set vhd files to load in vhdl-tools-mode.

(add-to-list 'load-path "...")
(add-to-list 'auto-mode-alist '("\\.vhd" . vhdl-tools-mode))

Then, I autoload the modes under demand to avoid requiring everything at startup.

(autoload 'vhdl-tools-mode "vhdl-tools")
(autoload 'vhdl-tools-vorg-mode "vhdl-tools")
;; (require 'vhdl-tools)

When opening vhdl files, the library will be implicitly required.

Finally, load your custom code

(with-eval-after-load 'vhdl-tools
  (require 'vhdl-tools-personal-configuration))

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

M-x package-install RET vhdl-tools

Then, proceed as before

(autoload 'vhdl-tools-mode "vhdl-tools")
(autoload 'vhdl-tools-vorg-mode "vhdl-tools")
;; (require 'vhdl-tools)

Setup

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

• configure ggtags
• setup projectile by putting it under version control with git

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.

Use

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.

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

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.

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.

Misc

C-c M-b

beautify current block (module, etc.)

vOrg

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.

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.

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.

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

Coding

Sparse list of projects intended at improving coding

VHDLHandbook

Example configuration

For an example configuration, see my personal here. Basically, I just update the load path and then declare vhd files to be open in vhdl-tools-mode. In order to load the library only when first calling the major modes, I autoload them.

Finally, when the libray is loaded, I customize it with this setup, where I include not only vhdl-tools related features but additional useful code.

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/.

About