Configure (base) Spacemacs

Table of Contents

I love using Spacemacs. I like how extensible Emacs is, but prefer the modal editing nature of Vi(m), and Spacemacs provides the best of both worlds through the use of Evil. Tinkering with my editor configuration to get the perfect setup is fun, and there are a few ways this can be achieved:

1. Use base Emacs with customizations
2. Use the full Spacemacs distribution
3. Customize the base Spacemacs distribution

Using base Emacs (1) and adding our own packages and configurations is doable but it takes a lot of work. Full Spacemacs (2) offers everything the distribution has to offer, but I find there are packages that I never use, which causes my editor to load/perform slower than it needs to.

I opted for the 3rd option: install the base Spacemacs distribution, then pick and choose specific layers and packages that I need to keep my editor as light as possible. I could’ve just installed the packages separately (instead of going through the layer system) but then I’d lose the ability to integrate the package into the Spacemacs ecosystem without additional configuration of things like keybindings and adding custom functions.

Overall, I don’t mind buying into an opinionated ecosystem like Spacemacs, I just want it to be faster.

Note: The following contains links and code from the Spacemacs GitHub repo. Given Spacemacs is a community driven distribution, the structure of the repo may change at any time. The below is correct as of 14/04/17.

Identifying base packages and layers

We can see the list of packages installed with the base distribution in their GitHub repo:

(setq spacemacs-base-packages
      '(
        (abbrev :location built-in)
        ace-window
        (archive-mode :location built-in)
        (bookmark :location built-in)
        (centered-buffer-mode :location local)
        (conf-mode :location built-in)
        (dired :location built-in)
        (dired-x :location built-in)
        (electric-indent-mode :location built-in)
        (ediff :location built-in)
        (eldoc :location built-in)
        evil-escape
        (evil-evilified-state :location local :step pre :protected t)
        evil-visualstar
        (exec-path-from-shell :step pre)
        help-fns+
        (hi-lock :location built-in)
        (holy-mode :location local :step pre)
        (hybrid-mode :location local :step pre)
        (image-mode :location built-in)
        (imenu :location built-in)
        (linum :location built-in)
        (occur-mode :location built-in)
        (package-menu :location built-in)
        (page-break-lines :location built-in)
        pcre2el
        (process-menu :location built-in)
        projectile
        (recentf :location built-in)
        (savehist :location built-in)
        (saveplace :location built-in)
        (spacemacs-theme :location built-in)
        (subword :location built-in)
        (tar-mode :location built-in)
        (uniquify :location built-in)
        (url :location built-in)
        (visual-line-mode :location built-in)
        (whitespace :location built-in)
        (winner :location built-in)
))

When we install the full/standard distribution, some additional layers are added to give us access to more packages. Again, we can see the added layers in their repo:

(configuration-layer/declare-layers '(spacemacs-base
                                      spacemacs-completion
                                      spacemacs-layouts
                                      spacemacs-editing
                                      spacemacs-editing-visual
                                      spacemacs-evil
                                      spacemacs-language
                                      spacemacs-misc
                                      spacemacs-ui
                                      spacemacs-ui-visual
                                      spacemacs-org
))

Layers are just groups of Emacs packages with custom functionality added. So, the goal is to look at each of these full distribution layers and figure out which packages we want to extract and use in our own setup.

Of course we can also just install individual packages the "traditional" way by adding it to dotspacemacs-additional-packages but if the package we want can be found in a Spacemacs layer then it’s preferable (in my opinion) to extract it from the layer system. This way we can retain all of the upstream configurations, keybindings, and custom functions that Spacemacs sets for those packages.

Picking and choosing packages

The best way to figure out which packages to extract is by digging through their GitHub repo to see what each layer contains (along with what additional configurations are used for each layer/package). The Spacemacs layers used in the full distribution can be found here. To see what packages are in each layer, we just dive into the directory for that layer and look at the packages.el file.

Let’s take the spacemacs-editing layer for example. packages.el shows the packages used in that layer:

(setq spacemacs-editing-packages
      '(aggressive-indent
        avy
        (bracketed-paste :toggle (version <= emacs-version "25.0.92"))
        clean-aindent-mode
        eval-sexp-fu
        expand-region
        (hexl :location built-in)
        hungry-delete
        link-hint
        lorem-ipsum
        move-text
        (origami :toggle (eq 'origami dotspacemacs-folding-method))
        smartparens
        (spacemacs-whitespace-cleanup :location local)
        undo-tree
        uuidgen
        ws-butler
))

Now that we know what this layer contains, we can choose only the packages we need and add it to our own configuration.

To install packages we need to edit our ~/.spacemacs file, which contains our configuration. Specifically, we’re looking for the dotspacemacs/layers() function. Inside, you’ll see dotspacemacs-configuration-layers which is where we’d typically install entire layers, but we can use this to install specific packages from a layer as well.

So let’s say we only want to use the avy and smartparens packages from this layer. We simply specify those packages in dotspacemacs-configuration-layers:

(defun dotspacemacs/layers ()
  (setq-default
   dotspacemacs-configuration-layers
   '((spacemacs-editing :packages
      avy
      smartparens))
))

If we want to add an entire Spacemacs layer (spacemacs-xxx) or any other layer in the their ecosystem (e.g. git or html), we add them to the same place. Furthermore, we can pick and choose packages from any of those additional layers as well (e.g. rainbow-mode from the colors layer):

(defun dotspacemacs/layers ()
  (setq-default
  dotspacemacs-configuration-layers
  '((colors :packages
     rainbow-mode)
     git
     helm
     html
     (spacemacs-editing :packages
     avy
     smartparens)
     (spacemacs-editing-visual :packages
     auto-highlight-symbol
     highlight-parentheses
     indent-guide)
     spacemacs-layouts
     spacemacs-org)
))

Spacemacs offers a nice ecosystem, and in my mind the best way to customize the distribution is by installing spacemacs-base and then flexibly picking desired packages from within their layer system.

This gives the advantage of customizing the editor with only the packages that I want and need, while still retaining all of the upstream configurations for each of those packages so I can avoid configuring them manually. Of course, this has the disadvantage of your configuration breaking if they rename their spacemacs-xxx layers, or decide to remove a package from a particular layer, but this seems like a small price to pay for the flexibility and performance increases that can be gained.