.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_ELPA 1"
.TH DH_ELPA 1 "2021-01-28" "perl v5.32.0" "Debhelper"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dh_elpa \- install emacs lisp packages into package build directories
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdh_elpa\fR [\fIdebhelper\ options\fR]  [\fIpkg-file\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdh_elpa\fR is a debhelper program that is responsible for installing
elpa style emacs lisp packages into package build directories.
.PP
\&\fBdh_elpa\fR will attempt to run \s-1ERT\s0 and Buttercup test suites using
\&\fBdh_elpa_test\fR\|(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 \fBdh_elpa_test\fR\|(1).
.SH "FILES"
.IX Header "FILES"
.IP "debian/\fIpackage\fR.elpa" 4
.IX Item "debian/package.elpa"
.PD 0
.IP "debian/elpa" 4
.IX Item "debian/elpa"
.PD
List of files to be installed into \fIpackage\fR (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).
.Sp
For lines with a single file or glob, \fBdh_elpa\fR will install matching
file(s) into the top level elpa package directory.
.Sp
For lines which include a destination subdirectory, \fBdh_elpa\fR will
install matching file(s) into the named subdirectory.
.Sp
Only elisp files in the top level elpa package directory will be
automatically byte-compiled.
.IP "\fIelpa-package\fR\-pkg.el" 4
.IX Item "elpa-package-pkg.el"
This file contains packaging metadata for a multi-file package \*(-- see
the Emacs manual on the subject of \*(L"Packaging\*(R" for full details.
.Sp
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 \f(CW\*(C`debian/\*(C'\fR and list it in
debian/\fIpackage\fR.elpa.
.IP "\fIelpa-package\fR\-autoloads.el" 4
.IX Item "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.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-byte\-compile\fR, \fB\-\-no\-byte\-compile\fR" 4
.IX Item "--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.
.IP "\fB\-\-emacs\-loadpath\fR \fIpath\fR" 4
.IX Item "--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).
.IP "\fB\-\-fix\-autoload\-date\fR, \fB\-\-no\*(--fix\-autoload\-date\fR" 4
.IX Item "--fix-autoload-date, --nofix-autoload-date"
Enable (default) or disable munging the dates in Emacs generated
autoload files to match debian/changelog.
.SH "SUBSTVARS"
.IX Header "SUBSTVARS"
dh_elpa currently defines three substvars (cf. \fBdeb\-substvars\fR\|(5)) that
can be used in debian/control
.IP "${misc:Depends}" 4
.IX Item "${misc:Depends}"
These are dependencies needed by every dh_elpa based package.
.IP "${elpa:Depends}" 4
.IX Item "${elpa:Depends}"
These are dependencies on other \s-1ELPA\s0 packages as given in the
Package-Requires: line of the package's main Emacs Lisp file.
.Sp
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}.
.Sp
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.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Here is an example of using the helper in a \fBdh\fR\|(1) style debian/rules
.Sp
.Vb 3
\&    #!/usr/bin/make \-f
\&    %:
\&        dh $@ \-\-with elpa
.Ve
.PP
Here is a more complex \fBdh\fR\|(1) style debian/rules, where the package
needs some non-dh-elpa emacs addon \fIfubar-el\fR
.Sp
.Vb 3
\&    #!/usr/bin/make \-f
\&    %:
\&        dh $@ \-\-with elpa
\&
\&    override_dh_elpa:
\&        dh_elpa \-\-emacs\-loadpath="/usr/share/emacs/site\-lisp/fubar\-el"
.Ve
.PP
Here is an example of a binary package stanza using dh_elpa generated
substvars
.Sp
.Vb 5
\&    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.
.Ve
.SH "HINTS"
.IX Header "HINTS"
.SS "Specifying the package version"
.IX Subsection "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
\&\s-1DEB_UPSTREAM_VERSION\s0 and \s-1DEB_VERSION_UPSTREAM\s0 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:
.Sp
.Vb 2
\&    include /usr/share/dpkg/pkg\-info.mk
\&    export DEB_VERSION_UPSTREAM
.Ve
.PP
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.
.SS "Specifying the Emacs package name"
.IX Subsection "Specifying the Emacs package name"
Every Emacs package has a name (e.g. \f(CW\*(C`magit\*(C'\fR, \f(CW\*(C`circe\*(C'\fR, or
\&\f(CW\*(C`tetris\*(C'\fR).  For a simple package this is the filename without the
\&'.el' extension; for a multi-file package, it is given in the
\&\f(CW\*(C`*\-pkg.el\*(C'\fR file.  The Emacs package name is often distinct from the
name of the upstream repository or the name of the Debian source
package.
.PP
\&\fBdh_elpa\fR 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>).
.PP
To override that assumption, you can export the \fB\s-1ELPA_NAME\s0\fR
environment variable in debian/rules:
.Sp
.Vb 2
\&    ELPA_NAME=tpp\-mode
\&    export ELPA_NAME
.Ve
.PP
You can also specify the name on a per binary package basis with
\&\f(CW\*(C`ELPA_NAME_binary\-package\-name\*(C'\fR=tpp\-mode.
.SS "Debian-specific Lisp customizations"
.IX Subsection "Debian-specific Lisp customizations"
With \fBdh_elpa\fR, the file \f(CW\*(C`debian/emacsen\-startup\*(C'\fR is no longer
required to ensure that \f(CW\*(C`load\-path\*(C'\fR is properly set.  This means that
most packages do not require a \f(CW\*(C`debian/emacsen\-startup\*(C'\fR file at all.
.PP
If you do need other configuration to be executed, add the special
\&\fIautoload cookie\fR in front of a form, and it will be run at package
initialization time.  This is better than using
\&\f(CW\*(C`debian/emacsen\-startup\*(C'\fR because the forms are then added to
\&\fIelpa-package\fR\-autoloads.el, rather than a file in \f(CW\*(C`/etc/\*(C'\fR, as the
contents of \f(CW\*(C`debian/emacsen\-startup\*(C'\fR was.  This simplifies package
maintenance.
.PP
These cookies can either annotate upstream source, or be added (along
with the relevant forms) to a file in \f(CW\*(C`debian/\*(C'\fR, by convention
\&\f(CW\*(C`debian/debian\-autoloads.el\*(C'\fR.  That file must then be listed in
debian/\fIpackage\fR.elpa.
.IP "Autoload a function" 4
.IX Item "Autoload a function"
In general definitions of which functions to autoload belong in the
upstream source beside the function definition.
.Sp
.Vb 5
\&    ;;;###autoload
\&    (defun hello ()
\&    "wave in a friendly manner"
\&    (interactive)
\&    ...)
.Ve
.Sp
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 \f(CW\*(C`debian\-autoloads.el\*(C'\fR.
.Sp
.Vb 2
\&    ;;;###autoload
\&    (autoload \*(Aqhello "goodbye.el" "wave in a friendly manner" t)
.Ve
.IP "Other customizations" 4
.IX Item "Other customizations"
Other customizations (e.g. key bindings or setting variables) can be
handled similarly to autoloading functions.
.Sp
.Vb 2
\&    ;;;###autoload
\&    (setq the\-package\-setting 42)
.Ve
.Sp
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.