Vhdl-tools

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.

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

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.

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.

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

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.

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.

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