-
Notifications
You must be signed in to change notification settings - Fork 4
Vorg
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))))
or use file variables in the vOrg
file, as for example
-*- mode: vhdl-tools-vorg -*-
Otherwise, it is to be enabled manually.
From an vOrg
file, it is possible to tangle its blocks of vhdl
source code with
help of
C-c C-v t (vhdl-tools-vorg-tangle) - tangle vOrg file and beautify resulting buffer
C-c C-v _ (vhdl-tools-vorg-tangle-all) - tangle all vOrg files in current dir and beautify resulting buffers
Additionally, it is also possible to jump from the vOrg
file to the vhdl
file
with help of
C-c M-, (vhdl-tools-vorg-jump-from-vorg) - jump from vOrg to vhdl
This alternative will implement auto tangling if necessary before jumping.
Then, from within the vhdl
source file, and only when the sibling vOrg
file
exists, it is possible to jump back from the vhdl file to its corresponding vOrg
file -assuming its names are identical and only its extension changes- with help
of
C-C M-^ (vhdl-tools-vorg-jump-to-vorg) - jump from vhdl to vOrg
Finally, it is also possible to jump from the vOrg
file into the vhdl
module at
point with
C-c M-. (vhdl-tools-vorg-jump-from-vorg-into-module) - jump from vOrg to module vhdl
Once vOrg
minor mode is active the following keys are made available
C-c C-n (vhdl-tools-vorg-headings-next) - get to next header
C-c C-p (vhdl-tools-vorg-headings-prev) - get to previous header
Setting vhdl-tools-manage-folding
(off by default) to true will allow auto
folding upon jumping.
Following the status of the vhdl-tools-remap-smartscan
flag (off by default),
vOrg
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.
When vOrg
mode is active, editing source code blocks in the vOrg
file, the minor
mode will auto set proper indentation, whitespace fixup and alignment of source
code.
Additionally, manual beautification of source code blocks is made available with help of
C-c M-b (vhdl-tools-vorg-src-block-beautify) - beautify code block at point
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 vhdl 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 are put out of sight with help of
vhdl-tools--cleanup-tangled
which is activated along with VDHL-tools
.
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.
Conditionally tangling source code blocks is feasible too. This might be useful
for code reuse between projects. This may achieved by setting the variable
vhdl-tools-vorg-tangle-header-argument-var
and setting a tag in the heading
above the source code block. When no tags are given, the code block tangle
header argument is set to current file name. If a tag is present, but different
to the variable, the code block is ignored when tangling. This effectively 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
or directory local variable.
As an example, setting a heading tag to “altera” will allow tangling source code blocks below only if the previous variable includes “altera”. When no tag is defined, all blocks are tangled.
*** Altera :altera:
#+begin_src vhdl-tools
use work.cati_package.all;
#+end_src
*** Juno mezzamine code :xilinx:
#+begin_src vhdl-tools
use work.juno_mezzanine_package.all;
use UNISIM.VComponents.all;
#+end_src
Heading inclusion in tangled code is implemented. This provides a way to
replicate the file structure of the vOrg
file in the source code file.
Tangled code appears by default in the same directory where the vOrg
file
lies. However, it is possible to modify this behaviour. Using the variable
vhdl-tools-vorg-src-vhdl-dir
, source code may be extracted in a different
directory to its vOrg
sibling. When setting vhdl-tools-tangle-comments-link
as
explained in “Using references” section, it will be possible to jump back to the
vOrg
origin, effectively providing a means of splitting code appart. Along with
“Conditional tangling”, this provides a way to develop code common to different
targets, families, etc.
Publishing is one of benefits of using org and the literate programming paradigm. It may achieved with help of
C-c M-P (vhdl-tools-vorg-publish) - Publish project
Before publishing, one has to define the project configuration with help of, for example, a .dir-locals.el file containing something similar to
((nil
(org-publish-project-alist . (("CatiROC-test-firmware"
:base-directory "/home/User/MyProjects/src-vorg/"
:publishing-directory "/tmp/src-html/"
:publishing-function org-html-publish-to-html
:makeindex nil
:section-numbers nil
:auto-sitemap t
:sitemap-filename "index"
:sitemap-title "CatiROC tests Firmware"
:with-toc t )))))
An example project using this feature may be found here, where all local vOrg
files has been published.