GNU Emacs

GNU Emacs is a highly extensible and customizable text editor. You can find many useful information (Manual, FAQ, ...) on the official GNU Emacs project page.

Installation

Unix/Linux

Most likely Emacs is already available on these platforms, otherwise

• chances are high that there exists a binary package (RPM, deb, ...) that can easily be installed with the respective packet management software.
• you can also compile Emacs from the sources. Below are instructions for a basic install. Note: For more detailed installation instructions and info about the optional extra packages please see the "INSTALL" file in the downloaded tarball.
  1. Download the source tarball emacs-XX.X.tar.gz (e.g. emacs-21.4a.tar.gz) from the gnu server or a mirror,
     • ftp://mirror.switch.ch/mirror/gnu/emacs/
     • ftp.gnu.org/gnu/emacs/
  2. Unpack, configure, compile and install global installation (requires superuser)

      gzip -d -c emacs-21.4a.tar.gz | tar xvf -
      cd emacs-21.4
      ./configure
      make
      make install

     local installation Note: Adapt the prefix path

      gzip -d -c emacs-21.4a.tar.gz | tar xvf -
      cd emacs-21.4
      ./configure --prefix=/path/to/my/emacs
      make
      make install

Windows

There are two rather different ways to use Emacs on the windows platform:

• Use a Windows port
• Run Emacs under Cygwin

Cygwin is a Linux-like environment for Windows that emulates the Linux API (Application Programming Interface) and provides a broad collection of Linux tools that are ported to Cygwin (and run on top of the emulation layer).

A native Windows port however is noticeably faster and consumes much less disk space so if you solely need Emacs this is the recommended way.

The following is a brief description about how to install the GNU Emacs Windows port. For more detailed instructions and more information please see the GNU Emacs FAQ For Windows page.

1. Download the precompiled distribution emacs-XX.X-fullbin-i386.tar.gz (e.g. emacs-21.3-fullbin-i386.tar.gz) from the gnu server or a mirror
   
   • ftp://mirror.switch.ch/mirror/gnu/emacs/windows/
   • ftp.gnu.org/gnu/emacs/windows/
2. Install an archiver that can handle .tar.gz archives, e.g. winrar, winzip or alike.
3. You can install Emacs for all users (global installation) or just for you (local installation). The former requires Administrator rights, i.e. you need to be Administrator or a member of the Administrators group.
   global installation (Administrator rights required)
   • Unpack the tarball directly to C:\Program Files (this will create an emacs-XX.X subdirectory)
   • Run C:\Program Files\emacs-XX.X\bin\addpm.exe (for an alternative see next point). This will create a couple of registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs and a start menu entry for all users: "Start -> All Programs -> Gnu Emacs -> Emacs".
     

     Note: For newer Emacs versions the registry keys are no longer required, so if you don't like them you can delete them with the registry editor ("Start -> Run : regedit").

   • As an alternative to the last point you can manually create the start menu entry:
     1. Right-click the Start button and select "Open All Users".
     2. Navigate to the folder you want to create the new entry in, e.g. "Programs\Gnu Emacs" (create folders as needed).
     3. To create the shortcut drag "C:\Program Files\emacs-XX.X\bin\runemacs.exe" to this folder (hold down Ctrl and Shift while dragging!)
   
   local installation
   • Unpack the tarball to a folder of your choice on your account, e.g. "My Documents\Applications"
   • Run emacs-XX.X\bin\addpm.exe (for an alternative see next point). This will create a couple of registry keys under HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs and a start menu entry for the current user: "Start -> All Programs -> Gnu Emacs -> Emacs".
     

     Note: For newer Emacs versions the registry keys are no longer required, so if you don't like them you can delete them with the registry editor ("Start -> Run : regedit"). Warnings:

     • If you are member of the "Power Users" group the registry keys will be created in the HKEY_LOCAL_MACHINE branch instead, which means they are per-machine and not per-user.
     • If you are even member of the "Administrators" group, in addition to the last point the start menu entry will be created not only for the current user but for all users.
   • As an alternative to the last point you can manually create the start menu entry: Drag "emacs-XX.X\bin\runemacs.exe" to the desired location in the start menu (create subfolders as needed). Note: To create a desktop shortcut hold down Ctrl and Shift while dragging.

Extra functionality (Windows)

Some functionality of Emacs relies on external binaries, e.g. the "Tools -> Compare" functions require the "diff" utility to be available on the system. Fortunately there exist native Windows ports for many Gnu Utilities. GnuWin32 is a very nice project with many packages available.

To install the DiffUtils package you can choose between an installer and a zip-file based method. For the full details please see the "Installation and Usage" section of the package and "General Installation Instructions".

1. Download zip-files or the installer from the "Download" section:
   
   # option 1
   Download the "Binaries" and the "Dependencies" zip files. They need to be unpacked to the same folder later.</dt><dd>
   
   # option 2
   Download the installer "Complete package, except sources". The installer will </dt><dd>
   • let you choose the target folder
   • ask whether to create start menu items or not
   • create some registry keys
   • make the package show up in "Add or Remove Programs"
     
     
2. Unpack zip-files or run installer:

   global installation (Administrator rights required)
   unpack or install to "C:\Program Files\GnuWin32"

   local installation
   unpack or install to a folder on your account, e.g. "My Documents\Applications\GnuWin32"

3. As a final step we need to make sure that Emacs can find the new binaries. This is required even if you have used the installer and not the zip-files. Again there are two options:
   

   #option 1
   Add the "GnuWin32\bin" folder to the "PATH" Windows environment variable. Emacs reads this variable at startup an adds its value to the search path for executables (i.e. exec-path). Unless the name of a new binary coincides with an existing windows binary it does not matter whether you prepend or append to "PATH". Note: This option has the advantage that you can easily run the new binaries from the windows command prompt too.

   global installation (Administrator rights required)
   Set the following system environment variable:
   name = PATH
   value = %PATH%;C:\Program Files\GnuWin32\bin

   local installation
   Set the following user environment variable (adapt value)
   name = PATH
   value = %PATH%;%USERPROFILE%\My Documents\Applications\GnuWin32
   
   #option 2
   Add the "GnuWin32\bin" folder directly to the Emacs "exec-path". This can be done in an Emacs customization file.

   site-wide installation (Administrator rights required unless Emacs locally installed)

   Add this to the site-start.el file (please note the forward slashes in the paths!):

   ; append
   (setq exec-path (append exec-path (list "C:/Program Files/GnuWin32/bin")))
   ; prepend
   ;(setq exec-path (cons "C:/Program Files/GnuWin32/bin" exec-path))

   
   per-user installation

   Add this to your .emacs/_emacs file (please note the forward slashes in the paths!):
   
   ; append
   (setq exec-path (append exec-path (list(expand-file-name "~/Applications/GnuWin32/bin"))))
   ; prepend
   ;(setq exec-path (cons (expand-file-name "~/Applications/GnuWin32/bin") exec-path))

   
   Note: Adapt the path as needed. This example assumes that your Emacs "home" is set to "%USERPROFILE%\My Documents" as "~" will be replaced by its value.

Configuration

Emacs customizations (actually lisp code) are usually stored in these files:

.emacs

• per-user settings
• located in the users "home" directory (more about "home" on Windows follows below)
• overrides site-wide settings
• to inhibit loading use command-line switch --no-init-file<tt></tt>

site-start.el

• site-wide settings, i.e. for all users of this particular Emacs installation
• located in the Emacs installation directory
• to inhibit loading use command-line switch --no-site-file<tt></tt>

At startup Emacs looks for "site-start.el" and ".emacs" (in this order) and loads them in turn if they exist. Therefore you can easily modify or override site-wide settings with your personal init file.

Note: For site-wide settings you could also have a default.el file that is loaded after the per-user settings.

It is always a good idea to check if there exist site-wide settings and have a closer look at them as they might considerably change the default behavior of Emacs.

Tip: Users here at D-ITET might want to read "Setup here at D-ITET" (see below).

Unix/Linux

Put the Emacs customization files in the following places:

.emacs
in your home directory, i.e. $HOME<tt></tt>

site-start.el
in the Emacs installation directory under "emacs-XX.X/share/emacs/site-lisp/"<tt></tt>

Windows

The file ".emacs" can alternatively be named "_emacs" to avoid problems when using the GUI to create this file. Note: do not use both files concurrently.

Put the Emacs customization files in the following places:

.emacs or _emacs<tt></tt>
Emacs will look for this file in your "home" directory, the location of which is determined as follows (take the first value defined/set or fall back to 4.):

1. Value of the Windows environment variable named "HOME"
2. Value of registry key <tt>"HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs\HOME"</tt>
3. Value of registry key <tt>"HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs\HOME"</tt>
4. "C:\"

Option 1. is a convenient method to set your Emacs "home" but make sure there arises no conflict with other software installed that uses this environment variable too (e.g. Cygwin, see here).

The best location to set Emacs "home" to might also depend on your Window setup, but here are two suggestions (using standard windows environment variables):

• <tt>%USERPROFILE%\My Documents</tt>
• <tt>%HOMEDRIVE%%HOMEPATH%</tt>

Note: You should also take into consideration that Emacs substitutes "~" in filenames (e.g. ~/_emacs) with the value of "home".

Troubleshooting HOME: To check what Emacs thinks your "home" is set to type the following lisp code in the *scratch* buffer and evaluate it with C-x C-e:

 (insert (getenv "HOME"))

The actual value of "home" should now be inserted in the same window just behind the lisp code.

site-start.el

in the Emacs installation directory under <tt>"emacs-XX.X/site-lisp/"</tt>

VHDL Mode

VHDL Mode is an Emacs major mode for editing VHDL code. This mode has plenty of very useful features that greatly facilitate writing of VHDL code.
It was primarily developed with GNU Emacs but is compatible to XEmacs too.

Tip: Users here at D-ITET might want to read "Setup here at D-ITET" (see below).

Installation

With newer Emacs versions (>= 20.4 for Gnu Emacs) VHDL Mode is part of the distribution. To check the version and availability of VHDL Mode in your current Emacs installation start up Emacs and try to load vhdl-mode with the following command (in Emacs):

 M-x vhdl-mode

Note: "ESC x" does exactly the same as "M-x", so if you do not have a Meta key you can always use the Escape key instead. Please note that the two keys "ESC" and "x" do not need to be pressed simultaneously (which would be written as "ESC-x"). Furthermore, on Windows the Alt key usually acts as Meta key.

Unless VHDL Mode is missing altogether you should now see the version number at the bottom of the Emacs window in the minibuffer. If you have an old version or no VHDL Mode at all follow the instructions below to install the latest version.

Note: site-wide installation means for all users of this particular Emacs installation and per-user installation means only for the current user, i.e. the user you are currently logged on.

1. Download the latest VHDL Mode as .zip or .tar.gz file from www.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html and unpack it to a temporary directory.
2. Copy the lisp (.el) and byte-compiled lisp (.elc) files of VHDL Mode and possibly required patches (see note and example below) to the following location:
   site-wide installation (Administrator/root rights required unless Emacs locally installed)
   the 'site-lisp' directory
   per-user installation an arbitrary directory on your account, e.g. "~/library/vhdl-mode-3.33.5" (Unix example) Note: For the latest patch requirements see the INSTALL file included with VHDL Mode. Example: For VHDL Mode 3.33.5 and Gnu Emacs 21.X the files to copy are
   • vhdl-mode.el, vhdl-mode.elc
   • speedbar.el, speedbar.elc
   • dframe.el, dframe.elc
   • sb-image.el, sb-image.elc
3. As we want Emacs to look in this directory first when loading lisp files, we need to prepend it to the Emacs load-path.
   site-wide installation nothing to do as the 'site-lisp' directory is already on the built-in load-path (at/near the beginning)
   per-user installation add the following line to your .emacs (or _emacs) file (adapt the path):

    (setq load-path (cons (expand-file-name "~/library/vhdl-mode-3.33.5") load-path))

   Notes:
   • Windows: use '/' (not '\') in the directory path!!!
   • You can use '~' in the path, it will interpolate to what Emacs thinks your "home" is (for Windows see above).
   • Do not point to a directory where you unpacked the whole VHDL Mode archive to. This might lead to problems if Emacs picks up patch files from there that are not intended for this particular Emacs release (i.e. Emacs/XEmacs, version)
   
4. If (and only if) VHDL Mode was not bundled with your Emacs distribution (very unlikely), i.e. <tt>"M-x vhdl-mode"</tt> did not do anything, you need to add these lines

    (autoload 'vhdl-mode "vhdl-mode" "VHDL Mode" t)
    (setq auto-mode-alist (cons '("\\.vhdl?$" . vhdl-mode) auto-mode-alist))

   to the appropriate Emacs customization file:
   site-wide installation site-start.el file (create it if it does not exist yet)
   per-user installation your .emacs (or _emacs) file
5. (Windows only): For Windows you might also want to set up file type associations for ".vhd" and ".vhdl".

Configuration

The VHDL Mode default settings are very reasonable, but to support a custom naming convention some extra configuration is needed. You can find this as well as an example ".emacs" file below.
To use these customizations add them to the appropriate Emacs customization file (.emacs/_emacs, site-start.el).
Note: To see all possible customizations of VHDL Mode use the "VHDL -> Options" menu in Emacs.

• namingconv: To support the naming conventions for signal, constant and port names (supports some older conventions too, i.e. "xE" and "xZ").
• extraface: Optional extra face to make tristate-signals bold (does not work with XEmacs). Background info: The "special syntax highlighting" feature of VHDL Mode only supports setting of the foreground color (i.e. text color) based on a regular expression match. If you want to set other attributes (e.g. bold, underline,...) you can modify the internally generated faces via "VHDL -> Options -> Highlight -> Colors...". However, as the "special syntax highlighting" rules are not additive, i.e. the first one that matches is taken, it is not possible to set e.g. the text color with one rule and the text weight with another one. This is exactly what the extraface above does, i.e. add the bold attribute (based on a regexp match) to the already existing attributes.
• .emacs: This is an example ".emacs" file that includes above customizations along with some hopefully useful general Emacs settings and keybindings.

Troubleshooting: If VHDL Mode does not behave as expected and you are sure that the installation and configuration are correct then try this:

• Delete the pre-compiled lisp files (*.elc) of vhdl-mode and patches. Emacs will now use the *.el files instead of the *.elc files which is slower but should not make a difference otherwise. If things are OK now there was an incompatibility with the pre-compiled lisp and you might want to try the next step to speed things up again.
• Re-compile all incompatible lisp files with your Emacs, e.g.:

   M-x byte-compile-file RET ~/mylisp/vhdl-mode.el RET
   

Miscellaneous

Windows environment variables

You can add, modify or delete windows environment variables through the "Environment Variables" Dialog (see below). There are per-user settings ("User variables") and system wide settings ("System variables"). To modify the latter Administrator rights are required.

1. Right-click "My Computer" and then click Properties. This brings up the "System Properties" Dialog
2. On the Advanced tab, click the "Environment Variables" button
3. Modify user and/or system environment variables in the "Environment Variables" Dialog.
   Note: No quoting is required for the variable name/value
4. Apply the settings

To verify the settings you can open a command shell ("Start -> Run : cmd") and type "set" at the prompt to see all environment variables or type "set home" to show only variables that begin with "home".

Windows file type associations

If you want Windows to open a ".vhd" or ".vhdl" file with Emacs when you double-click it you need to create file type associations.
For a global installation do the following instructions with Administrative (or "Power User") rights, for a local installation make sure you do not have such rights, i.e. you are only member of the "Users" group.
To associate ".vhd" to "runemacs.exe":

1. Right-click a file with the extension that you want to change (e.g. ".vhd") and then click Open, or double-click the file.
2. Windows displays a dialog box that indicates that no program is associated with this file. Select the option "Select the program from a list" and click Ok.
3. Windows shows the "Open With" dialog box with a list of registered applications.
   • If available select "Gnu Emacs" from the Programs list, otherwise click the "Browse..." button to locate the "runemacs.exe" binary in your Emacs installation under "emacs-XX.X\bin\runemacs.exe".
   • Select the "Always use the selected program to open this kind of file" check box and click Ok

Troubleshooting and background info:
There are basically three places in the registry where this information will be stored (with increasing precedence):

• with global installation

   HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.vhd
   HKEY_LOCAL_MACHINE\SOFTWARE\Classes\vhd_auto_file

• with local installation

   HKEY_CURRENT_USER\SOFTWARE\Classes\.vhd
   HKEY_CURRENT_USER\SOFTWARE\Classes\vhd_auto_file

• only in special cases

   HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\FileExts\.vhd

The "SOFTWARE\Classes\.vhd" keys point to "vhd_auto_file" which in turn points to "runemacs.exe". The "Explorer\FileExts\.vhd" key stores the actual file association in a key named "Progid" or "Application" and NOT in the two subkeys "OpenWithList" and "OpenWithProgids" as it might appear.

You can have entries in one, two or even three of these places (precedence is as noted above). Note: A merged view of the keys under "SOFTWARE\Classes\" is available under "HKEY_CLASSES_ROOT", but it is more transparent to work with the original keys from "HKEY_LOCAL_MACHINE" and "HKEY_CURRENT_USER".

You can always remove associations by simply deleting above key(s) including all subkeys ("Start -> Run : regedit", select key and hit DEL). Particularly the "Explorer\FileExts\.vhd" can cause strange problems when creating new file associations with above method, so if you experience such problems simply delete this key and retry.

The GUI to change file associations (Tools -> Folder Options... -> File Types) is somewhat limited, e.g. it does not show entries from "Explorer\FileExts\" and does not allow a restricted user (no Administrator or Power User) to delete/modify the associations he was able to create beforehand.

Setup here at D-ITET

Some points about the Emacs/VHDL-Mode setup here at D-ITET:

• For Solaris/Linux installations most Laboratories here use the Emacs SEPP packages created by ISG. These packages include extensive site-wide customizations including lots of keybindings. For example for emacs-21.3 they can be found in "/usr/pack/emacs-21.3-to/share/emacs/site-lisp/site-start-local.el" which gets loaded by "/usr/pack/emacs-21.3-to/share/emacs/site-lisp/site-start.el". If you don't like them you can override them or even inhibit their loading altogether (see above).
  The VHDL Mode and its configuration included in these packages is usually not up to date but should work anyway.
• There is a SEPP package named "ic_support-1.0-ma" that holds (among other things) the latest Emacs VHDL Mode along with complete example ".emacs" files (see above). Please see "/usr/pack/ic_support-1.0-ma/emacs/README" for the details and instructions on how to use this stuff. If this package is not yet available on your network you have to ask your sysadmin to install it.