This project provides support under Emacs in terms of navigation of VHDL sources.
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
imenu
smartscan
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.
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
.
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 headerC-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 imenuC-x c i i
instancesC-x c i c
componentsC-x c i p
processesC-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 linkC-c M-y
paste a linkC-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 vhdlC-c C-n
get to next headerC-c C-p
get to previous headerC-c C-v t
tangle vOrg
file and beautify resulting bufferC-c C-v _
tangle all vOrg
files in current dir and beautify resulting buffersC-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.
(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.
“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.
“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.
Some additional emacs packages useful in this context
Sparse list of projects intended at improving coding
For an example configuration, see my personal setup.
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/.