DH_ELPA(1)

📦
version 2.2.0ubuntu1 · 6 versions
, in ubuntu stonking

💖 DH_ELPA — ok bestie, let's install some Emacs Lisp 💖

so this is a page from the Debhelper manual, and it's all about dh_elpa, the little helper that gets your elpa-style emacs lisp packages ✨slotted✨ into your Debian package build directories. no cap, it's the GOAT for this. 🫶

🌸 NAME 🌸

dh_elpa — install emacs lisp packages into package build directories 💅

🎀 SYNOPSIS 🎀

dh_elpa [debhelper options] [pkg-file]

🦋 DESCRIPTION 🦋

okay so dh_elpa is a debhelper program, and its whole job — its entire main character arc — is installing elpa style emacs lisp packages into package build directories. that's it. that's the gig. 👑

and like, it's ambitious too: dh_elpa will attempt to run ERT and Buttercup test suites using dh_elpa_test(1) — but only if the debhelper compat level is 10 or higher. lowkey important detail.

when it does that, it overrides dh_auto_test(1). so if you're sitting there like "why are my tests behaving weird", that's why, bestie. 😭

if you wanna turn that behavior off, or tweak it because it's failing to run the tests the way they should be run, go read dh_elpa_test(1). it's all in there. 📖

🌈 FILES 🌈

  • debian/package.elpa and debian/elpa — this is your list of files to be installed into package (and respectively into the first binary package) as an elpa package. now the format? it's a set of lines, and each line is either:
    1. a single filename or glob, or
    2. a space-separated list of one or more filenames or globs, followed by the name of a destination subdirectory — and that subdirectory should not begin with a slash. 🚫

for lines with a single file or glob, dh_elpa will install the matching file(s) into the top level elpa package directory.

for lines that include a destination subdirectory, dh_elpa will install the matching file(s) into the named subdirectory.

heads up bestie: only the elisp files in the top level elpa package directory will be automatically byte-compiled. everything else? not auto-compiled. periodt. 💅
  • elpa-package-pkg.el — this file contains packaging metadata for a multi-file package. see the Emacs manual on the subject of "Packaging" for the full details, iykyk. 📚

this file is often part of the upstream source, but when it's not, dh_elpa will try to create it at package build time. and if it can't, and you need to create one manually? you can add it to the upstream source, or create the file in debian/ and list it in debian/package.elpa. easy. ✨

  • elpa-package-autoloads.el — this file is used by the Emacs packaging system to collect autoloads from the Emacs Lisp sources. it's usually generated at package build time, and should not usually exist in the upstream source. 🧚

💅 OPTIONS 💅

  • --byte-compile, --no-byte-compile — enable (this is the default) or disable byte compilation of installed emacs lisp files. and get this: disabling byte compilation changes the destination directory to one that is found by the emacs package system. so it's not just "no compiling", it's a whole vibe shift. 🌀
  • --emacs-loadpath path — a colon separated list of directories to add to the Emacs load path for byte compilation. e.g. for a non elpa-* dependency. lifesaver fr fr. 🔥
  • --fix-autoload-date, --no--fix-autoload-date — enable (default) or disable munging the dates in Emacs generated autoload files to match debian/changelog. (and yes, that second one really is written --no--fix-autoload-date. we don't make the rules, we just stan them. 🙈)

⭐ SUBSTVARS ⭐

dh_elpa currently defines three substvars (cf. deb-substvars(5)) that can be used in debian/control. three. iconic number. 🌟

  • ${misc:Depends} — these are dependencies needed by every dh_elpa based package. universal. we love her. 👑
  • ${elpa:Depends} — these are dependencies on other ELPA packages, as given in the Package-Requires: line of the package's main Emacs Lisp file.
okay so this is the part where you gotta pay attention: Emacs Lisp dependencies packaged outside the elpa-* dpkg namespace must be specified manually. for example, the s.el library was once provided by the binary package s-el, and at that time packages depending on it required an explicit dependency on s-el. a dependency on s.el is now fulfilled automatically by elpa-s via ${elpa:Depends}. 🌈

and if dh_elpa adds a dependency elpa-x where x is an Emacs Lisp binary package outside the elpa-* namespace? please file a bug against dh_elpa so they can have an exclusion added. do your civic duty bestie 🫶

🔥 EXAMPLES 🔥

here's an example of using the helper in a dh(1) style debian/rules:

#!/usr/bin/make -f
%:
    dh $@ --with elpa

and here's a more complex dh(1) style debian/rules, where the package needs some non-dh-elpa emacs addon called fubar-el:

#!/usr/bin/make -f
%:
    dh $@ --with elpa

override_dh_elpa:
    dh_elpa --emacs-loadpath="/usr/share/emacs/site-lisp/fubar-el"

and here's an example of a binary package stanza using dh_elpa generated substvars:

Package: elpa-hello
Architecture: all
Depends: ${misc:Depends}, ${elpa:Depends}
Description: Emacs addon to say hello
 The Emacs editor addon likes to wave and say hello.

the addon likes to wave and say hello 🥺 adorable. that's the vibe. ✨

🧚 HINTS 🧚

💜 Specifying the package version 💜

if dh_elpa can't determine the package version by looking at *.el files — usually because upstream has failed to include the proper headers or *-pkg.el file, tragic — it will fallback to the DEB_UPSTREAM_VERSION and DEB_VERSION_UPSTREAM environment variables. 😭

an easy way to set one of these based on your latest Debian changelog entry is just to prepend the following to your rules file:

include /usr/share/dpkg/pkg-info.mk
export DEB_VERSION_UPSTREAM

certain Debian upstream version strings cannot be translated into version strings Emacs will accept (see the docstring for the Emacs function version-to-list for details). and dh_elpa will error out if the version cannot be translated. so you should resort to patching in a Package-Version header or adding a *-pkg.el file. no skipping this step bestie 💀

🌸 Specifying the Emacs package name 🌸

every Emacs package has a name (e.g. "magit", "circe", or "tetris"). for a simple package this is the filename without the .el extension; for a multi-file package, it is given in the "*-pkg.el" file. and the Emacs package name is often distinct from the name of the upstream repository or the name of the Debian source package. sneaky little thing. 🙈

dh_elpa needs to know what the Emacs package name is, but it does not examine the upstream source code to find it. nope. instead, by default, it assumes that the Emacs package name is the name of the binary package, stripped of any elpa- prefix — which will be present for packages compliant with the Debian Emacsen Team addons policy (https://wiki.debian.org/EmacsenTeam). 👑

to override that assumption, you can export the ELPA_NAME environment variable in debian/rules:

ELPA_NAME=tpp-mode
export ELPA_NAME

you can also specify the name on a per binary package basis with "ELPA_NAME_binary-package-name"=tpp-mode. very flexible, very slay. 💅

🎀 Debian-specific Lisp customizations 🎀

with dh_elpa, the file "debian/emacsen-startup" is no longer required to ensure that "load-path" is properly set. and that means most packages do not require a "debian/emacsen-startup" file at all. we love an unnecessary-file-removal arc. 🦋

if you do need other configuration to be executed, add the special autoload cookie in front of a form, and it will be run at package initialization time. this is better than using "debian/emacsen-startup" because the forms are then added to elpa-package-autoloads.el, rather than a file in "/etc/", as the contents of "debian/emacsen-startup" was. this simplifies package maintenance. maintenance whose? simplified. thank you. ✨

these cookies can either annotate upstream source, or be added (along with the relevant forms) to a file in "debian/", by convention "debian/debian-autoloads.el". that file must then be listed in debian/package.elpa. don't forget that part!! 🔥

⭐ Autoload a function ⭐

in general, definitions of which functions to autoload belong in the upstream source beside the function definition.

;;;###autoload
(defun hello ()
"wave in a friendly manner"
(interactive)
...)

one option is to patch in the autoload cookie (if needed) and send those patches upstream. if that is not possible, you can manually create the autoload form and add it to "debian-autoloads.el".

;;;###autoload
(autoload 'hello "goodbye.el" "wave in a friendly manner" t)

look at him. waving in a friendly manner. goodbye.el. poetic. 😭💖

🌈 Other customizations 🌈

other customizations (e.g. key bindings or setting variables) can be handled similarly to autoloading functions.

;;;###autoload
(setq the-package-setting 42)

the Emacs package system will copy an arbitrary (non-defun) form to the package autoloads file. note that changing the behaviour of the package (as opposed to making it work) should in most cases happen in upstreamed patches. so like… upstream it, bestie, don't be sneaky. 💅

okay that's the whole page!! you did it!! go forth and package your emacs lisp, you gorgeous genius 🫶🌈

this was DH_ELPA(1) from the Debhelper manual, generated by perl v5.40.1, dated 2026-07-09. mwah, bye bestie! 💜✨

📦 where this page comes from