User's Initialization File

User's Initialization File or dotemacs or init file is a file to store your configurations/customizations for Emacs written in Emacs Lisp, located at either ${HOME}/.emacs.d/init.el or (archaically) at ${HOME}/.emacs or at %HOME%\_emacs on MS Windows.

The most reliable way to find our the place of the initialization file on your system is to check the value of the user-init-file variable.

Configuration Example

For a good example of an init file check out some of the starter kits, like Prelude.

Debugging the Init file

Debug on init, debug on error

$ emacs --debug-init

Running the above command will enable the Emacs Lisp debugger for errors in the init file.

You can also use debug-on-error to get the debugger when an error occurs:

(setq debug-on-error t)

Identify what is causing an error message

Sometimes you see an error message, for example "Package cl is deprecated", but you can't find where it's coming from. Use debug-on-message:

(setq debug-on-message "Package cl is deprecated")

Bug-hunter - dissect the init file for you

A more advanced usage is to use elisp's bug hunter. It will find the source of the error for you. You can install it through ELPA and call it interactively:

 M-x bug-hunter-init-file RET e

So it will find easily where there's a parenthesis missing.

Test what function is taking most CPU

Use profiler.el to calculate and display the CPU profile of what Emacs functions take the most of the processing time.

Test if your init file is ok without reloading emacs

(see this blog post)

(defun my-test-emacs ()
  (interactive)
  (require 'async)
  (async-start
   (lambda () (shell-command-to-string
          "emacs --batch --eval \"
(condition-case e
    (progn
      (load \\\"~/.emacs.d/init.el\\\")
      (message \\\"-OK-\\\"))
  (error
   (message \\\"ERROR!\\\")
   (signal (car e) (cdr e))))\""))
   `(lambda (output)
      (if (string-match "-OK-" output)
          (when ,(called-interactively-p 'any)
            (message "All is well"))
        (switch-to-buffer-other-window "*startup error*")
        (delete-region (point-min) (point-max))
        (insert output)
        (search-backward "ERROR!")))))

How to package your config and packages

Will come a moment when you want to duplicate your emacs configuration into another computer. And you realize that you rely on a lot of third party packages that you don't want to re-install manually ! So how can we package our config, along with all our packages ? There are some options.

First you would obviously bundle everything into source control (except for a private file). Bitbucket and Gitlab.com offer private repos.

You then must read the page on package.el to see a way to list all the packages you use.

With Cask

You can use Cask to manage all the dependencies. A Cask file lists them all, like

   (depends-on "cask")
   (depends-on "dash")
   (depends-on "evil")

With use-package

Use-package (see below) is a macro that cleans emacs's configuration and speeds up its start up. We can use it also to manage our packages with package.el. See its documentation. The relevant packages are downloaded automatically once declared in your .emacs. The :ensure keyword causes the package(s) to be installed automatically if not already present on your system:

 (use-package magit
  :ensure t)

We can also choose prefered package sources (between GNU Elpa, Melpa-stable or Melpa), and more.

With org-mode

Some write their config in org-mode and load it with a call to org-babel, which is doable in one line in ~/.emacs.d/init.el:

   (require 'org)
   (require 'ob-tangle)
   (org-babel-load-file (expand-file-name "~/.emacs.d/myemacs.org"))

See an example config with Cask and org-mode.

some split it in multiple elisp files, some keep it in one big file.

Finally, to speed up the installation and ensure the same environment, you can also commit the pckages installed with package.el.

You can take inspiration from Starter Kits.

Speed up Emacs's start up

Use-package

Use-package is a macro that allows you to isolate package configuration in your .emacs file in a way that is both performance-oriented and, well, tidy. The author created it because he has over 80 packages that he uses in Emacs, and things were getting difficult to manage. Yet with this utility his total load time is around 2 seconds, with no loss of functionality. The key point is that it loads packages lazily. So your emacs starts up, you can start using it, and the longest loadings are done in the background.

The simplest use-package declaration looks like this:

 (use-package foo)

This loads in the package foo, but only if foo is available on your system.

Then we have keywords to add functionality. We can call code before and after a package is loaded (:init and :conf), :bind keybindings, do conditional loading, etc.

External links

The Init File (`(info "(emacs) The Init File")')
How Large is Your .emacs?