Resources for Emacs-Lisp Dev

README.md

Resources for elisp dev

How to improve emacs features discoverability & elisp debugging UX

We assume you already configured MELPA and use-package.

Otherwise, see e.g. this ~/.emacs template.

Then, add the following elisp snippet in your ~/.emacs, in order to install:

• which-key
• discover-my-major
• Helpful
• edebug-x

(use-package which-key
  :ensure t
  :config
  (which-key-mode))

(use-package discover-my-major
  :ensure t
  :config
  (global-set-key (kbd "C-h C-m") #'discover-my-major)
  (global-set-key (kbd "C-h M-m") #'discover-my-mode))

;; Recall we also have the standard keybinding "C-h m".

(use-package helpful
  :ensure t
  :config
  (global-set-key (kbd "C-h f") #'helpful-callable)
  (global-set-key (kbd "C-h v") #'helpful-variable)
  (global-set-key (kbd "C-h k") #'helpful-key)
  ;;; Look up Functions (excludes macros).
  ;; (global-set-key (kbd "C-h F") #'helpful-function)
  ;;; Look up Commands (= keybindings).
  ;; (global-set-key (kbd "C-h K") #'helpful-command)
  ;;; COMMENTED-OUT as "Info-goto-emacs[-key]-command-node" are more useful.
  (add-hook 'emacs-lisp-mode-hook #'(lambda ()
    (local-set-key (kbd "C-c C-.") #'helpful-at-point))))

;; Note we can also type "C-h" after a prefix to list its expansions.

(use-package edebug-x
  :ensure t)

Finally, run M-x package-refresh-contents RET and restart Emacs.

A must-have: Magit

• Assuming you have Git (otherwise you have to install it):
• Setup Magit in your ~/.emacs by folllowing this Gist.

Tips and tricks to debug code

To run the debugger automatically:

• M-: (setq debug-on-error t) RET → in case of error
• M-: (setq debug-on-quit t) RET → when typing C-g (to debug infinite loops or so)

To cancel, replace t with nil:

• M-: (setq debug-on-quit nil) RET.

To add a breakpoint on a function, say, learn-ocaml-mode:

• Open the Elisp code directly or indirectly:
  • Type C-h f learn-ocaml-mode RET then TAB… and RET on learn-ocaml.el.
• On line (def… learn-ocaml-mode, type C-x SPC.
• Run the command at stake (in the running example: M-x learn-ocaml-mode RET).
• You're now in edebug-mode, try typing e, i or SPC for example (or C-h m for other keybindings details).

Tutorials and further documentation

• First, read this tiny tutorial https://learnxinyminutes.com/docs/elisp/ (if you never wrote code in Elisp)
• Then, read and experiment with at least these three pages from ergoemacs.org:
  • http://ergoemacs.org/emacs/elisp_basics.html
  • http://ergoemacs.org/emacs/elisp_editing_basics.html
  • http://ergoemacs.org/emacs/elisp_list.html
• Read the Appendix D.1 Emacs Lisp Coding Conventions.
• For the record, further conventions are available in Appendix D Tips and Conventions & The Emacs Lisp Style Guide.
• Bookmark the URL of the official introductory doc (270+ pages) and the GNU Emacs manuals from the official website.