Configuring Emacs
1 Introduction
This is a brief overview of how to move forward from knowing basic Emacs commands to acutally configuring Emacs to your own preferences. This article assumes you have at least done the Emacs tutorial that is found on the initial screen after loading Emacs.
2 Why configure Emacs?
Emacs is rarely if ever used out of the box with no configuration. Other editors like Vim, Sublime Text, and Atom are extensible however they offer a ready to use solution upon installation that most users don’t like changing. The whole ethos of Emacs is its extensibility. Many times developers use a text editor that they just have to accept the quirks of. With Emacs you can change virtually anything you want!
Don’t let this discourage you by thinking this is too much work. Extending Emacs can be fun as long as it’s understood piece by piece at your own pace.
3 What this post is not
This post will cover anything dealing with the Emacs Lisp interpreter or the Lisp language in general. This will not explain basic movement or general commands nor will it explain installing Emacs.
4 Getting Started
4.1 Using Customize
We will not touch on this too much however Emacs has a built in interface for customization. Since this has a menu system it’s really straight forward and is really learned by exploring! To access this feature simply run:
M-x customize
4.2 Creating your own customization file(s) (recommended)
4.2.1 Creating an init file
When Emacs is launched in a normal way (without passing -q from a terminal), Emacs will attempt to load an initialization (init) file. Emacs will attempt to look in 3 locations:
- ~/.emacs
- ~/.emacs.el
- ~/.emacs.d/init.el
As long as you have any of the above files, you can configure Emacs! For the sake of this post, we will assume we are working with a ~/.emacs file since we will only be dealing with a single configuration file (our init file).
4.2.2 Testing our ~/.emacs file
Now that we’ve created our ~/.emacs file it’s time to get down to work. Depending on how you use Emacs (assuming you are using a window manager Emacs will launch the GUI by default. If you desire to work in a terminal invoke Emacs with -nw (emacs -nw)) perhaps the most commonly asked Emacs configuration question is: how do I change this horrid theme?. This will also serve as a test to make sure your ~/.emacs file is working.
Launch Emacs (assuming GUI) and you’ll see a horrid theme (should be white background).
Now open ~/.emacs (C-x C-f ~/.emacs).
Insert the following code into your file
(load-theme 'wombat)
If you restart Emacs you should see a new theme!
- Note about themes
Emacs does come with several themes that you can try out. To see/test those run:
(M-x load-theme)
And hit TAB to view completion options. If you find one you like you can use that instead of wombat.
4.2.3 The Scratch Buffer
Before we get ahead of ourselves, it’s important to be aware of the scratch buffer in Emacs. This buffer is already present when you launch Emacs you just need to switch to it!
If you launch Emacs and press C-x b it should prompt you to switch there by default. Do that.
You can write any lisp code in the scratch buffer and interpret it on the fly! Let’s enter the following into our scratch buffer:
(message "Scratch says hi")
There’s two common ways we can evaluate this. With your cursor anywhere on that line press C-M-x (the -M is the meta key). This should invoke (eval-defun EDEBUG-IT). On some setups this may not work out of the box depending on your OS so it may be easier to go to the end of the line (C-e), and press C-x C-e instead which will invoke (eval-last-sexp EVAL-LAST-SEXP-ARG-INTERNAL).
Different people prefer different ways of evaluating Lisp and there’s definitely more than a few ways of doing so. You may want to also check out M-x eval-buffer to evaluate the entire buffer’s code for writing longer pieces of Lisp.
4.2.4 Turning on Debugging
If we write some bad code in our ~/.emacs file it’s nice to get some debug information about what took place. Wrapping your ~/.emacs file with turning on and off debug mode is an easy way to get all the information you need:
(setq debug-on-error t) (load-theme 'wombat) (setq debug-on-error nil)
This tell Emacs to give you useful debug information during execution of your init file and turn it back off afterwards. Turning it off at the end will make sure Emacs doesn’t blow up your workspace with Emacs debug information while working.
4.2.5 Common configuration
Perhaps the most common use of an init file is for configuring those simple options Emacs exposes to us like displaying the tool bar, displaying scroll bar, making backup files, turning off word wrap, or inserting spaces intead of tabs. Here would be a quick example of doing all of those plus a little more … the configuration taking place should be obvious based on the names, if not use C-h v.
(menu-bar-mode 0) (tool-bar-mode 0) (scroll-bar-mode 0) (setq make-backup-files nil) (setq-default truncate-lines t) (setq-default indent-tabs-mode nil)
- Note about setq-default
When setting variables using setq, sometimes the variable is specific to the current frame or buffer. To set this for every buffer, you need to use setq-default. Using:
C-h v
Should give you all the documentation you need for determining that. If you make changes and it only affects one buffer, chances are you can assume you need to use setq-default.
4.2.6 Custom keybindings
At some point you may want to create your own keybindings. This can seem intimidating but it’s a breeze! Here’s an example of binding the C-c e key to open up eshell:
(global-set-key (kbd "C-c e") 'eshell)
This binding makes it much more convenient to open commonly used functions almost instantly.
Sometimes, however, you may want to run a whole procedure when defining a keybinding … you can accomplish this using lambdas:
(global-set-key (kbd "C-c e") (lambda () (interactive) (eshell) (message "Eshell opened.")))
This is a simple example but you get the point.
4.2.7 Custom Functions
We can easily refactor our last keybinding to work with a custom function rather than writing the lambda syntax. This also makes refactoring code easier:
(defun launch-eshell () "Launch Eshell and message confirmation" (interactive) (eshell) (message "Launched Eshell")) (global-set-key (kbd "C-c e") 'launch-eshell)
- Finding Documentation
When writing new Lisp functions it can seem impossible at first to know what to do in the first place. The key to configuring Emacs is learning how to lookup Emacs’s built-in documentation. When searching for either a variable, keybinding, or function by name you can simply type:
C-h [item-prefix]
Item prefix above is to be replaced by the first letter of what you’re looking up (usually). So to lookup what a keybinding calls you can use:
C-h k
You will then be automatically prompted to type the key. Simply type it as you would call it.
- Example
Let’s say we want to jump to the end of a line in a new custom Lisp function. We know if we press C-e we will accomplish that. What function does that key call? Pressing C-h k –> C-e will respond with the following text in a new buffer:
C-e runs the command move-end-of-line (found in global-map), which is an interactive compiled Lisp function in ‘simple.el’. It is bound to C-e. (move-end-of-line ARG) Move point to end of current line as displayed. With argument ARG not nil or 1, move forward ARG - 1 lines first. If point reaches the beginning or end of buffer, it stops there. To ignore the effects of the ‘intangible’ text or overlay property, bind ‘inhibit-point-motion-hooks’ to t. If there is an image in the current line, this function disregards newlines that are part of the text on which the image rests.
This should give you all the information you need about the function move-end-of-line. If you press TAB or hover over where it says ‘simple.el’ and press ENTER it will take you to the actual Emacs source code for that function! If you encounter a function that is defined in the C source code, you will need a copy of that (however it’s somewhat rare).
- Example
4.2.8 Installing Packages
Another major aspect of configuring Emacs is installing packages. Even if you don’t continue to write your own Lisp functions or bindings, you’ll certainly find yourself installing more than a few packages.
Fortunately, Emacs has a built in package manager. You’ll want to configure that package manager to use the popular MELPA repository of packages in addition to the built-in ELPA repository (shown in example below).
- Auto Installing Packages
A great thing about configuring Emacs yourself is you can use Lisp to auto install packages you know you’ll need. If you keep your configuration in a remote repository you can simply pull your code and launch Emacs and your packages will be installed! Here’s a full example of configuring your packages:
(setq package-archives '(("elpa" . "http://tromey.com/elpa/") ("melpa" . "http://melpa.org/packages/"))) (setq myv-install-packages '( ;; actual list of packages i always install! helm magit web-mode projectile helm-projectile emmet-mode php-mode go-mode )) ;; Define which packages we want to auto verify install ;; every time Emacs is launched. (package-initialize) (unless package-archive-contents (package-refresh-contents)) (dolist (package myv-install-packages) (unless (package-installed-p package) (package-install package)))
5 Conclusion
If you’ve gotten this far you should be getting somewhat comfortable with setting up your own ~/.emacs file. You should know the syntax to set variables, create keybindings, install packages, and even write new functions and bind them to keys. Although this tutorial is nowhere near exhaustive it should give you a decent foundation to keep learning.
5.1 Further Learning
If there’s one link I can recommend it’s the GNU Manual for Emacs Lisp. This will teach you endless amounts of knowledge about configuring Emacs and specifically getting comfortable with Lisp.