391 lines
15 KiB
EmacsLisp
391 lines
15 KiB
EmacsLisp
;;; use-package --- A use-package declaration for simplifying your .emacs
|
||
|
||
;; Copyright (C) 2012 John Wiegley
|
||
|
||
;; Author: John Wiegley <jwiegley@gmail.com>
|
||
;; Created: 17 Jun 2012
|
||
;; Version: 1.0
|
||
;; Keywords: dotemacs startup speed config package
|
||
;; X-URL: https://github.com/jwiegley/use-package
|
||
|
||
;; This program is free software; you can redistribute it and/or
|
||
;; modify it under the terms of the GNU General Public License as
|
||
;; published by the Free Software Foundation; either version 2, or (at
|
||
;; your option) any later version.
|
||
|
||
;; This program is distributed in the hope that it will be useful, but
|
||
;; WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
;; General Public License for more details.
|
||
|
||
;; You should have received a copy of the GNU General Public License
|
||
;; along with GNU Emacs; see the file COPYING. If not, write to the
|
||
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
||
;; Boston, MA 02111-1307, USA.
|
||
|
||
;;; Commentary:
|
||
|
||
;; The `use-package' declaration macro allows you to isolate package
|
||
;; configuration in your ".emacs" in a way that is performance-oriented and,
|
||
;; well, just tidy. I created it because I have over 80 packages that I use
|
||
;; in Emacs, and things were getting difficult to manage. Yet with this
|
||
;; utility my total load time is just under 1 second, with no loss of
|
||
;; functionality!
|
||
;;
|
||
;; Here is the simplest `use-package' declaration:
|
||
;;
|
||
;; (use-package foo)
|
||
;;
|
||
;; This loads in the package foo, but only if foo is available on your system.
|
||
;; If not, a warning is logged to your `*Messages*' buffer. If it succeeds a
|
||
;; message about "Loading foo" is logged, along with the time it took to load,
|
||
;; if that time is over 0.01s.
|
||
;;
|
||
;; Use the :init keywoard to do some stuff to initialize foo, but only if foo
|
||
;; actually gets loaded:
|
||
;;
|
||
;; (use-package foo
|
||
;; :init
|
||
;; (progn
|
||
;; (setq foo-variable t)
|
||
;; (foo-mode 1)))
|
||
;;
|
||
;; A very common thing to do when loading a module is to bind a key to primary
|
||
;; commands within that module:
|
||
;;
|
||
;; (use-package ace-jump-mode
|
||
;; :bind ("C-." . ace-jump-mode))
|
||
;;
|
||
;; This does two things: first, it creates autoload for the `ace-jump-mode'
|
||
;; command, and defers loading of `ace-jump-mode' until you actually use it.
|
||
;; Second, it binds the key `C-.' to that command. After loading, you can use
|
||
;; `M-x describe-personal-keybindings' to see all such bindings you've set
|
||
;; throughout your Emacs.
|
||
;;
|
||
;; A more literal way to do the exact same thing is:
|
||
;;
|
||
;; (use-package ace-jump-mode
|
||
;; :commands ace-jump-mode
|
||
;; :init
|
||
;; (bind-key "C-." 'ace-jump-mode))
|
||
;;
|
||
;; When you use the `:commands' keyword, it creates autoloads for those
|
||
;; commands and defers loading of the module until they are used. In this
|
||
;; case, the `:init' form is always run -- even if ace-jump-mode might not be
|
||
;; on your system. So remember to keep `:init' activities to only those that
|
||
;; would succeed either way.
|
||
;;
|
||
;; If you aren't used `:commands' or `:bind' (which implies `:commands'), you
|
||
;; can still defer loading with `:defer' keyword:
|
||
;;
|
||
;; (use-package ace-jump-mode
|
||
;; :defer t
|
||
;; :init
|
||
;; (progn
|
||
;; (autoload 'ace-jump-mode "ace-jump-mode" nil t)
|
||
;; (bind-key "C-." 'ace-jump-mode)))
|
||
;;
|
||
;; This does exactly the same thing as the other two commands above.
|
||
;;
|
||
;; A companion to the `:init' keyword is `:config'. Although `:init' always
|
||
;; happens in the case of deferred modules (which are likely to be the most
|
||
;; common kind), `:config' form only run after the module has been loaded by
|
||
;; Emacs:
|
||
;;
|
||
;; (use-package ace-jump-mode
|
||
;; :bind ("C-." . ace-jump-mode)
|
||
;; :config
|
||
;; (message "Yay, ace-jump-mode was actually loaded!"))
|
||
;;
|
||
;; You will see a "Configured..." message in your `*Messages*' log when a
|
||
;; package is configured, and a timing if the configuration time was longer
|
||
;; than 0.01s. You should keep `:init' forms as simple as possible, and put
|
||
;; as much as you can get away with on the `:config' side.
|
||
;;
|
||
;; You can have both `:init' and `:config':
|
||
;;
|
||
;; (use-package haskell-mode
|
||
;; :commands haskell-mode
|
||
;; :init
|
||
;; (add-to-list 'auto-mode-alist '("\\.l?hs$" . haskell-mode))
|
||
;; :config
|
||
;; (progn
|
||
;; (use-package inf-haskell)
|
||
;; (use-package hs-lint)))
|
||
;;
|
||
;; In this case, I want to autoload the command `haskell-mode' from
|
||
;; "haskell-mode.el", add it to `auto-mode-alist' at the time ".emacs" is
|
||
;; loaded, but wait until after I've opened a Haskell file before loading
|
||
;; "inf-haskell.el" and "hs-lint.el".
|
||
;;
|
||
;; The `:bind' keyword takes either a cons or a list of conses:
|
||
;;
|
||
;; (use-package hi-lock
|
||
;; :bind (("M-o l" . highlight-lines-matching-regexp)
|
||
;; ("M-o r" . highlight-regexp)
|
||
;; ("M-o w" . highlight-phrase)))
|
||
;;
|
||
;; The `:commands' keyword likewise takes either a symbol or a list of
|
||
;; symbols.
|
||
;;
|
||
;; You can use the `:if' keyword to predicate the loading and initialization
|
||
;; of a module. For example, I only want an `edit-server' running for my
|
||
;; main, graphical Emacs, not for Emacsen I may start at the command line:
|
||
;;
|
||
;; (use-package edit-server
|
||
;; :if window-system
|
||
;; :init
|
||
;; (progn
|
||
;; (add-hook 'after-init-hook 'server-start t)
|
||
;; (add-hook 'after-init-hook 'edit-server-start t)))
|
||
;;
|
||
;; The `:disabled' keyword can be used to turn off a module that you're having
|
||
;; difficulties with, or to stop loading something you're not really using at
|
||
;; the present time:
|
||
;;
|
||
;; (use-package ess-site
|
||
;; :disabled t
|
||
;; :commands R)
|
||
;;
|
||
;; Another feature of `use-package' is that it always loads every file that it
|
||
;; can when your ".emacs" is being byte-compiled (if you do that, which I
|
||
;; recommend). This helps to silence spurious warnings about unknown
|
||
;; variables and functions.
|
||
;;
|
||
;; However, there are times when this is just not enough. For those times,
|
||
;; use the `:defines' keyword to introduce empty variable definitions solely
|
||
;; for the sake of the byte-compiler:
|
||
;;
|
||
;; (use-package texinfo
|
||
;; :defines texinfo-section-list
|
||
;; :commands texinfo-mode
|
||
;; :init
|
||
;; (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
|
||
;;
|
||
;; If you need to silence a missing function warning, do it with an autoload
|
||
;; stub in your `:init' block:
|
||
;;
|
||
;; (use-package w3m
|
||
;; :commands (w3m-browse-url w3m-session-crash-recovery-remove)
|
||
;; :init
|
||
;; (eval-when-compile
|
||
;; (autoload 'w3m-search-escape-query-string "w3m-search")))
|
||
;;
|
||
;; Lastly, `use-package' provides built-in support for the diminish utility,
|
||
;; if you have that installed. It's purpose is to remove strings from your
|
||
;; mode-line that would otherwise always be there and provide no useful
|
||
;; information. It is invoked with the `:diminish' keyword, which is passed
|
||
;; the minor mode symbol:
|
||
;;
|
||
;; (use-package abbrev
|
||
;; :diminish abbrev-mode
|
||
;; :init
|
||
;; (if (file-exists-p abbrev-file-name)
|
||
;; (quietly-read-abbrev-file))
|
||
;;
|
||
;; :config
|
||
;; (add-hook 'expand-load-hook
|
||
;; (lambda ()
|
||
;; (add-hook 'expand-expand-hook 'indent-according-to-mode)
|
||
;; (add-hook 'expand-jump-hook 'indent-according-to-mode))))
|
||
;;
|
||
;; If you noticed that this declaration has neither a `:bind', `:commands' or
|
||
;; `:defer' keyword: congratulations, you're an A student! What it means is
|
||
;; that both the `:init' and `:config' forms will be executed when ".emacs" is
|
||
;; loaded, with no delays until later. Is this useful? Not really. I just
|
||
;; happen to like separating my configuration into things that must happen at
|
||
;; startup time, and things that could potentioally wait until after the
|
||
;; actual load. In this case, everything could be put inside `:init' and
|
||
;; there would be no difference.
|
||
;;
|
||
;; * For el-get users
|
||
;;
|
||
;; You can use `use-package' as a way to create source definitions for el-get.
|
||
;; All that's needed is to add a `:type' keyword to your declaration. When
|
||
;; this is present, certain keywords get translated to what el-get expects in
|
||
;; the `el-get-sources' list:
|
||
;;
|
||
;; :config -> :after
|
||
;; :requires -> :depends
|
||
;;
|
||
;; A `:name' will be added also, if one is not provided explicitly, which will
|
||
;; be the same as the name of the package.
|
||
;;
|
||
;; But why would you want to use `use-package' when you have el-get? My
|
||
;; answer is that I'd like to use el-get to install and update some packages,
|
||
;; but I don't want it managing configuration. Just loading el-get -- without
|
||
;; call (el-get 'sync) -- takes a quarter second on my machine. That's 25% of
|
||
;; my load time! `use-package' is designed for performance, so I only want to
|
||
;; load el-get when it's time to install or update on of my used packages.
|
||
;;
|
||
;; Here is the `use-package' declaration I use for setting up el-get, but only
|
||
;; when I want to install or update:
|
||
;;
|
||
;; (defvar el-get-sources nil)
|
||
;;
|
||
;; (use-package el-get
|
||
;; :commands (el-get
|
||
;; el-get-install
|
||
;; el-get-update
|
||
;; el-get-list-packages)
|
||
;; :config
|
||
;; (defun el-get-read-status-file ()
|
||
;; (mapcar #'(lambda (entry)
|
||
;; (cons (plist-get entry :symbol)
|
||
;; `(status "installed" recipe ,entry)))
|
||
;; el-get-sources)))
|
||
|
||
(require 'bind-key)
|
||
|
||
(defgroup use-package nil
|
||
"A use-package declaration for simplifying your .emacs"
|
||
:group 'startup)
|
||
|
||
;;;_ , Create use-package macro, to simplify customizations
|
||
|
||
(eval-when-compile
|
||
(require 'cl))
|
||
|
||
(require 'bind-key)
|
||
(require 'diminish nil t)
|
||
|
||
(defcustom use-package-verbose t
|
||
"Whether to report about loading and configuration details."
|
||
:type 'boolean
|
||
:group 'use-package)
|
||
|
||
(defmacro with-elapsed-timer (text &rest forms)
|
||
`(let ((now ,(if use-package-verbose
|
||
'(current-time))))
|
||
,(if use-package-verbose
|
||
`(message "%s..." ,text))
|
||
,@forms
|
||
,(when use-package-verbose
|
||
`(let ((elapsed
|
||
(float-time (time-subtract (current-time) now))))
|
||
(if (> elapsed 0.01)
|
||
(message "%s...done (%.3fs)" ,text elapsed)
|
||
(message "%s...done" ,text))))))
|
||
|
||
(put 'with-elapsed-timer 'lisp-indent-function 1)
|
||
|
||
(defmacro use-package (name &rest args)
|
||
(let* ((commands (plist-get args :commands))
|
||
(init-body (plist-get args :init))
|
||
(config-body (plist-get args :config))
|
||
(diminish-var (plist-get args :diminish))
|
||
(defines (plist-get args :defines))
|
||
(keybindings (plist-get args :bind))
|
||
(predicate (plist-get args :if))
|
||
(pkg-load-path (plist-get args :load-path))
|
||
(defines-eval (if (null defines)
|
||
nil
|
||
(if (listp defines)
|
||
(mapcar (lambda (var) `(defvar ,var)) defines)
|
||
`((defvar ,defines)))))
|
||
(requires (plist-get args :requires))
|
||
(requires-test (if (null requires)
|
||
t
|
||
(if (listp requires)
|
||
`(not (member nil (mapcar #'featurep
|
||
(quote ,requires))))
|
||
`(featurep (quote ,requires)))))
|
||
(name-string (if (stringp name) name
|
||
(symbol-name name))))
|
||
|
||
(if diminish-var
|
||
(setq config-body
|
||
`(progn
|
||
,config-body
|
||
(ignore-errors
|
||
,@(if (listp diminish-var)
|
||
(mapcar (lambda (var) `(diminish (quote ,var)))
|
||
diminish-var)
|
||
`((diminish (quote ,diminish-var))))))))
|
||
|
||
(when keybindings
|
||
(if (and commands (symbolp commands))
|
||
(setq commands (list commands)))
|
||
(setq init-body
|
||
`(progn
|
||
,init-body
|
||
,@(mapcar #'(lambda (binding)
|
||
(push (cdr binding) commands)
|
||
`(bind-key ,(car binding)
|
||
(quote ,(cdr binding))))
|
||
(if (and (consp keybindings)
|
||
(stringp (car keybindings)))
|
||
(list keybindings)
|
||
keybindings)))))
|
||
|
||
(unless (plist-get args :disabled)
|
||
`(progn
|
||
,@(mapcar
|
||
#'(lambda (path)
|
||
`(add-to-list 'load-path
|
||
,(expand-file-name path user-emacs-directory)))
|
||
(if (stringp pkg-load-path)
|
||
(list pkg-load-path)
|
||
pkg-load-path))
|
||
|
||
(eval-when-compile
|
||
,@defines-eval
|
||
,(if (stringp name)
|
||
`(load ,name t)
|
||
`(require ',name nil t)))
|
||
|
||
,(when (and (boundp 'el-get-sources)
|
||
(plist-get args :type))
|
||
(setq args
|
||
(mapcar #'(lambda (arg)
|
||
(cond
|
||
((eq arg :config)
|
||
:after)
|
||
((eq arg :requires)
|
||
:depends)
|
||
(t
|
||
arg)))
|
||
args))
|
||
(unless (plist-get args :name)
|
||
(nconc args (list :name (if (stringp name)
|
||
name (symbol-name name)))))
|
||
(nconc args (list :symbol (if (stringp name)
|
||
(intern name) name)))
|
||
`(push (quote ,args) el-get-sources))
|
||
|
||
,(if (or commands (plist-get args :defer))
|
||
(let (form)
|
||
(unless (listp commands)
|
||
(setq commands (list commands)))
|
||
(mapc #'(lambda (command)
|
||
(push `(autoload (function ,command)
|
||
,name-string nil t) form))
|
||
commands)
|
||
|
||
`(when ,(or predicate t)
|
||
,@form
|
||
,init-body
|
||
,(unless (null config-body)
|
||
`(eval-after-load ,name-string
|
||
'(if ,requires-test
|
||
(with-elapsed-timer
|
||
,(format "Configuring package %s" name-string)
|
||
,config-body))))
|
||
t))
|
||
`(if (and ,(or predicate t)
|
||
,requires-test)
|
||
(with-elapsed-timer
|
||
,(format "Loading package %s" name-string)
|
||
(if (not ,(if (stringp name)
|
||
`(load ,name t)
|
||
`(require ',name nil t)))
|
||
(message "Could not load package %s" ,name-string)
|
||
,init-body
|
||
,config-body
|
||
t))))))))
|
||
|
||
(put 'use-package 'lisp-indent-function 1)
|
||
|
||
(provide 'use-package)
|
||
|
||
;;; use-package.el ends here
|