DH_ELPA(1) Debhelper DH_ELPA(1)

dh_elpa - install emacs lisp packages into package build directories

dh_elpa [debhelper options] [pkg-file]

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).

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.

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.

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.

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.
A colon separated list of directories to add to the Emacs load path for byte compilation (e.g. for a non elpa-* dependency).
Enable (default) or disable munging the dates in Emacs generated autoload files to match debian/changelog.

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.

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.

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.

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.

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.

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 (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.

2023-09-15 perl v5.36.0