Article: how to create a spacemacs layer

How to create a custom layer for Spacemacs, with examples

how to include packages
- init a package
- include in package list (optionally with a toggle defined as a var)
adding mnemonic key bindings (following Spacemacs conventions)
defining custom functions
defining custom variables
defining custom faces
Adding optional behaviour configured with toggles and layer variables

Follow-on articles

Adding packages and key bindings to an existing package

Basic starting point

SPC SPC configuration-layer/create-layer

configuration-layer/create-layer is an interactive Lisp function in ‘core-configuration-layer.el’.

(configuration-layer/create-layer)

Ask the user for a configuration layer name and the layer directory to use. Create a layer with this name in the selected layer directory.

define a package list

Add a `defconst called layername-packages

In packages.el

(defconst clojure-packages
  '(
    cider
    cider-eval-sexp-fu
    (clj-refactor :toggle clojure-enable-clj-refactor)
    (helm-cider :toggle (configuration-layer/layer-used-p 'helm))
    clojure-mode
    (clojure-snippets :toggle (configuration-layer/layer-used-p 'auto-completion))
    company
    eldoc
    evil-cleverparens
    flycheck
    (flycheck-clojure :toggle (memq 'squiggly (if (listp clojure-enable-linters)
                                                  clojure-enable-linters
                                                (list clojure-enable-linters))))
    (flycheck-clj-kondo :toggle (memq 'clj-kondo (if (listp clojure-enable-linters)
                                                     clojure-enable-linters
                                                   (list clojure-enable-linters))))
    (flycheck-joker :toggle (memq 'joker (if (listp clojure-enable-linters)
                                             clojure-enable-linters
                                           (list clojure-enable-linters))))
    ggtags
    (kaocha-runner :toggle clojure-enable-kaocha-runner)
    counsel-gtags
    helm-gtags
    org
    popwin
    (sayid :toggle clojure-enable-sayid)
    smartparens
    subword))

Create a custom var for optional features

Edit config.el and add a suitably named var with a default value

(defvar clojure-enable-kaocha-runner nil
  "If non-nil, the Kaocha runner is enabled.
Kaocha should be a dev-dependency or alias in a Clojure project.")

Initialising the package

Edit packages.el and add a function defun to initialise the package

Add sub-menu sections Add key bindings

(defun clojure/init-kaocha-runner ()
  (use-package kaocha-runner
    :defer t
    :init
    (progn
      (setq kaocha--key-binding-prefixes
            '(("mtk" . "kaocha")))
      (spacemacs|forall-clojure-modes m
        (mapc (lambda (x) (spacemacs/declare-prefix-for-mode
                            m (car x) (cdr x)))
              kaocha--key-binding-prefixes)
        (spacemacs/set-leader-keys-for-major-mode m
          "tka" 'kaocha-runner-run-all-tests
          "tkt" 'kaocha-runner-run-test-at-point
          "tkn" 'kaocha-runner-run-tests
          "tkw" 'kaocha-runner-show-warnings
          "tkh" 'kaocha-runner-hide-windows)))))

TODO: check package only initialised if toggle is true

Prompted for location of layer - defaults to ~/.emacs.d/private/

practicalli / blog-cryogen