Difference between revisions of "User's Initialization File"

From WikEmacs
Jump to navigation Jump to search
(→‎Debugging the Init file: the elips bug hunter)
(→‎Debugging the Init file: add debug-on-message)
 
(5 intermediate revisions by the same user not shown)
Line 9: Line 9:
  
 
== Debugging the Init file ==
 
== Debugging the Init file ==
 +
 +
=== Debug on init, debug on error ===
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
Line 15: Line 17:
  
 
Running the above command will enable the Emacs Lisp debugger for errors in the init file.
 
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:
 +
 +
<syntaxhighlight lang="lisp">
 +
(setq debug-on-error t)
 +
</syntaxhighlight>
 +
 +
=== 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'':
 +
 +
<syntaxhighlight lang="lisp">
 +
(setq debug-on-message "Package cl is deprecated")
 +
</syntaxhighlight>
 +
 +
=== Bug-hunter - dissect the init file for you ===
  
 
A more advanced usage is to use [https://github.com/Malabarba/elisp-bug-hunter elisp's bug hunter]. It will find the source of the error for you. You can install it through [[ELPA]] and call it interactively:
 
A more advanced usage is to use [https://github.com/Malabarba/elisp-bug-hunter 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
 
   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 [http://oremacs.com/2015/03/05/testing-init-sanity/ this blog post])
 +
 +
<source lang="lisp">
 +
(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!")))))
 +
</source>
  
 
== How to package your config and packages ==  
 
== How to package your config and packages ==  
Line 24: Line 76:
 
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.
 
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 offer private repos.
+
First you would obviously bundle everything into source control (except for a private file). Bitbucket and [https://gitlab.com 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.
 
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
 
You can use [[Cask]] to manage all the dependencies. A Cask file lists them all, like
Line 34: Line 88:
 
     (depends-on "evil")
 
     (depends-on "evil")
  
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:  
+
=== 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 [https://github.com/jwiegley/use-package#for-packageel-users 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 'org)
Line 48: Line 113:
  
 
You can take inspiration from [[Starter Kits]].
 
You can take inspiration from [[Starter Kits]].
 +
 +
== Speed up Emacs's start up ==
 +
 +
=== Use-package ===
 +
 +
[https://github.com/jwiegley/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.
 +
  
 
== See Also ==
 
== See Also ==

Latest revision as of 16:16, 29 December 2022

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.


See Also

  • Prelude, a much more powerful and productive set of initial configuration than the one you get out of the box.
  • Emacs Starter Kit
  • package.el, the built-in package manager in Emacs 24.

External links