summaryrefslogtreecommitdiff
path: root/dh_elpa.in
blob: 33766126814db7bd126498f3de08634232983f2d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
#!/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.  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, B<dh_elpa> will install matching
file(s) into the top level elpa package directory.

For lines which include a destination subdirectory, B<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.

=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;
  my @dests;
  my $is_single_file;

  # Call isnative because it sets $dh{VERSION}
  # as a side effect.
  isnative($package);
  if ($file) {
    # Don't glob yet, we need to count the words first.
    @files=filedoublearray($file);

    # On lines with more than one word, the last word is the
    # destination (sub)directory
    @dests=map { (@$_ > 1) ?  (pop @$_) : undef; } @files;

    # Globexpand any remaining words, leaving them grouped as one array per line.
    @files=map { map { [ glob_expand(["."], \&glob_expand_error_handler_warn_and_discard, $_) ] } @$_ } @files;

    $is_single_file = (scalar(@files) == 1 && scalar(@{$files[0]}) == 1);

    $is_single_file || grep { $_[0] =~ 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 ($is_single_file) {
      my $pkg_file=$files[0][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";
    for (my $i=0; $i<scalar(@files); $i++) {
      my $targetdir = $stagedir;

      if (defined ($dests[$i])) {
        verbose_print("dest=$dests[$i]");
        $targetdir = $stagedir . "/" . $dests[$i];
      }

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

      foreach my $file (@{$files[$i]}) {
        doit("cp", "-a", $file, "$targetdir");
      }
    }

    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.

=back