Installing Emacs For VHDL Work

Posted by Iain Waugh on
Emacs Logo

Emacs can be a very powerful tool to help you write VHDL code. It has:

  • Project management and navigation assistance
  • Code templates
  • Language syntax templates
  • Copy an entity and paste it as an instance, a set of signals or even a new testbench template
  • Code formatting (beautification)
  • Auto-update the sensitivity list
  • A list of simulators that you can compile against

This article shows you how to set up Emacs for VHDL work and make it behave like a regular Windows text editor (for copy/paste).

The Interface

Emacs looks pretty much the same if you’re using it in a terminal or if you’ve launched the GUI version. The GUI can have an icon-bar if you like. When I launch it and switch it to VHDL mode, it can look like this:

The Fundamental Emacs Keystrokes

Emacs can be used with the default menu bar and icon bar, but you really get the most out of it if you know some basic keyboard short-cuts. The Gnu organisation has a PDF reference card, here, but it’s easy to get swamped in the details and (a bit further on) I’ll be showing you how to customise it to make standard copy/paste keys work, so I’ll run through the most essential ones and you can look at the reference card if you want more.

Quitting: <Ctrl>-X, <Ctrl>-C
Note: you don’t have to let go of the <Ctrl> key between pressing x and c.

Cancel out of the minibar: <Ctrl>-]
It’s like an escape key. If you think you’ve lost control or are in some strange mode, hold down a <Ctrl> key and mash ] a couple of times.

Emacs refers to opened files as “buffers”. Emacs can have lots of buffers open at once, but it doesn’t have a tabbed bar at the top to show them all. If you have at least one document open, then press <Ctrl>-left mouse click to get a menu showing a list of them.

Save: <Ctrl>-X, s

Close a file (close buffer): <Ctrl>-x, k
Note: Let go of <ctrl> before pressing k, then press <enter> to kill the current buffer that you’re looking at.

That’s enough for now; they really are the basics. We’re going to be customising more in the section below, then I’ll introduce a few fancy ones at the end.

Managing Emacs Start-up Options

When Emacs starts, it looks for an environment variable called “HOME“, then it looks for a file called “$HOME/.emacs” to load your options. Now, there’s a ton of options and you really don’t want to make all your options in that one file; I find Emacs is much more manageable if you break the options out into separate sections and load them from there.

If you’ve never launched Emacs before, you won’t have a “.emacs” file saved yet. The “.emacs” file contains any changes to the standard Emacs settings that you make and save.

By default, Emacs uses a very old way to copy and paste text. Our first configuration change will be to configure standard Windows/Mac Cut/Copy/Paste keys. This is called cua-mode. Launch Emacs, go to the menu bar and select “Options -> Use CUA Keys”.

You have to save the option or it won’t be remembered next time you launch Emacs. Go to the menu bar and select “Options -> Save Options”.

If you’ve got the HOME directory open in Explorer, you will notice a new directory is also created, called “.emacs.d”. We can ignore that; it’s not relevant, but if you really want more details, look here.

You can edit the “.emacs” file manually, if you like. Here’s what the start of mine looks like:

(custom-set-variables
 ;; custom-set-variables was added by Custom.
 ;; If you edit it by hand, you could mess it up, so be careful.
 ;; Your init file should contain only one such instance.
 ;; If there is more than one, they won't work right.
 '(cua-mode t nil (cua-base))
 '(inhibit-startup-screen t)
 '(make-backup-files nil)
 '(message-log-max 2000)
 '(show-paren-mode t)
 '(tool-bar-mode nil)
)

Setting Up Your Compiler/Simulator

Prerequisites:

  • You can open a cmd.exe window and type make.
    If not, see the article on How To Set Up And Use MSys2, then add msys64\usr\bin to your Windows PATH variable.
  • You have your simulator executable on your PATH.
    In my case, it’s Intel/Altera’s free vsim.exe

If it’s set up correctly, you can check with these 2 commands.
vsim -version
make -v

Microsoft Windows [Version 10.0.19041.450]
(c) 2020 Microsoft Corporation. All rights reserved.
C:\Windows\System32>vsim -version
Model Technology ModelSim - INTEL FPGA STARTER EDITION vsim 2020.1 Simulator 2020.02 Feb 28 2020
C:\Windows\System32>make -v
GNU Make 4.3
Built for x86_64-pc-msys
Copyright (C) 1988-2020 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
C:\Windows\System32>

Download My Configuration

I was going to explain each step in my Emacs configuration, but that’s really slow and boring. Instead, you can grab an archive of my set-up below, install it by extracting it into your $HOME directory with this command:

tar -jxvf emacs_cfg.bz2

Once installed, you can enter VHDL mode by pressing <Ctrl>-F12. Next, I’ll explain some key points so you can customise it for yourself.

emacs_cfgDownload

Here’s a function-key strip that you can print out as a reference:

Emacs-Function-Key-Strip (PDF)Download

Customise It For You

Open my sample .emacs file and scroll to line 422. Everything before this line gets overwritten by these statements:

(setq load-path `("~/emacs/" ,@load-path))
(load "site-vhdl.el") ; Load my VHDL defaults
(load "google-c-style.el") ; Google's C styleguide
(load "my-molokai-theme.el") ; Nice dark theme

Open emacs/site-vhdl-templates.el and change this line to whatever you want to be called:

'(vhdl-company-name "Change My Name")

The funky SpeedBar isn’t going to work for you unless you point it to where your code is. Open emacs/site-vhdl-projects.el and edit the paths. By default, I store my work under C:/Work, but you’ve probably got yours somewhere else. The general format of each project is a sequence of “space”-separated parameters:

  • “Short Name (appears in SpeedBar)”
  • “Long Name (Goes into headers)”
  • “Path to the project’s top-level”
  • “List of search paths to scan for HDL files”
  • “Regular expression of files/directories to ignore”

If that’s a bit confusing, use the Emacs editor’s menu system and look at:
VHDL -> Project -> Options -> Project Setup

If you have Vivado or ISE installed, try changing my install paths to yours. Once you do that, you will be able to open the Speedbar with <Shift>-F12 and scan those files.