Provided by: dh-elpa_2.1.9ubuntu1_all 
NAME
dh_elpa - install emacs lisp packages into package build directories
SYNOPSIS
dh_elpa [debhelper options] [pkg-file]
DESCRIPTION
dh_elpa is a debhelper program that is responsible for installing elpa style emacs lisp packages into
package build directories.
dh_elpa will attempt to run ERT and Buttercup test suites using dh_elpa_test(1) if the debhelper compat
level is 10 or higher. This will override dh_auto_test(1). To disable this behaviour, or tweak it if it
is failing to run the tests as they should be run, see dh_elpa_test(1).
FILES
debian/package.elpa
debian/elpa
List of files to be installed into package (respectively into the first binary package) as an elpa
package. The format is a set of lines, where each line is either (i) a single filename or glob, or
(ii) a space-separated list of one or more filenames or globs, followed by the name of a destination
subdirectory (which should not begin with a slash).
For lines with a single file or glob, dh_elpa will install matching file(s) into the top level elpa
package directory.
For lines which include a destination subdirectory, dh_elpa will install matching file(s) into the
named subdirectory.
Only elisp files in the top level elpa package directory will be automatically byte-compiled.
elpa-package-pkg.el
This file contains packaging metadata for a multi-file package -- see the Emacs manual on the subject
of "Packaging" for full details.
This file is often part of the upstream source, but when it is not, dh_elpa will try to create it at
package build time. If it cannot, 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.
elpa-package-autoloads.el
This file is used by the Emacs packaging system to collect autoloads from the Emacs Lisp sources. It
is usually generated at package build time, and should not usually exist in the upstream source.
OPTIONS
--byte-compile, --no-byte-compile
Enable (default) or disable byte compilation of installed emacs lisp files. Disabling byte
compilation changes the destination directory to one that is found by the emacs package system.
--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).
--fix-autoload-date, --no--fix-autoload-date
Enable (default) or disable munging the dates in Emacs generated autoload files to match
debian/changelog.
SUBSTVARS
dh_elpa currently defines three substvars (cf. deb-substvars(5)) that can be used in debian/control
${misc:Depends}
These are dependencies needed by every dh_elpa based package.
${elpa:Depends}
These are dependencies on other ELPA packages as given in the Package-Requires: line of the package's
main Emacs Lisp file.
Note that 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}.
If dh_elpa adds dependency elpa-x where x is an Emacs Lisp binary package outside the elpa-*
namespace, please file a bug against dh_elpa to have an exclusion added.
EXAMPLES
Here is an example of using the helper in a dh(1) style debian/rules
#!/usr/bin/make -f
%:
dh $@ --with elpa
Here is a more complex dh(1) style debian/rules, where the package needs some non-dh-elpa emacs addon
fubar-el
#!/usr/bin/make -f
%:
dh $@ --with elpa
override_dh_elpa:
dh_elpa --emacs-loadpath="/usr/share/emacs/site-lisp/fubar-el"
Here is 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.
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), 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). dh_elpa will error out if the
version cannot be translated. You should resort to patching in a Package-Version header or adding a
*-pkg.el file.
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. The
Emacs package name is often distinct from the name of the upstream repository or the name of the Debian
source package.
dh_elpa needs to know what the Emacs package name is, but it does not examine the upstream source code to
find it. 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.
Debian-specific Lisp customizations
With dh_elpa, the file "debian/emacsen-startup" is no longer required to ensure that "load-path" is
properly set. This means that most packages do not require a "debian/emacsen-startup" file at all.
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.
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.
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)
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.
Changing the behaviour of the package (as opposed to making it work) should in most cases happen in
upstreamed patches.
perl v5.40.1 2025-03-14 DH_ELPA(1)