#!/usr/bin/perl

=head1 NAME

dh_elpa - install emacs lisp packages into package build directories

=cut

use strict;
use Cwd qw{ getcwd };
use File::Temp qw{tempfile};
use IO::Handle;
use File::Path;

use Debian::Debhelper::Dh_Lib;

=head1 SYNOPSIS

B<dh_elpa> [S<I<debhelper options>>]  [S<I<pkg-file>>]

=head1 DESCRIPTION

B<dh_elpa> is a debhelper program that is responsible for installing
elpa style emacs lisp packages into package build directories.

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

=head1 FILES

=over 4

=item debian/I<package>.elpa

=item debian/elpa

List of files to be installed into I<package> (respectively into the
first binary package) as an elpa package.

=item I<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 C<debian/> and list it in
debian/I<package>.elpa.

=item I<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.

=back

=cut

init(options => {
        "emacs-loadpath=s" => \$dh{EMACS_LOADPATH},
	"byte-compile!" => \$dh{BYTECOMPILE},
	"fix-autoload-date!" => \$dh{FIXAUTOLOADDATE},
});

=head1 OPTIONS

=over 4

=item B<--byte-compile>, B<--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.

=back

=over 4

=item B<--emacs-loadpath> I<path>

A colon separated list of directories to add to the Emacs load path
for byte compilation (e.g. for a non elpa-* dependency).

=back

=over 4

=item B<--fix-autoload-date>, B<--no--fix-autoload-date>

Enable (default) or disable munging the dates in Emacs generated
autoload files to match debian/changelog.

=back

=cut

sub doit_quietly {
  my ($handle,$tmpfile) = tempfile(UNLINK=>1);
  my $exitcode;

  verbose_print(escape_shell(@_));
  open (CPERR,">&STDERR") or error "$!";
  open (CPOUT,">&STDOUT") or error "$!";
  STDOUT->fdopen($handle,'w');
  STDERR->fdopen($handle,'w');
  my $ret=doit_noerror(@_);
  STDOUT->fdopen(\*CPOUT,'w');
  STDERR->fdopen(\*CPERR,'w');

  if (!$ret){
    $exitcode=$?;
    seek $handle, 0, 0 or error "$!";
    print while (<$handle>);
    my $command=join(" ",@_);
    error("$command returned exit code ".($exitcode >> 8));
  }

}

# simplified version of private sub autoscript_sed in Dh_Lib
sub sed_file {
  my ($sed, $infile, $outfile) = @_;

  open(IN, $infile) or die "$infile: $!";
  open(OUT, ">>$outfile") or die "$outfile: $!";
  while (<IN>) { $sed->(); print OUT }
  close(OUT) or die "$outfile: $!";
  close(IN) or die "$infile: $!";
}

sub read_package_desc {
  my ($descdir, $package) = @_;
  my %desc = ();

  my $descfile="${descdir}/${package}.desc";

  my $fh;

  open $fh,'<', $descfile or
    error "failed to open $descfile";

  while (<$fh>) {
    if (m/([^:]+):\s*(.*)\s*$/) {
      $desc{$1} = $2;
    }
  }
  return \%desc;
}

my $templatedir = "/usr/share/debhelper/dh_elpa/emacsen-common";

sub maybe_install_helper{
  my ($package,$piece, $mode, $desc, $emacs_loadpath)=@_;
  my $file=pkgfile($package,"emacsen-$piece");

  my $tmp=tmpdir($package);
  my $ecdest="$tmp/usr/lib/emacsen-common/packages";
  my $target="$ecdest/$piece/$package";
  # if there is file, leave it for dh_installemacsen
  if ($file eq '') {
    if (! -d "$ecdest/$piece") {
      doit("install","-d","$ecdest/$piece");
    }
    unlink $target; # ignore errors

    my $elpapackage = $desc->{'ELPA-Name'} or
      error "elpa package name not found";

    my $elpaversion = $desc->{'ELPA-Version'};
    error "elpa version not found" if (!defined($elpaversion));

    sed_file (sub {s/#ELPAPACKAGE#/$elpapackage/;
                   s/#ELPAVERSION#/$elpaversion/;
                   s/#EMACSLOADPATH#/$emacs_loadpath/; },
              "$templatedir/$piece", $target);
    chmod oct($mode), $target;
  }
}

$dh{BYTECOMPILE} = 1 unless defined($dh{BYTECOMPILE});
$dh{FIXAUTOLOADDATE} = 1 unless defined($dh{FIXAUTOLOADDATE});

my $elpadir;

my $dhelpadir="/usr/share/emacs/site-lisp/elpa";

# TODO: do we really need a seperate elpa-src hierarchy?
if ($dh{BYTECOMPILE}) {
  $elpadir="/usr/share/emacs/site-lisp/elpa-src";
} else {
  $elpadir=$dhelpadir;
}

PACKAGE:
foreach my $package (@{$dh{DOPACKAGES}}) {

  my $tmp=tmpdir($package);
  my $file=pkgfile($package,"elpa");

  my $varname="ELPA_NAME_${package}";
  my $elpapkg = $ENV{$varname} || $ENV{ELPA_NAME};
  if (!defined($elpapkg)) {
    verbose_print("Guessing elpa package name from package name $package");

    $elpapkg = $package;
    $elpapkg =~ s/^elpa-//;
  }
  verbose_print("Using elpa package name $elpapkg");

  my @files;

  # Call isnative because it sets $dh{VERSION}
  # as a side effect.
  isnative($package);
  if ($file) {
    @files=filearray($file, ".");
    scalar(@files) == 1 || grep { m/\b${elpapkg}-pkg.el$/ } @files or
      warning "missing ${elpapkg}-pkg.el; will try to generate it";
  }
  if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL})
      && @ARGV) {
    push @files, @ARGV;
  }

  next PACKAGE if (scalar(@files) == 0);

  my $pkg_file;
  my $cwd = getcwd();
  my $tempdir = "${cwd}/debian/.debhelper/elpa";
  my $helper_version = '@HELPER_VERSION@';

  my @extra_args = ( $tempdir );
  my $emacs_loadpath = "";

  if (defined $dh{EMACS_LOADPATH}) {
    $emacs_loadpath = $dh{EMACS_LOADPATH} . ':'
  }

  if ($dh{FIXAUTOLOADDATE}) {
    push @extra_args, get_source_date_epoch();
  }

  File::Path::rmtree $tempdir ||
      error "cleaning $tempdir";

  File::Path::make_path $tempdir ||
	  error "creating $tempdir";

  if (scalar(@files) == 1) {
      my $pkg_file=$files[0];

      doit_quietly(qw{emacs -batch -Q -l package},
		   '--eval',"(add-to-list 'package-directory-list \"$dhelpadir\")",
		   '--eval',"(add-to-list 'package-directory-list \"$elpadir\")",
		   qw{-f package-initialize -l dh-elpa.el},
		   qw{-f dhelpa-batch-install-file}, "$tmp/$elpadir", $pkg_file, @extra_args);
  } else {
    my $stagedir = "$tempdir/$elpapkg";
    File::Path::make_path $stagedir ||
	  error "creating $stagedir";

    # copy files into stagedir, flattening hierarchy
    # TODO: do this more correctly
    foreach my $el_file (@files) {
      doit("cp", "-a", $el_file, "$stagedir");
    }

    doit_quietly(qw{emacs -batch -Q -l package},
		 '--eval',"(add-to-list 'package-directory-list \"$dhelpadir\")",
		 '--eval',"(add-to-list 'package-directory-list \"$elpadir\")",
		 qw{-f package-initialize -l dh-elpa.el},
		 qw{-f dhelpa-batch-install-directory},
		 "$tmp/$elpadir", $stagedir, @extra_args);

  }

  my $desc = read_package_desc ($tempdir,$elpapkg);
  my $deps = $desc->{'ELPA-Requires'};

  # TODO: addsubstvar fails to add a variable if its blank.  So if the
  # package has no ELPA dependencies, we should tell the user not to
  # use this substvar in debian/control
  addsubstvar($package, 'elpa:Depends', $deps);

  if ($dh{BYTECOMPILE}) {
    addsubstvar($package, 'misc:Depends', 'emacsen-common');
    maybe_install_helper($package, 'compat', '0644', $desc, $emacs_loadpath);
    maybe_install_helper($package, 'install', '0755', $desc, $emacs_loadpath);
    maybe_install_helper($package, 'remove', '0755', $desc, $emacs_loadpath);

    if (! $dh{NOSCRIPTS}) {
      autoscript($package,"postinst","postinst-emacsen",
                 "s/#PACKAGE#/$package/");
      autoscript($package,"prerm","prerm-emacsen",
                 "s/#PACKAGE#/$package/");
    }
  }

}

=head1 SUBSTVARS

dh_elpa currently defines three substvars (cf. deb-substvars(5)) that
can be used in debian/control

=over 4

=item ${misc:Depends}

These are dependencies needed by every dh_elpa based package.

=item ${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.

=back

=head1 EXAMPLES

Here is an example of using the helper in a dh(1) style debian/rules

=over 4

    #!/usr/bin/make -f
    %:
        dh $@ --with elpa

=back

Here is a more complex dh(1) style debian/rules, where the package
needs some non-dh-elpa emacs addon I<fubar-el>

=over 4

    #!/usr/bin/make -f
    %:
        dh $@ --with elpa

    override_dh_elpa:
        dh_elpa --emacs-loadpath="/usr/share/emacs/site-lisp/fubar-el"

=back

Here is an example of a binary package stanza using dh_elpa generated
substvars

=over 4

    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.

=back

=head1 HINTS

=head2 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:

=over 4

    include /usr/share/dpkg/pkg-info.mk
    export DEB_VERSION_UPSTREAM

=back

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.

=head2 Specifying the Emacs package name

Every Emacs package has a name (e.g. C<magit>, C<circe>, or
C<tetris>).  For a simple package this is the filename without the
'.el' extension; for a multi-file package, it is given in the
C<*-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.

B<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
(L<https://wiki.debian.org/EmacsenTeam>).

To override that assumption, you can export the B<ELPA_NAME>
environment variable in debian/rules:

=over 4

    ELPA_NAME=tpp-mode
    export ELPA_NAME

=back

You can also specify the name on a per binary package basis with
C<ELPA_NAME_binary-package-name>=tpp-mode.

=head2 Debian-specific Lisp customizations

With B<dh_elpa>, the file C<debian/emacsen-startup> is no longer
required to ensure that C<load-path> is properly set.  This means that
most packages do not require a C<debian/emacsen-startup> file at all.

If you do need other configuration to be executed, add the special
I<autoload cookie> in front of a form, and it will be run at package
initialization time.  This is better than using
C<debian/emacsen-startup> because the forms are then added to
I<elpa-package>-autoloads.el, rather than a file in C</etc/>, as the
contents of C<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 C<debian/>, by convention
C<debian/debian-autoloads.el>.  That file must then be listed in
debian/I<package>.elpa.

=over 4

=item 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 C<debian-autoloads.el>.

    ;;;###autoload
    (autoload 'hello "goodbye.el" "wave in a friendly manner" t)

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

=head2 A word on info pages in dh_elpa packages

While info pages can be installed to the main INFOPATH in
/usr/share/info using B<dh_installinfo>, this is not recommended.  If
the addon is also bundled with Emacs this method will, at times,
conflict with the file path of a page provided by GNU Emacs.
Conflicts are primarily with the B<emacs-common-non-dfsg> package.
More importantly, installing files outside of the B<dh-elpa>-managed
directory /usr/share/emacs/site-lisp/elpa-src/package-version violates
the ELPA package specification.  This specification requires that the
contents of an ELPA package are contained within a single directory,
and that this directory is named package-version; subdirectories
within package-version are permitted I<[1]>.

Thus, the following method is recommended: Add the path of
C<package.info>, relative to source-package-dir to
debian/[S<I<package.>>]elpa.  Emacs' info viewer is able to find info
pages installed in this way because C<package.el> updates
C<Info-directory-list> to include each addon I<[2]>.  At present the
only downside is that these info pages will be inaccessible using the
standalone B<info> viewer, eg: bugs such as I<#725408> "org-mode 8
info does not show up in info index".

This issue can be fixed upstream in the standalone B<info> viewer if
the ability to parse installed ELPA packages is added to B<info>.
Alternatively, this issue can be resolved by customising C<INFOPATH>
I<[2]>.  eg: B<dh-elpa> could hypothetically be extended using a
method similar to C</etc/profile.d/bash_completion.sh> for each
elpa-package that installs an info page.  GNU Emacs info-mode and the
standalone B<info> viewer would then use C<INFOPATH> to resolve the
correct location of an info page.

= item References:

[1] For more information see section "Multi-file Packages" in the GNU
Emacs Lisp Reference Manual, available online or from the non-free
package emacs-common-non-dfsg C<qinfo "(elisp) Multi-file Packages">.

[2] For more information see section "Other Info Directories" in the
GNU Texinfo Manual, available online or from the non-free package
texinfo-doc-nonfree C<info "(texinfo) Other Info Directories">.

=back