Documentation about Emacs Windows Integration

Emacs Logo

I have been using Emacs under Windows for quite some time, starting with Emacs 20.7 under Windows 98SE. I am using Emacs now under Windows 10 Pro both 32‑bit and 64‑bit.

My main use cases are software development for micro-controllers and creating documentation. For documentation I use Emacs' org-mode and HTML export.

I describe here how I install, configure and use Emacs under Windows. Use this advice at your own risk. I do not take any responsibility for this.

I have the following requirements:

I need to have the same Emacs software available on multiple PCs
I need to have the same configuration available on multiple PCs
I am used to the Windows/CUA keyboard shortcuts like Ctrl-c for copy, Ctrl-v for paste and Alt-Tab to switch windows, etc.

To have the same set-up on multiple PCs, I use the OneDrive feature of Windows, which provides automatic synchronisation via Microsoft's cloud.

Installation

You might want to download the 32‑bit version from the official web-site http://ftp.gnu.org/gnu/emacs/windows/. In my case (Nov. 2016) the files were:

emacs-25.1-i686-w64-mingw32.zip		48.968KB
emacs-25.1-i686-w64-mingw32.zip.sig	1KB
emacs-25-i686-deps.zip			36.415KB
emacs-25-i686-deps.zip.sig		1KB
emacs-25-win-README.txt

To use Emacs from several PCs, "install" Emacs by extracting to a new directory on your OneDrive

C:\Users\xyz\OneDrive\myPrograms\Emacs

Please substitute "xyz" with your account name. Emacs uses the HOME environment variable, which is not existing by default under Windows. To create it, type "environment" in the Windows Search input box and select "Environment variables for this user". Specify for HOME

C:\Users\xyz\OneDrive

I recommend to run Emacs in server mode. For this please create another environment variable EMACS_SERVER_FILE which shall read

C:\Users\xyz\.emacs.d\server\server

Server mode is very fast to start editing a file. For house keeping purposes, the Emacs server will create a special file. You want that special file on your private space, because it needs to be specific for a PC. Thus it shall not be located on the OneDrive.

For this to work, you also need to customise the Emacs variable server-auth-dir. To do this form within Emacs you could do Help, Describe, Describe Variable ... input server-auth-dir and then follow the instructions. You should set this variable matching the EMACS_SERVER_FILE environment variable you set above.

C:\Users\xyz\.emacs.d\server

Notice that this time, you specify a directory called server, whereas in EMACS_SERVER_FILE you specified a file called server which lives in that server directory. In other words: the environment variable EMACS_SERVER_FILE and the Emacs variable server-auth-dir need to match.

To arrange to have the Emacs server started when you log-in, do

Win-R shell:startup

and create in this directory a shortcut with the command line

%OneDrive%\myPrograms\emacs-25.1\bin\runemacs.exe --daemon

The Emacs server will run in the background. You could see it in Task Manager.

Configuration

Under Emacs 20.7 I had a file called _emacs in the HOME directory to contain my customisations. With Emacs 25.1 you might want to follow the recommendation to call the file init.el and put it in directory

C:\Users\xyz\OneDrive\.emacs.d

When you do customisations within Emacs via the menu Options, Customize, Emacs will also write to init.el. You might want to consult my init.el. I contains various types of customisations:

Various changes and additions to key-bindings to match my taste. This is mainly related to the fact that I am used to Windows keyboard short-cuts. The most complex to set up was Ctrl‑tab to cycle the buffers in one window. I had to "steal" and adapt some E-Lisp code to achieve this. The code skips "uninteresting" buffers like *scratch* and *messages* and the like. You could customise these buffers by editing the variable skippable-buffers in init.el
Require my own org-mode HTML export code. See details here
Bind various file extensions to visual-basic-mode. Note that visual-basic-mode does not come out of the box with Emacs 25.1.
My own assembler mode to use with AVR micro-controller assembly programming language. This is still primitive and improving it is on my to-do list.

Editing with Emacs under Windows

Send a file To Emacs

The simplest and least intrusive way to integrate Emacs with the Windows GUI is to use Send-To. That is when you right click a file in Explorer there is the Send-To option in the pop-up menu.

To add Emacs to the Send-To targets, create a short-cut in the SentTo folder. You find this folder by pasting

%APPDATA%\Microsoft\Windows\SendTo

in the Windows search box. Then you put a short-cut with command line

C:\Users\xyz\OneDrive\myPrograms\emacs-25.1\bin\emacsclientw.exe -n

in it and give the shortcut the name Emacs.

Running Emacs by double clicking

Another way to integrate with the Windows GUI is to have Emacs editing a file when double-clicking. However, ever since Windows Vista there is no more GUI support to customise associating a file to open in a program. Hence I recommend the following:

Right click a file and find "Open With…"
Specify "Further Apps"
Find the file

C:\Users\xyz\OneDrive\myPrograms\emacs-25.1\bin\emacsclientw.exe

Hit OK

This will select the correct executable, but it misses a command line argument -n to go with it. To fix this, open the (User-)Registry and go to

HKEY_CLASSES_ROOT\abc_auto_file\shell\open\command

Replace abc with the file extension of the file you where treating. There you should find the command line

C:\Users\xyz\OneDrive\myPrograms\emacs-25.1\bin\emacsclientw.exe

you specified above. Edit it and include the -n switch. This makes sure that emacsclientw.exe just hands over the file to the Emacs server and then terminates as it should.

Integrating Emacs with other tools under Windows

For software development under Windows, I wanted to integrate Emacs with other tools:

make. I chose a GNU make native build. I got version 3.81 from year 2006. I put C:\Users\xyz\OneDrive\myPrograms\make-3.81\bin in my Windows path.
bash. bash can be used from the git for windows native build. I chose the portable version 2.20.1.windows.1, that can be "installed" without administrator rights
rcs. For simple cases I am still using rcs rather than git. I am using rcs version 5.7 for Win32, which is ancient, but works. I put C:\Users\xyz\OneDrive\myPrograms\rcs\bin\win32 in the Windows path.

Both Emacs and make will use the Windows environment variable SHELL which I set to

C:/Users/xyz/OneDrive/myPrograms/git-2.20.1/bin/bash.exe

Note the forward slashes! It turns out that in that case ‑ using bash rather than Windows' cmd ‑ as the shell, it is better to define HOME also with forward slashes

C:/Users/xyz/OneDrive

This will allow to use HOME also from Makefiles.

Emacs M-x shell will then bring you into bash rather than cmd. You can then use tools like grep et cetera, that are delivered together with git.

When the shell starts, there is an warning message though:

bash: cannot set terminal process group (-1): Inappropriate ioctl for device
bash: no job control in this shell

I have not yet figured out, how to get rid of it. It does not seem to harm.

When started from Emacs, there is the environment variable

$INSIDE_EMACS

which yields in my case

25.1.1,comint

This I learned from zsh shell inside Emacs on Windows which mentions also a shell under Emacs does not have a true TTY and a special switch to use SSH.

I also customised the shell command prompt, because I felt the default is much too long for my taste. I needed to edit the file

C:/Users/xyz/OneDrive/myPrograms/git-2.20.1/etc/profile.d/git-prompt.sh

which constructs the environment variable PS1.

If you set the SHELL environment variable like advised above, make will use bash it even when make is started from cmd.

If you want to use bash and make only under Emacs, e.g. by starting a shell within Emacs or by starting make via Emacs' compile command, then there is the possibility to set the SHELL environment variable only within Emacs by adding the following to your init.el file

(setenv "SHELL" "C:/Users/xyz/OneDrive/myPrograms/git-2.20.1/bin/bash.exe")

There is also the possibility to extend PATH only within Emacs via adding to to init.el:

(setenv "PATH"
  (concat
   "C:\\Users\\xyz\\OneDrive\\myPrograms\\git-2.20.1\\usr\\bin;"
   (getenv "PATH")))

Note that backslashes need to be escaped, i.e. doubled up.

Other Possibility - Using Emacs under WSL

Under Windows 10 64‑bit there is the possibility to use the Windows Subsystem for Linux (WSL). That allows to use Emacs and other related Linux tools like under standard Linux distributions, but integrated with Windows and without the need to run a virtual machine.

The advantage of this is that numerous tools, e.g. spell checking, are easy to install in that Linux environment and they are usually well integrated with Emacs. On Windows most of these tools are available as well but installation and setting-up the integration with Emacs require more work, like you read above.

As I want to keep using PCs with Windows 10 32‑bit, I continue to use the Windows native Emacs.

However I do use WSL successfully for other purposes.