Setting up Spacemacs – My new favorite text editor

Emacs or vim? Nano or pico? What about notepad++, sublime, atom, VScode, ed?

I have certainly made the rounds with text editors over the years and I never felt like any one was perfect. I used Notepad++ for a long time on windows. I liked the utility it had, but I always wanted a more full-featured IDE that worked with the different languages I would program in. I tried Sublime and its close cousin Atom for a while, but it too lacked some features that I wanted. When developing in linux, I became very familiar with the infamous Vim editor, which I loved. In fact, I kinda went package and extension crazy with linting and smart auto-completion. My vim setup almost did everything I wanted, but it fell short in doing the few things that required a GUI, like editing a LaTex document. I didn’t think the perfect editor existed, that is before I found Spacemacs.

Spacemacs is a “Community-driven emacs distribution”, which means it’s really just emacs, with some smart changes. It rebinds a lot of the complicated emacs commands to mnemonic key combos. It creates a consistent layer system for each type of text I am editing. It also is fully-extensible and has good community support to allow you to tinker. The best part? You can edit in whatever style you prefer. Vanilla emacs is a very approachable and for someone who has never used vim, it’s a good starting place. Vim, however, is a very efficient way to edit text as countless blog posts will attest to. Evil is a vim compatibility layer that allows you to use Emacs as though you were editing in vim (for the most part). This is why the tagline to Spacemacs is “The best text editor isn’t vim or emacs, its vim AND emacs”.

Who should use Spacemacs

This post isn’t about really about trying to convince anyone to switch their editor, there are other posts for that. Really I just want to document the steps I went through to get everything working. From that statement alone, one could gather that Spacemacs isn’t exactly a download-and-go solution. Which leads me to detail who I think Spacemacs is good for.

If you are the kind of programmer who:

  • Is a polyglot and wants an IDE that provides a consistent means by which to develop
  • Is a researcher who writes LaTeX and wants something a bit more than TexStudio
  • Likes Jupyter notebook and wants that kind of environment in a more formal markup system like LatTeX
  • Wants the extensibility of Emacs with the handling of Vim
  • Is ok with getting your hands dirty in getting things working

Then you might want to give Spacemacs a shot.

If not, check out VSCode. Seriously, it’s a great piece of software.

The problem statement

I like having the same editor on all my machines. I have a Macbook Pro that I carry around with me and a Windows workstation at home. I have been using Spacemacs for a while now on macOS, but I just recently wanted the same environment on my windows box.

Emacs is from the GNU project, a group that is pretty vehement about free software. Just read this blurb from the download page for the Emacs windows binaries.

The purpose of the GNU system is to give users the freedom that proprietary software takes away from its users. Proprietary operating systems (like other proprietary programs) are an injustice, and we aim for a world in which they do not exist.

Naturally, things are a little hairy when trying to get ‘nix software working on windows outside of the linux for windows subsystem.

So, the rest of this post will be the steps I took to get my spacemacs setup working in Windows. I plan on writing more blog posts that go more in-depth into my workflow for different languages and Org.

Step 1: Get vanilla emacs

There are a few precompiled binaries and nice packages for Emacs on windows, but a lot of them have a hodgepodge of deprecated packages and strange initial configurations that make the rest of the steps complicated. I found that starting from the vanilla binary from GNU was the best place to start.

As of this writing, the most recent Emacs is 26.1 – which can be found in a mirror from GNU such as https://mirror.clarkson.edu/gnu/emacs/windows/

I downloaded the zip and extracted it to a convenient location.

Open up runemacs.exe to make sure it opens and revel at the ugliness of vanilla emacs. This also ensures that the .emacs.d directory is created.

Step 2: Get spacemacs

As mentioned before, spacemacs really is a collection of configuration settings for emacs. So the way spacemacs is installed is by cloning a git repo into the .emacs.d directory which holds the emacs configuration files.

As this step involved git, make sure you have git by installing Git for Windows

Now, we have to find where the .emacs.d directory is located, which depends on the $HOME$ environment variable.

For me, it was created in C:\Users\my_username\AppData\Roaming – so I would check there first. If not, it may have created it simply in C:\User\username

Open up Git bash and cd to wherever .emacs.d is
cd C:\Users\username\AppData\Roaming

And clone the git repo into the folder
git clone https://github.com/syl20bnr/spacemacs .emacs.d

Then we want to switch the the development branch. Trust me, a lot of things improved on develop that aren’t yet on master. It’s worth it to switch.
cd .emacs.d
git checkout develop

So at this point, spacemacs is setup. Open up runemacs.exe and you should be greeted with the shiny spacemacs startup screen.

Select the editing style you want, and then let spacemacs whir away and download all it’s dependencies.

Once the develop branch makes it to master, things will get a little easier, but in the meantime, you have to pull updates by hand through git in the .emacs.d folder. Also, the new standard is instead of having a .spacemacs file next to the .emacs.d folder, there is a seperate .spacemacs.d folder with an init.el file. To switch to the new standard, which some new layers require, you can do this all in the git bash shell.

Still in the folder that contains .emacs.d

mkdir .spacemacs.d
mv .spacemacs .spacemacs.d/init.el

Step 3: Fonts and themes

Source Code Pro

The default font in spacemacs is Source Code Pro, quite a beautiful face if you ask me. Unfortunately, it is not a default font on Windows. To install it, download the latest source from Adobe’s github. Note: You will need non-variable fonts for this to work as windows doesn’t really support OTF. The latest link as of this writing is https://github.com/adobe-fonts/source-code-pro/archive/2.030R-ro/1.050R-it.zip

Extract that and navigate to the TTF subdirectory. Highlight all, right click, and install.

MacType

The way Windows renders fonts is a little strange, and if you ever wondered why they aren’t as smooth looking as macOS is because of built-in rastering options. A program called MacType fixes this and makes nice fonts like Source Code Pro render correctly. This is completely optional, but I like the way it looks.

To install it, grab the latest installer from http://www.mactype.net/

Run it and make sure to check either run from system tray or as a service. Applying it to the registry breaks things in Windows 10. Then select which profile you want, I like the LCD profile. Done!

Themes Megapack

The default spacemacs theme is pretty nice, but there are a lot to choose from. There is a spacemacs layer called themes-megapack that holds a lot of good themes. Adding new layers is very easy, you do so by editing your init.el file in the .spacemacs.d folder. To edit your spacemacs configuration, you use the key combination SPC f e d – file emacs dotfile is the mnemonic. This file is where all of your spacemacs is configured. Under a function called defun dotspacemacs/layers () there is a list of layers. Some are commented out with two semicolons. In that list, add themes-megapack. To reload the configuration with Org, use SPC f e R – file emacs Reload. Spacemacs should now download all the new themes! You may notice the screen flash and things change as they install as some of the themes apply themselves as they install, but once they are done installing, you press SPC q R to restart spacemacs and everything is back to normal.

Check out all the themes in https://themegallery.robdor.com/

Once you find one you like, you add the name of the theme to (setq-default dotspacemacs-themes '(list-themes-here)) in your init.el file. I’m partial to twilight-anti-bright.

Step 4: Get helpful layers to work

At this point, spacemacs is setup. The tricky part begins with getting the specific layers to work. I’ll start with what I believe to be most important for me, Org mode.

Org Mode Setup

Org mode is an emacs addon that is a full-featured typesetting editor. From their website:

Org mode is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

People use it for all sorts of stuff: class notes, writing emails, this and all my other blog posts, and scientific papers.

What I like about it is its ability to compile to LaTeX to PDF. It effectively allows me to author beautiful documents typeset in LaTeX but without the nightmare that is actually writing LaTeX.

I’ll write a post eventually on all the cool things you can do with Org, but here’s how to set it up.

Enable the Org Layer

In your .spacemacs file (or init.el if you moved it), simply uncomment line that says ;; org to enable the layer. I use bibtext a lot, so you could add that to layers as well.

To reload the configuration with Org, use SPC f e R – file emacs Reload. Emacs should now download all the files it needs to use Org.

Download a LaTeX toolchain

If you want to publish to PDFs from Org, you will need an active LaTeX installation. MikTex is a very good bundle to start with on Windows. The link can be found here https://miktex.org/download

Once you download and install it, you may need to add it to the PATH in spacemacs. I ran into a problem where the install to it was in my system path, but not populating in spacemacs for some reason. I would first check to see if it works by making a sample org file

SPC f f Test.org RET

Then type some stuff like

#+TITLE: Test
#+AUTHOR: Me
* Blah
** Blah Blah
#+BEGIN_EXPORT latex
\begin{equation}
\overline{F} = M \Cdot A
\end{equation}
#+END_EXPORT

To compile, you hit , to open up the layer specific commands. Then e e l o – export-dispatcher export latex open

If you’re lucky, you will get a nice PDF output.

If you get an error like PDFlatex is an unrecognized command, you need to add the MikTex binaries to the path.

To do this, you open your dotfile and navigate to the dotspacemacs/user-config() section and make the following changes:


(defun dotspacemacs/user-config ()
"Configuration for user code:
This function is called at the very end of Spacemacs startup, after layer
configuration.
Put your configuration code here, except for variables that should be set
before packages are loaded."
(setenv "PATH" (concat (getenv "PATH") "e:/Program Files/MiKTeX 2.9/miktex/bin/x64"))
(setq exec-path (append exec-path '("e:/Program Files/MiKTeX 2.9/miktex/bin/x64")))
)

Of course you would change the path to be where you actually installed miktex.

SPC f e R to reload and then we can check the path with SPC SPC getev RET path RET – Verify the path you added is at the end of the output.

Then try running the latex export again, it should work. Tada!

Next steps

I have done a lot to modify my spacemacs setup, so I will follow up this post with others on my workflow and setup in different layers. I plan to write on how I set up my C/C++ setup so I have consistency between developing on my mac and on my desktop, my common lisp setup with a different REPL than SLIME, a better PDF viewer, and many other tutorial-like instructions. Stick around and watch out for those!