Installing emacs & org-mode on Windows

Introduction

At home I am on LINUX pretty much full-time.  I only run Windows inside a VM in some special circumstances.  But at work I have to use Windows due to corporate policy, so I regularly face the challenge of finding cross-platform software which I can use both at home and at work.

One of the things I had to change when I switched from Windows at home was my text editor, because the previous editor I used was a Windows only application.

I decided that I would take the opportunity to go the whole-hog and learn a “proper” comprehensive text editor.  But this would involve a significant and ongoing investment of my time, so I wanted an editor that I could learn once and then use it everywhere.

I chose emacs.

Since then I have discovered org-mode (a major-mode for emacs which supports task management) and I have developed a detailed configuration which enables me to plan my work, clock time spent on tasks, develop projects, take notes, produce reports, etc.

Of course, I needed a setup which would allow me to work cross-platform, so that my text editing and org-mode task management would be seamless no matter if I worked at the office on Windows or at home on LINUX.  The need for a cross-platform installation and configuration was born.

In this blog I will explain my method for installing emacs on Windows.  Some of the decisions I make are related to my desire for cross-platform use, and these will be discussed.  But this blog works fine standalone, so even if all you’re interested in is using emacs on Windows, and you have no interest in sharing a configuration with LINUX, these instructions will still produce a working emacs installation on Windows for you.

I also discuss installation of org-mode and associated cross-platform use.

Pre-Requisites

EMACS ON LINUX

If you’re following this blog with the aim of cross-platform use, then you must already have a working installation on LINUX since I will not discuss the details of that here.  Your config file on LINUX must be available at ~/.emacs because that is the setup I am going to replicate on Windows.

GIT

I will discuss an org-mode installation that makes use of git.  If you don’t care to use org-mode and are only interested in emacs then this pre-requisite is not required and you can ignore it.  Otherwise, if you want to replicate my cross-platform setup with org-mode, you’ll need git.
I don’t explain how to install git on Windows, so if you’re unsure about that you will need to find some tutorials elsewhere and come back here once you’ve got git installed.  But here’s a hint: you need to visit the git web page, and install git for Windows.  If you prefer a GUI client I recommend tortoise git, you will need to install this separately.

INSTALLING EMACS

Cygwin

The first task is to install Cygwin.  Cygwin is a repository of GNU tools for Microsoft Windows.  This will allow you to install emacs on Windows and maintain an environment and file structure that is similar to that on LINUX.  This is essential to satisfy the cross-platform objective of the configuration.

Visit http://www.cygwin.com and download the Windows installer.  Launch it.

Advance the installer, and when asked to choose a download source, select “Install from internet”.

Next you will be asked to choose an install directory.  This will form the root of your Cygwin installation.  Inside it a file structure will be created, and this will include your “Home” folder.
The Home folder is the crucial ingredient; this will allow us to maintain an emacs installation that is the same across Windows and LINUX.

You don’t need to do anything to set all this up.  Just advance the installer script.  You can choose a different install location if you want, but I tend to accept the default.

Choose the installation directory

Now it is time to choose the GNU packages you want to install.  I’ll stick to what is required for emacs here.  You can always go back and browse for further packages that interest you afterwards.  I’ll be showing you how to install more packages later on.

In the search box type “emacs”.  This will show all the emacs related packages.  Now expand the “Editors” tree.

You must select the emacs package.  This is the base emacs installation.  You will see the package install message change from “Skip” to the version number that is going to be installed.

Now you have a choice.  You can either select the emacs-X11 package, in which case you will get a console only version of emacs, or you can select the emacs-w32 package.  In this case you will get the full emacs experience with GUI.  Even though emacs usage is heavily weighted towards the keyboard, I still prefer this option.

The screen grab below shows the correct selections to make:

Selecting emacs packages

Advance the installer.

The next page asks you if it’s OK to install dependencies.  You need to leave this box checked and advance to the next page.

Now cygwin will start installing everything, including emacs.  Sit back and wait!

Installing cygwin & emacs

When the installer finishes you will have an option to create a desktop icon.  This shortcut is not for emacs! It’s a shortcut for the cygwin terminal.  The terminal is quite useful, so I recommend you allow the installer to create the shortcuts, but it’s up to you.

Setting up emacs.

Emacs is installed and will run as it is.  First, let’s check it works.  Launch the Cygwin terminal using the shortcut icon.

Now you will see a terminal appear.  If this is the first time you have launched a cygwin terminal you will see some initial setup take place; cygwin will create some startup files in your cygwin home directory.  Then you will get a terminal prompt.

In the terminal prompt, type:

emacs &

If everything has worked, you should find that a bare-bones default emacs setup will launch.

emacs first launch

 

Now it is time to set things up.  If you’re a seasoned emacs user you will surely have your own config file that you want to use.  If you’re new to emacs then you should still create the file we’re going to talk about (because you will undoubtedly want to edit it in the future).

Now, a disclaimer: I can’t possibly know what you’ve got inside your own .emacs file.  If you’ve created a rats-nest in there, and some things don’t work, it’s up to you to fix them.  I’m happy to answer questions if I can though! Ask them in the comments.  Note that I consider myself very much an amateur emacs user.  I am still learning the ropes myself! I don’t know everything.

I have quite an extensive .emacs file which I have developed while using emacs on LINUX.  I control it with git, so I checked out the file and copied it to my cygwin home directory.  Assuming you accepted the default cygwin installation path then the home directory will be located at:

C:\cygwin\home\user

Where ‘user’ is your Windows user name.

This is what we refer to as your “home” directory.  On LINUX the home directory for a user is typically abbreviated as ~/.  This abbreviation works in Cygwin as well, and that’s why we can develop a common configuration that works across LINUX and Windows.  We only need to make sure that critical files (e.g. files which are referred to explicitly in .emacs, or used in org-mode) are kept in the home directory with a file structure that is replicated across the two systems.  The location of the home directory itself is not important, nor is the user name, since we will use the ~/ abbreviation when we refer to the home directory in code.

Creating an emacs shortcut icon

You might find it tedious to have to launch a cygwin terminal and type ’emacs’ every time you want to launch the application.

To fix that you can find the emacs executable in the cygwin bin directory and send a shortcut for it to your desktop.  Or you can pin it to your start menu, whatever you want.  See the screen grab below:

Creating an emacs shortcut

 

That’s it for emacs! We’re done!

You just need some way to keep the .emacs file current on both your Windows and LINUX systems.  I use git for that, so whenever I make changes I commit them to a git repository and then simply pull the changes on each local system.  This means I have one configuration which works at home on LINUX and at work on Windows.  The user experience and functionality is identical between these systems.

If you want to set up org-mode, read on:

org-mode setup

There are a few ways to set up org-mode.  I don’t debate the pros and cons here, I only offer a method that works for me.

I run org-mode by pulling the latest code from a repository and then running uncompiled source files on my systems.  This works on both LINUX and Windows.  Here’s how to do it:

First, you need git installed.  Otherwise you’ll have to find a manual method by which you can obtain the org-mode source.

Clone the org-mode repository:

clone the org-mode repository

 

make

Now you need to install the make utility.  You can get it from the Cygwin repository.  It could have been selected and installed at the same time as emacs, but if you’re not familiar with Cygwin this is a good opportunity to find out how to install extra packages.

You need to launch the Cygwin installer again.  Advance the installer in the same way as you did before until you get to the package selections.  Change the ‘View’ combobox to “Full”.  Then search for “make”.

Install make

You need to install the GNU version.  Select it so that the status changes from skip to the version number that will be installed.  Then advance the installer in the same way as before.

Make will be installed.

make uncompiled org-mode

Now open a Cygwin terminal.  Change directory to the location of the org-mode repo (in my case it’s ~/git/org-mode).  Enter “make uncompiled”.  See screen grab below:

Synchronising org files

Now you need a way to synchronise your org files in a way that will be common on both LINUX and Windows with the file paths being identical.

Some people use git to sync their org files, and that’s something I’d like to explore.  But right now I am using ownCloud, which is a cloud storage tool.  I use ownCloud because I run my own server and prefer to be in control of my own files, but you can use any cloud storage tool: Dropbox, Google Drive, One Drive, they all should work the same.  If you’re looking to run cross-platform, like me, then your choice will be limited by the clients that are available on both platforms.

The important bit is setting a target path for the cloud storage client that can be repeated on both platforms.  That means setting it up in your home folder.

I have my org files set up in the following path on both systems:

~/ownCloud/Documents/emacs/org

This way I am safe to refer to this path in my .emacs file.  For example, I have some lines in my .emacs that tells org-mode to include all org files inside certain folders into the agenda view:

This works on both platforms because ~/ refers to my home folder on LINUX and to the Cygwin home on Windows.  As long as the rest of the path is common on both systems, it’ll work.

When I am at work my org files are changed as I clock into and out of tasks, complete tasks, set new tasks, take notes, and so on.  These changes are synchronised with my server using ownCloud, and then the ownCloud client on my LINUX side at home pulls down the changed files.

The Final Result

Here is a screen grab of my emacs installation.  The theme and all configuration is common across LINUX and Windows using a single .emacs file.

my emacs installation
org-mode agenda view