quelpa / quelpa-use-package

Emacs quelpa handler for use-package

Build and install your Emacs Lisp packages on-the-fly and directly from source.

News

• 2022/09/26: Support elpa-devel version scheme (e.x, 0.27.0.20220914.164819) with :vertion-type quelpa in recipes
• 2021/03/12: Switch default from shallow clone to partial clone for git recipes

Contents

• Overview
• Requirements
• Installation
• Usage
• Why “Quelpa”?

Overview

quelpa is a tool to compile and install Emacs Lisp packages locally from local or remote source code.

Given a recipe in MELPA’s format, for example:

(quelpa '(hydra :repo "abo-abo/hydra" :fetcher github))

quelpa gets the package source code, builds an ELPA compatible package and installs that locally with package.el. The installed packages can then be managed in the usual way with M-x list-packages.

quelpa can be used in many ways, for example to manage your personal packages, testing development versions of other packages or as a helper when developing a package to test building, compiling and installing it.

To get an idea how to use it to manage your Emacs setup, take a look at the steckemacs configuration, which uses quelpa-use-package to integrate with use-package.

You can build and install packages from (fetcher names in parens): Git (git), GitHub (github), Bazaar (bzr), Mercurial (hg), Subversion (svn), CVS (cvs), Darcs (darcs), Fossil (fossil) and EmacsWiki (wiki)

Requirements

• Emacs 25.1
• tar
• git (recommend version >= 2.20): http://git-scm.com/

Every build requires the corresponding build tool. To install a subversion hosted package, you need to have subversion installed.

Note: Even if the sources of a package are fetched with a VCS tool you have installed, they might have dependencies that require a different VCS tool. Better install the most common ones before proceeding.

Installation

You may install quelpa like this:

• Using MELPA, run M-x package-install RET quelpa RET.
• Alternatively, place file quelpa.el into a directory in your Emacs load-path, then use (require 'quelpa) in your init file.
• If you want to bootstrap quelpa automatically from your init file, you can use this snippet:

(unless (package-installed-p 'quelpa)
  (with-temp-buffer
    (url-insert-file-contents "https://raw.githubusercontent.com/quelpa/quelpa/master/quelpa.el")
    (eval-buffer)
    (quelpa-self-upgrade)))

Usage

Cool. Now that we are all setup, enjoy the ride.

• Installing packages
• Upgrading packages
• Managing packages
• Using tagged versions
• Additional recipe fetchers
• Additional options

Installing packages

There are two ways to install packages with Quelpa:

By package name

• Interactively, use M-x quelpa RET, then input a package name with completion.
• In Lisp code, use (quelpa 'package-name).

This will fetch the package’s source code from its repository, build the package, and install it.

By recipe

You can also install packages that are not on MELPA by providing a recipe in the proper format. For example, call quelpa with a recipe like:

(quelpa '(discover-my-major :fetcher git :url "https://framagit.org/steckerhalter/discover-my-major.git"))

Once you installed a package with its own recipe, Quelpa will remember it and next time it can offer you to upgrade/install the package again with M-x quelpa RET.

Upgrading packages

By default, Quelpa does not upgrade installed packages. You can enable upgrading globally by running M-x customize-variable RET quelpa-upgrade-p RET.

To override the default and upgrade individual packages:

• Interactively, call quelpa with a universal prefix argument, like C-u M-x quelpa RET.
• From Lisp, call quelpa with the keyword argument :upgrade, like (quelpa 'package-name :upgrade t).
• Interactively, call M-x quelpa-upgrade RET, it will list all Quelpa installed packages.

When evaluating a buffer of quelpa calls, you may prevent a package from being upgraded by setting :upgrade nil, like (quelpa 'package-name :upgrade nil).

Upgrading all packages

You may choose to upgrade all Quelpa-installed packages at Emacs startup, but that can slow down Emacs’s startup considerably.

Alternatively, you may upgrade all Quelpa-installed packages using M-x quelpa-upgrade-all RET. This command relies on the cache file, set in variable quelpa-cache-file. It is updated after every quelpa invocation.

By default, when upgrading all packages, Quelpa also upgrades itself. Disable this by setting variable quelpa-self-upgrade-p to nil.

To run quelpa-upgrade-all at most every 7 days, after all the init files are loaded:

(setq quelpa-upgrade-interval 7)
(add-hook #'after-init-hook #'quelpa-upgrade-all-maybe)

Managing packages

Quelpa installs packages using Emacs’s built-in package library, package.el, so after installing a package with Quelpa, you can view its status and remove it using M-x list-packages RET. Note that deleting a package this way does not yet affect Quelpa’s cache, so Quelpa will still consider the package to have been installed with Quelpa.

Quelpa will automatically remove obsoleted package versions after upgrading. Disable this by setting quelpa-autoremove-p to nil.

Alternatively, you may prevent a package old version from being removed by setting :autoremove nil, like (quelpa 'foo :autoremove nil).

Also, here is the default actions of each Quelpa command related to removing packages:

• M-x quelpa-upgrade-all, M-x quelpa-upgrade, C-u M-x quelpa will by default remove obsoleted packages
• M-x quelpa will by default not remove obsoleted package.

Using tagged versions

Quelpa can be instructed to build tagged versions of packages. This means that the Git or Mercurial repository is queried for a tagged version, and if one is found, that version will be built. For more information please see MELPA’s notes on stable packages.

To enable building of tagged versions globally, set variable quelpa-stable-p to t.

To do so for a single package:

• Using the quelpa command, use the command’s keyword argument :stable, like (quelpa 'package-name :stable t).
• In a package’s recipe, use the same keyword, like (quelpa '(package-name :stable t)).

Using the argument to the quelpa command overrides the global setting quelpa-stable-p, and using the argument in a recipe overrides both the command argument and the global setting.

Note: Non-tagged package version numbers are generated at build time using the current date, and these numbers usually are sorted as higher than tagged version numbers. Therefore, if you have installed a non-tagged package version and wish to replace it with a tagged version, you must first remove the package, then install the tagged version.

Note: Tagged versions are commonly referred to as “stable” versions (since these are the versions appearing in the MELPA Stable repo). However, such package versions are not necessarily more stable than the untagged versions provided in the non-“Stable” MELPA repo, and using them is not generally recommended. Therefore, we do not refer to such versions as “stable” versions.

Additional recipe fetchers

You may use these additional fetchers in recipes:

URL

The url fetcher builds packages from single .el files. The URL may be a remote HTTP one or a local file:// one. For example:

(quelpa
 '(rainbow-mode :fetcher url
                :url "http://git.savannah.gnu.org/cgit/emacs/elpa.git/plain/packages/rainbow-mode/rainbow-mode.el"))

Note:

• By default, upgrades are managed through file hashes, so if the content has changed, Quelpa will upgrade the package.
• Existing version numbers are retained. Quelpa uses a version suffix that allows the original version to retain priority, so if you install a package from another source with the same version, it will be preferred.
  • To omit the Quelpa-specific version suffix, use the parameter :version original. For example:

(quelpa
 '(queue :version original :fetcher url
         :url "http://www.dr-qubit.org/download.php?file=predictive/queue.el" ))

File

The file fetcher builds single-file packages from local .el files. For example:

(quelpa
 '(rainbow-mode :fetcher file
                :path "/home/user/src/rainbow-mode/rainbow-mode.el"))

It also builds multi-file packages from a local directory. For example:

(quelpa
 '(rainbow-mode :fetcher file
                :path "~/src/rainbow-mode"))

Note:

• Specifying a directory for :path does not retain existing version numbers, nor does it respect the :version original parameter.
• Paths are expanded with expand-file-name, so ~ in path names is expanded to the user’s home directory.

Github SSH

The github-ssh fetcher builds packages from github ssh link, it’s alternative of github fetcher which builds packages from https link. For example, the following recipe will clone Quelpa from [email protected]:quelpa/quelpa.git and builds it:

(quelpa '(quelpa :fetcher github-ssh :repo "quelpa/quelpa"))

Note:

• You should setup Github ssh key before using this.
• This fetcher will come handy when you want to modify the packages and contribute back without the needs of enter password everytime.

Additional options

Prevent updating of MELPA repo on Emacs startup

By default, when Quelpa is loaded, it updates the local clone of the MELPA git repo, which ensures that the latest recipes are always available. If you load Quelpa in your init file, this naturally lengthens Emacs’s startup time. You may disable this by setting quelpa-update-melpa-p to nil before loading Quelpa.

If you don’t want to use MELPA recipes at all (e.g. if you’re using Quelpa mainly to install packages not in MELPA) you can disable all fetching of the MELPA repo by setting quelpa-checkout-melpa-p to nil.

Use local recipes

You may configure Quelpa to use recipes stored in a local directory in preference to those in MELPA. This may be helpful if you wish to modify a MELPA recipe. The variable quelpa-melpa-recipe-stores is a list of directory paths which are searched for recipes; by default, it contains the path to the local MELPA clone’s recipes directory. Directories listed in the variable are searched in order, so to give your own recipe directory preference, add it to the front of the list, like:

(add-to-list 'quelpa-melpa-recipe-stores "/home/user/src/recipes")

If a package’s recipe is not found in that directory, Quelpa will fall back on remaining directories in the list, including the MELPA recipe directory.

Recipe files should be named after the package name, without any filename extension.

Why “Quelpa”?

The German word quelle means spring (as in: water source) but also source. Source code is translated to quellcode. ELPA is the abbreviation for Emacs Lisp Package Archive. You get the idea.

quelpa-use-package's Issues

:quelpa with recipe tries to install package from MELPA when `use-package-always-ensure` is `t`

Trying to install the kite-mini package (which is not on MELPA) using a recipe, when I evaluate:

(use-package kite-mini
  :quelpa (kite-mini :fetcher github :repo "tungd/kite-mini.el"))

Emacs enters the debugger on the following error:

Debugger entered--Lisp error: (error "Package `kite-mini-' is unavailable")
  signal(error ("Package `kite-mini-' is unavailable"))
  error("Package `%s-%s' is unavailable" kite-mini "")
  package-compute-transaction(nil ((kite-mini)))
  package-install(kite-mini)
  use-package-ensure-elpa(kite-mini t)
  use-package-ensure-elpa(kite-mini)
  use-package-handler/:ensure(kite-mini :ensure t (:quelpa ((kite-mini :fetcher github :repo "tungd/kite-mini.el")) :config (t)) nil)
  use-package-process-keywords(kite-mini (:ensure t :quelpa ((kite-mini :fetcher github :repo "tungd/kite-mini.el")) :config (t)))
  #[(name &rest args) "\306�\235?\205\321�  ;\203��\307 !\202�� �\310\n�\"\311\312���\313
\f\"\203(�
\202-�\314
\f�#+�'\315�(\203R��'\316�(���\313
\f\"\203I�
\202N�\314
\f�#+\202T��'!�)\317\320!\203\241���\203\241��)\321\322\323\324\325\326�)\327\"\"\330\331\332\n\"�*\205��\333\334\335\nDE\326�)\336\"?\205\215�\337\335\nDDFC\"B���\314
\f�\326
\f\"B#+�)\340\341\n�)\"!�+�,\203\316�\342r\343\344!�-r�-q\210ed|\210\345 \210\346�+!c\210)�-*!\210�+,\207" [args name name-symbol value property plist :disabled intern use-package-normalize-plist :config (t) plist-member plist-put use-package-sort-keywords :ensure boundp byte-compile-current-file :preface eval-when-compile append mapcar #[(var) "\301�D\207" [var defvar] 2] plist-get :defines with-demoted-errors format "Cannot load %s: %%S" message "Compiling package %s" quote :no-require require macroexp-progn use-package-process-keywords display-buffer get-buffer-create "*use-package*" emacs-lisp-mode pp-to-string args0 use-package-always-ensure args* use-package-verbose body use-package-debug buf] 11 ("/home/miki/.emacs.d/elpa/use-package-20150801.830/use-package.elc" . 28977)](kite-mini :quelpa (kite-mini :fetcher github :repo "tungd/kite-mini.el"))
  macroexpand((use-package kite-mini :quelpa (kite-mini :fetcher github :repo "tungd/kite-mini.el")))
  eval-defun-2()
  eval-defun(nil)
  call-interactively(eval-defun nil nil)
  command-execute(eval-defun)

I've customized use-package-always-ensure to t, which I think is the cause of the problem.
For now, I use the following workaround:

(use-package kite-mini
  :ensure nil
  :quelpa (kite-mini :fetcher github :repo "tungd/kite-mini.el"))

but I think it would be nice if quelpa-use-package could be modified to strip the :ensure t when the user has provided a recipe with :quelpa.

Add quelpa-use-package to MELPA

It would be handy to have quelpa-use-package on MELPA as well. It would simplify the bootstrapping of Spacemacs which uses ELPA repos.

Shorter recipe when using defaults

Most of :quelpa recipes I use are just downloaded from github so to avoid duplications I'd like to write them like:

(use-package fnhh
  :quelpa "a13/fnhh"
  :config
  (fnhh-mode 1))

instead of the current

(use-package fnhh
  :quelpa
  (fnhh :repo "a13/fnhh" :fetcher github)
  :config
  (fnhh-mode 1))

I think it's very easy to (and I'm ready to) implement such functionality in use-package-normalize/:quelpa, so we can get package name from name-symbol, the default :fetcher keyword can be a defcustom, which defaults to github.

github fetcher still installs the existing melpa package

I wanna install my own fork repo instead of the melpa one, but with the following config, use-package still installs the melpa package. Is it the expected behavior or I did something wrong? and what should I do to ignore the existing melpa package?

(require 'use-package)
(setq use-package-always-ensure t)

(use-package quelpa
  :config
  (setq quelpa-update-melpa-p t)
  )

(use-package quelpa-use-package
  :init
  (setq use-package-ensure-function 'quelpa)
  :config
  (quelpa-use-package-activate-advice))

(use-package org-pdftools
  :after quelpa quelpa-use-package
  :ensure nil
  :quelpa ((org-pdftools
	    :fetcher github
	    :repo "ST-Saint/org-pdftools"))
  :hook (org-mode . org-pdftools-setup-link))

How to copy static files to the "elpa" directory when build finished?

Quelpa will download the package in "quelpa/build/", and build ".el" and ".elc" files to the "elpa" directory to load it.

Sometimes I need the static files from package, so can I copy the static files when build finished?

Example:
files in quelpa:

files in elpa:

Add something similar to `use-package-always-ensure` for quelpa

I'd like to install most of my packages from quelpa without having to specify a bare :quelpa in all of them.

use-package-always-ensure currently will add an :ensure t or something similar, to each block implicitly if it doesn't already specify :ensure

Error: wrong type argument: package-desc, nil

Hi, I'm new with quelpa.
I tried to install manateelazycat/awesome-tray with quelpa, but I got this error:
wrong type argument: package-desc, nil
This is my elisp code:

(use-package awesome-tray
      :quelpa (awesome-tray :fetcher github :repo "manateelazycat/awesome-tray"))
;;      :init (awesome-tray-mode 1))

Elisp source of awesome-tray seems to be downloaded (quelpa/build), but not interpreted :/

Allow for the use of expressions rather than stringp

Apologies in advance if I use the wrong terminology. I'm very new to elisp, but after searching and asking it seems that I'm hitting a bug in either quelpa or quelpa-use-package.

I'm trying to do this:

(use-package evil-org :ensure nil
 :quelpa (evil-org
    :fetcher file
    :path (concat my-package-directory "evil-org")))

and getting

Quelpa: failed to checkout `evil-org': `Wrong type argument: stringp, (concat my-package-directory "evil-org")'

From some fairly generic searching I've also tried

,(concat my-package-directory "evil-org")

and

`(,(concat my-package-directory "evil-org"))

but none work.

On a regular quelpa function call this works (which is why I'm submitting this issue here):

(quelpa `(evil-org :fetcher file :path ,(concat my-package-directory "evil-org")))

And if I really want to make things messy I can do this:

(eval `(use-package evil-org
  :ensure nil
  :quelpa (evil-org
        :fetcher file
        :path ,(concat my-package-directory "evil-org")))

Is there some magic syntax I'm missing to make that concat evaluate before being expanded into the macro?

Thanks!

Automatically install package if not present, like ":ensure t"

Would it be possible to use the :ensure t in a quelpa recipe, or an other keyword, for the package to be installed automatically if it isn't already?
I know I can use :upgrade t to achieve this but I don't want to updated it every time I run emacs. I just want it to be install my package with quelpa if it is not present.

Cannot make quelpa-use-package work for help-fns+

Hello, I am using M-x emacs-version

GNU Emacs 26.1 (build 2, arm-unknown-linux-gnueabihf) of 2019-09-23, modified by Debian

on lsb_release -d

Description:    Raspbian GNU/Linux 10 (buster)

I cannot make quelpa-use-package work for help-fns+. FWIW, help-fns+ was a MELPA package, but have been removed from MELPA, and the source of this package is in https://www.emacswiki.org/emacs/help-fns%2b.el.

I am a user of use-package and I want to use help-fns+ via quelpa-use-package.

Here is the .emacs file:

# --------8<--------8<--------8<--------8<--------8<--------8<--------
$ cat .emacs-quelpa-help-fns+
(require 'package)
(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

(eval-when-compile
  (require 'use-package))

(use-package quelpa-use-package
  :ensure t)

(use-package help-fns+
  :quelpa (help-fns+ :fetcher wiki)
  ;; :quelpa (help-fns+ :fetcher url :url "https://www.emacswiki.org/emacs/download/help-fns+.el")
  ;; :quelpa (help-fns+ :fetcher url :url "https://www.emacswiki.org/emacs/download/help-fns%2b.el")
  ;; :quelpa (help-fns+ :fetcher github :repo "emacsmirror/help-fns-plus")
  :after help-fns)
# --------8<--------8<--------8<--------8<--------8<--------8<--------

I launch it with:

emacs -Q -l .emacs-quelpa-help-fns+

When I use :quelpa (help-fns+ :fetcher wiki), I have the error:

Fetcher: wiki
Contacting host: www.emacswiki.org:443
quelpa-checkout: Failed to checkout ‘help-fns+’: ‘HTTP error 400 fetching https://www.emacswiki.org/emacs/download/help-fns+.el’

When I use :quelpa (help-fns+ :fetcher url :url "https://www.emacswiki.org/emacs/download/help-fns+.el"), I have the error:

Fetcher: url
Source: https://www.emacswiki.org/emacs/download/help-fns+.el

Contacting host: www.emacswiki.org:443
Wrote /home/thierry/.emacs.d/quelpa/build/help-fns+/help-fns+.el
Error getting PACKAGE-DESC: (error Package lacks a file header)
quelpa-checkout: Failed to checkout ‘help-fns+’: ‘Wrong type argument: package-desc, nil’

When I use :quelpa (help-fns+ :fetcher url :url "https://www.emacswiki.org/emacs/download/help-fns%2b.el"), I have the error:

Fetcher: url
Source: https://www.emacswiki.org/emacs/download/help-fns%2b.el

Contacting host: www.emacswiki.org:443
Wrote /home/thierry/.emacs.d/quelpa/build/help-fns+/help-fns%2b.el
Error getting PACKAGE-DESC: (error Package lacks a file header)
quelpa-checkout: Failed to checkout ‘help-fns+’: ‘Wrong type argument: package-desc, nil’

When I use :quelpa (help-fns+ :fetcher github :repo "emacsmirror/help-fns-plus"), I have the error:

Fetcher: github
Source: emacsmirror/help-fns-plus

Cloning https://github.com/emacsmirror/help-fns-plus.git to /home/thierry/.emacs.d/quelpa/build/help-fns+/
quelpa-checkout: Failed to checkout ‘help-fns+’: ‘Command ’(env LC_ALL=C /usr/bin/timeout -k 60 600 git clone https://github.com/emacsmirror/help-fns-plus.gi\
t /home/thierry/.emacs.d/quelpa/build/help-fns+/ --origin origin --depth 1 --no-single-branch)’ exited with non-zero status 128: Cloning into '/home/thierry/\
.emacs.d/quelpa/melpa'...
fatal: unable to access 'https://github.com/melpa/melpa.git/': The requested URL returned error: 503
Cloning into '/home/thierry/.emacs.d/quelpa/build/help-fns+'...
fatal: unable to access 'https://github.com/emacsmirror/help-fns-plus.git/': The requested URL returned error: 503
’

My issue is maybe only a "how do I" question...
Thanks in advance for your help

Startup time of quelpa-use-package is high

I am currently profiling my emacs startup time and the highest time is spent in the quelp-use-package bootstrapping. Is there a solution to lower this?
My configuration

• OS - macos Catalina
• Machine macbook pro 13"
• emacs - 26.3

I am using following to bootstrap quelpa-use-package

(quelpa
 '(quelpa-use-package
   :fetcher git
   :url "https://github.com/quelpa/quelpa-use-package.git"))

I used esup to profile the startup time. It takes 10% of the startup time (around 3 seconds) for the above code snippet.

how do I specify a specific branch for a git repo?

Suppose I want to grab the evil-compat branch from https://github.com/myrjola/multiple-cursors.el, which provides a compatibility layer for evil.

how can I specify this specific branch? I was thinking in something like this:

(use-package multiple-cursors
  :ensure nil
  :quelpa (multiple-cursors
           :fetcher github
           :repo "myrjlola/multiple-cursors.el"
           :branch "evil-compat"))

It seems to install the elpa package as well

(use-package quelpa-use-package
  :ensure t
  :config (setq use-package-ensure-function 'quelpa))

(use-package
  dart-mode
  ;;:ensure t
  :quelpa ((dart-mode :fetcher github
                      :repo "bradyt/dart-mode") :upgrade t)
  :config (setq dart-format-on-save t))

Installs the (old) package into ~/.emacs.d/elpa/... and ~/.emacs.d/quelpa/build/...
and then the elpa version is loaded, which is what I actually tried to avoid.

Am I doing something wrong?

Allow omitting redundant package name

In (use-package foobar :quelpa (foobar :repo ...))) the foobar to use-package should always be the same as the foobar in the recipe. It would be nicer not to have to specify it twice, and just use (use-package foobar :quelpa (:repo ...))).

Looking in the code, there's already a case which looks like the intention might be to handle this. However, the pcase is on (car args) rather than args, so (:repo ...) gets caught by the (pred symbolp) and returns the original argument list instead. However, I'm not sure if this a bug or handling another real situation.

Quelpa: Fetch repo subdirectory

Cross-posted to spacemacs.
I raised this issue in the wrong repo, maybe it would worth to wait for an answer from spacemacs.

I wanted to fetch org-krita with

  (use-package org-krita
    :quelpa (org-krita :fetcher git :url "https://github.com/lepisma/org-krita")
    :ensure t)  

or

(use-package org-krita
    :quelpa (org-krita :fetcher github :repo "lepisma/org-krita" )
    :ensure t) 

But the important subdirectory /resources that must be cloned so that the package works correctly has not been fetched.
Currently, the following packages are installed:

• quelpa-use-package version 20200307.805
• quelpa version 20200903.825
  The problem is that spacemacs comes along with its own quelpa in core/library. I don't know which variant of quelpa has been used, so I posted here the issue.

Q. How to clone subdirectory with quelpa ?

quelpa :upgrade attribute has no effect in quelpa-use-package

This was working for a while but sometime around last October I realized that my quelpa packages were no longer being updated, and if I delete them they don't get re-installed. I am using quelpa-use-package to install the newest version of cc-mode, so I have this in my emacs init:

(use-package cc-mode
  :ensure t
  :quelpa (cc-mode :fetcher hg
                   :url "http://hg.code.sf.net/p/cc-mode/cc-mode"
                   :upgrade t))

This used to work but now is a no-op. I didn't notice so I'm not sure when it changed but the last time my cc-mode was updated was Oct 2020. Now when I start Emacs if I look in my messages buffer I see:

Newer package has been installed. Not upgrading.

and no updates are done.

Debugging shows that the :upgrade setting that I've given is ignored, and quelpa's quelpa-upgrade-p variable is nil, not t which is what I want, when it runs the quelpa-build method.

I was able to force it to install by evaluating this in my scratch buffer:

(quelpa '(cc-mode :fetcher hg
                  :url "http://hg.code.sf.net/p/cc-mode/cc-mode")
        :upgrade t)

Note, that the :upgrade attribute must appear outside of the package definition; it's a plist attribute for the invocation of the quelpa function; an :upgrade attribute inside the package definition is ignored. It seems that the quelpa-use-package wrapper isn't managing this attribute as expected?