This brief guide assumes you’re using a recent Ubuntu or Ubuntu-based GNU/Linux release (I’m using Xubuntu 13.04), and covers install/config of Emacs 24.

For working with Clojure, I suggest GNU Emacs. Reasons for this include:

Install

On current Ubuntu-based distributions:

sudo apt-get install emacs24

Emacs Configuration

If you don’t already have a ~/.emacs.d directory, create one. Emacs will store some things there later on.

Start Emacs from the command line (run emacs) and the GTK-based GUI version should start up. Configure it as follows:

  1. Go to the “Options” menu. Make sure the following menu items have check marks next to them:

    • Highlight Active Region
    • Highlight Matching Parentheses

    You might also do “Options → Set Default Font” to choose a different font if you’re not happy with the default (I recommend Inconsolata (sudo apt-get install fonts-inconsolata)).

    Then go to “Options → Save Options” and Emacs will create a ~/.emacs file for you and write some configuration info into it.

  2. Quit Emacs (“File → Quit”).

  3. Your freshly-created ~/.emacs file will contain some code at the top. Underneath that, using any editor you please, add a blank line, and:

    (require 'package)
(add-to-list 'package-archives
             '("marmalade" . "http://marmalade-repo.org/packages/"))
(package-initialize)

    and save the file. If you added that using Emacs, “File –> Quit” Emacs now.

  4. Start Emacs again. Hit M-x (aka, Alt-x), then type “package-install” (no quotes), hit RET (Return), type “clojure-mode”, then RET again. This will have the built-in Emacs package installer install clojure-mode (into your ~/.emacs.d/elpa directory) for you.

  5. Open your ~/.emacs file again (in any editor) and append the following to it:

    (setq-default inhibit-startup-screen t)

;; Uncomment the next line if you'd like to stop Emacs from
;; automatically creating and leaving "foo~" backup files
;; all over the place.
;(setq make-backup-files nil)

;; Spaces only (no tab characters at all)!
(setq-default indent-tabs-mode nil)

;; Always show column numbers.
(setq-default column-number-mode t)

;; Display full pathname for files.
(add-hook 'find-file-hooks
          '(lambda ()
             (setq mode-line-buffer-identification 'buffer-file-truename)))

;; For easy window scrolling up and down.
(global-set-key "\M-n" 'scroll-up-line)
(global-set-key "\M-p" 'scroll-down-line)

;; For easier access to regex search/replace.
(defalias 'qrr 'query-replace-regexp)

    Save your ~/.emacs file and quit Emacs if it’s running.

That’s it. Emacs should now be all set. To test it out, start up Emacs by running emacs ~/temp/foo.clj (assuming you have a ~/temp directory) and type in the following:

;; Count out loud to 3.
(dotimes [n 3]
  (println "hi" n))

Save by using the “File → Save” menu item. The file should be syntax-highlighted and the bar near the bottom of the Emacs window should say “(Clojure)----” in it. Quit Emacs by using the “File → Quit” menu item.

If you’re not crazy about the current colortheme, do “M-x load-theme RET” then hit TAB to tab-complete and see the list of built-in choices available (then type the name and hit Enter to try it out).

If none of those really suits your fancy, I suggest installing wonderful dark low-contrast zenburn:

M-x package-install RET zenburn-theme RET

To set Emacs to always use a given color theme — for example, zenburn — add this line near the end of your ~/.emacs file:

(load-theme 'zenburn t)

10-minute Emacs Tutorial

You can start Emacs from the command line like so: emacs. However, you’ll more commonly run it as “emacs &” in order to get your command line back after Emacs starts. :)

In Emacs, when you open a file it lives in a “buffer”, and that buffer is displayed, and you can edit it — and, if you like, save its contents back to the file from whence it came. The main Emacs window shows you one buffer at a time unless you split the window (the command for that is shown below). There are other buffers in Emacs that show other things besides files (for example, a buffer that shows all the files you currently have open).

Terminology Note: Emacs uses the term “frame” to mean the top-level desktop window within which Emacs is running. Emacs provides commands (described below) for splitting the display within the frame. Emacs uses the term “window” to mean one of the areas inside the frame (which may have been split).

So, the upshot is that when the Emacs docs talk about moving the cursor from one window to another, they mean moving between those split areas in the main Emacs app desktop window.

Emacs editing commands use the Ctrl and Alt keys, but Emacs calls the Alt key “Meta” instead of “Alt”. Emacs users write Ctrl-a as “C-a”, and they write Alt-x as “M-x” (that’s why, above, I wrote “M-x package-install” instead of “Alt-x package-install”).

To run Emacs editing commands, you can use menu items (with the mouse) while you’re still learning their keyboard combinations (which are printed alongside the menu items). If you like, you can type in Emacs just like a common GUI editor. Arrow keys, Home/End, and PgUp/PgDn all work as you’d expect. Ctrl-Arrows to move the cursor forward/back by-word and up/down by-paragraph. You can even use the mouse, if you’re so inclined. That said, you’ll probably eventually want to learn the more customary Emacs key combos to do most tasks (for more comfortable and faster editing).

Emacs hierarchically arranges some commands “underneath” other commands. That is to say, for some commands, you first must hit a prefix command (for example, C-x), and then — within that context — you can hit the command you’re looking for. For example, to open a file, you hit C-x, and then Emacs listens for the next key combo. “C-x C-f” (hit C-x, release, then hit C-f) is for opening a file, “C-x C-s” is for saving a file. Another example: “C-h t” (hit Ctrl-h, release, then tap the “t” key) is for running the built-in Emacs tutorial.

A few Emacs commands require you to hold down Ctrl and Alt at the same time while tapping another key (for example, regex incremental search, shown in the table below).

More terminology: Emacs uses the term “point” to refer to the cursor position, and “region” to mean a text area you have selected. Incidentally, to select text in Emacs you first hit a key command to begin the selection (C-Space), then move the cursor around to choose what gets selected.

One initial tip to start off with: C-g is to cancel whatever command you’re in the middle of. When in doubt, C-g to bail out.

Here are a number of useful Emacs key combos that will get you pretty far:

key combo resulting editor command
C-x C-f open a file
C-x k RET close current file (“kill buffer”)
C-x C-s save
C-x C-c quit
C-Space begin text selection
C-g cancel
C-w cut
M-w copy
M-y paste
M-h select current paragraph
C-s incremental search (RET to stop)
C-r incremental search backward
C-M-s regex incremental search
C-M-r regex incremental search backward
M-% search/replace
M-x qrr regex search/replace (our custom short name)
M-q re-wrap (reflow, justify) paragraph
M-; comment/uncomment region
C-/ undo
M-/ complete word (like tab-complete)
C-f move cursor forward
C-b move cursor back
M-f move cursor forward-by-word
M-b move cursor backward-by-word
C-n move cursor to next line
C-p move cursor to prev line
M-n scroll view down
M-p scroll view up
C-l scroll to middle and redraw screen
C-a move cursor to beginning of line
C-e move cursor to end of line
M-m move cursor to first non-whitespace char
M-{ move cursor up-by-paragraph
M-} move cursor down-by-paragraph
C-v page down
M-v page up
M-< go to top of buffer
M-> go to end of buffer
M-g M-g n go to line number n
C-x 2 split window horizontally
C-x 3 split window vertically
C-x o move cursor to other window
C-x b RET make window show other buffer
C-x 0 close current window (after splitting)
C-x 1 close any other windows

Finally, know that you can run any Emacs command using its long name by hitting M-x, then typing the name, then Enter. For example, to delete trailing whitespace throughout your file: “M-x delete-trailing-whitespace RET”. To “untabify” (convert tabs to spaces) a given selected region: “M-x untabify”.

If you’d like a longer and more leisurely Emacs tutorial, you might try the built-in one: “C-h t”. You can access all Emacs docs from within the editor (see “C-h ?”), or online, if you prefer. GNU also sells a dead-tree version (see the Emacs page for details).

You might also search the web for interesting tutorials. I happen to have written one myself (oof, though I need to update it for Emacs 24!).

Incidentally, one cosmic hub of much Emacs knowledge is the EmacsWiki. Also, find Clojure+Emacs-related projects at https://github.com/clojure-emacs.

Closing Note

Do note that there are other, arguably more productive and sophisticated Emacs configurations out there (ones that, for example, run a repl inside an Emacs buffer so you can paste code into that repl from within Emacs). This guide currently takes the simpler approach to get you going more quickly.