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.  To disable this behaviour, or tweak it if it is failing to run the tests as they
       should be run, set environment variables in debian/rules as detailed in 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 automaticaly 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 maintainance.

       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.