spacemacs/layers/+lang/emacs-lisp/README.org

Emacs Lisp layer

• Description
• Install
• Auto-compile
• Working with lisp files (barfage, slurpage & more)
• Debugging Elisp
• Key bindings
  • Additional evaluation functions
  • Format code
  • Debugging

Description

This layer gathers all the configuration related to emacs-lisp. This should always be in your dotfile, it is not recommended to uninstall it.

Install

To use this configuration layer, add it to your ~/.spacemacs. You will need to add emacs-lisp to the existing dotspacemacs-configuration-layers list in this file.

Auto-compile

This layer adds the auto-compile package to automatically keep the byte-compiled version of your Emacs lisp files synced with the uncompiled version on every save. If there are any compiler errors in the file, you will see a counter show up in the mode line. You can hover over these numbers to get a description or view the compiler output with the SPC m c l key binding. To disable the feature use this line in your dotspacemacs/user-config function.

  (remove-hook 'emacs-lisp-mode-hook 'auto-compile-mode)

You can also exclude the auto-compile package.

Working with lisp files (barfage, slurpage & more)

Spacemacs comes with a special lisp-state for working with lisp code that supports slurpage, barfage and more tools you'll likely want when working with lisp.

As this state works the same for all files, the documentation is in global DOCUMENTATION.org. In general, use SPC k to interact with the lisp-state.

Debugging Elisp

Here is an interactive quick start to debug Emacs Lisp.

First you need to read this file in Emacs in order to have the following code block to be interactively opened as Emacs Lisp.

(defun helloworld (name)
  (let ((n (subroutine name)))
    (message (format "Hello world, %s!" name))))

(defun subroutine (s)
  (concat "my dear " s))

(helloworld "Spacemacs")

1. To start the tutorial put your point in the source block above and press , '

it will open a new buffer in emacs-lisp-mode.

1. Evaluate each sexp by putting your point in each of them and press , e f.
2. To debug the helloworld function, put your cursor on the defun keyword and

press SPC m d f (or , d f), it will put a breakpoint on the function (we say that we instrumentalise this function) so whenever the Lisp interpreter encounters this function it will start the debugger.

1. Then go to the closing parenthesis of (helloworld "Spacemacs") and press

, e e to evaluate it, if you are using vim editing style you end up in evilified state otherwise you end up in emacs state and *Debugging* is displayed in the mode line.

1. Press s to go to next step up to the opening parenthesis of (subroutine name),
2. Press i to go into the subroutine where you can press s to step in

function or press o to go out of it.

1. Press a to stop debugging.

Key bindings

Key Binding	Description
SPC m g g	go to definition of symbol under point
SPC m g G	go to definition of symbol under point in other window
SPC m h h	describe symbol at point
SPC m c c	byte compile the current file
SPC m c l	popup compile-log buffer
SPC m e $ or SPC m e l	go to end of current line and evaluate
SPC m e b	evaluate current buffer
SPC m e C	evaluate current defun or setq
SPC m e e	evaluate sexp before point
SPC m e f	evaluation current function
SPC m e r	evaluate current region
SPC m ​,​	toggle lisp state
SPC m t b	run tests of current buffer
SPC m t q	run ert
SPC m d m	open macrostep transient-state

Additional evaluation functions

If smartparens is used the following additional key bindings are available:

Key Binding	Description
SPC m e c	evaluate sexp around point
SPC m e s	evaluate symbol around point

Format code

The semantic layer should be installed for these key bindings to become active.

Key Binding	Description
SPC m = b	format current buffer
SPC m = f	format current function
SPC m = o	format all on one line
SPC m = s	format current sexp

Debugging

To start debugging:

Key Binding	Description
SPC m d f	on a defun symbol toggle on the instrumentalisation of the function
SPC m d F	on a defun symbol toggle off the instrumentalisation of the function
SPC m d t	insert (debug) to print the stack trace and re-evaluate the function

In edebug-mode (*Debugging* is displayed in the minor modes segment of the mode line)

TODO

In debugger-mode (Debugger is displayed in major mode segment of the mode line)

TODO