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