This file is indexed.

/usr/bin/dh_elpa_test is in dh-elpa 1.6.

This file is owned by root:root, with mode 0o755.

The actual contents of the file can be viewed below.

  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
#!/usr/bin/perl

=head1 NAME

dh_elpa_test - run ELPA package testsuites

=cut

use strict;
use warnings;
no warnings "experimental::smartmatch";

=head1 SYNOPSIS

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

=head1 DESCRIPTION

B<dh_elpa_test> is a debhelper program that is responsible for running
the testsuites of ELPA packages, when those test suites use ERT or
buttercup(1).  dh_auto_test(1) is rarely suitable.

Testing with buttercup(1) will be activated if the package
build-depends on elpa-buttercup.  Testing with ERT will be activated
if ERT test files can be found.  Neither kind of test will be
activated unless the debhelper compat level is 10 or higher.

B<dh_elpa_test> overrides dh_auto_test(1).  If you need to switch back
to use dh_auto_test(1), use the B<disable> configuration key, below.

=head1 FILES

=over 4

=item debian/elpa-test

Configuration for running the package's test suite.  Each line is of
the form I<key> = I<value>, with I<key> drawn from the list of
configuration options below.

Note that you should not surround values with double quotation marks.
This is convenient for including lisp.  Configuration values cannot
cover more than one line.  Lines preceded with a # are ignored as
comments.

This configuration file is optional; in many cases, B<dh_elpa_test>
can figure out how to run the test suite itself.

=back

=head1 CONFIGURATION KEYS

=over 4

=item B<disable>

If this key is set to any value, dh_elpa(1) will not invoke
B<dh_elpa_test>.

=item B<buttercup_load_path>

A comma-separated list of directories to add to the load-path when
buttercup(1) invokes Emacs.  Will be passed to buttercup(1) with its
B<-L> command line argument.

=item B<buttercup_patterns>

A comma-separated list of Emacs regular expressions jointly matching
all and only the files containing Buttercup tests that you wish to
run.  If this key is not defined, all tests that can be found
will be run.  Will be passed to buttercup(1) with its B<-p> command
line argument.

=item B<ert_exclude>

A comma-separated list of file globs matching files containing ERT
tests that should not be run.

The '*' character in globs in this configuration key does NOT match
'/' directory separators.

=item B<ert_helper>

The name of a *.el file containing Emacs Lisp code that will run the
ERT test suite.  When this key is not defined, B<dh_elpa_test>
calls the function B<(ert-run-tests-batch-and-exit)>.

Note that this is not the way to load test helpers that do needed work
but don't actually run the tests.  For that, you can use something like

=over 4

    ert_eval = (load-file "test-helper.el")

=back

=item B<ert_eval>

Emacs Lisp code to be run prior to running ERT tests by the Emacs
instance spawned by B<dh_elpa_test> to run those tests.

=item B<ert_load_path>

A comma-separated list of directories to add to the load-path when
B<dh_elpa_test> invokes Emacs to run ERT tests.

=item B<autopkgtest_keep>

A comma-separated list of file globs matching files that should not be
moved out of the source tree before running DEP8 tests (see the
B<--autopkgtest> option below).

The '*' character in globs in this configuration key matches '/'
directory separators.

=back

=head1 OPTIONS

=over 4

=item B<--autopkgtest>

Operate in autopkgtest mode.  B<dh_elpa_test> will rename non-test *.el
files so that Emacs will not load them.  This ensures that the test
test the installed binary package rather than the unpacked source
package.

To exclude files from this removal, specify them in the
B<autopkgtest_keep> configuration option (see above).

=back

=head1 ENVIRONMENT VARIABLES

Older versions of B<dh_elpa_test> were configured using environment
variables corresponding to some of the above configuration keys.  For
example, the B<ert_eval> configuration key replaced environment
variable B<DH_ELPA_TEST_ERT_EVAL>.  Their use is now deprecated.  If
the debian/elpa-test file exists, they will be ignored.

=cut

use File::Find::Rule;
use Array::Utils qw{ array_minus };
use Text::Glob qw{ glob_to_regex };
use Config::Tiny;

use Debian::Debhelper::Dh_Lib;
use Debian::Control;

# ---- Subroutines

# like Find::File::Rule::name, but matches the whole path of the file
# (relative to cwd when search was started) against the glob, rather
# than just the basename (also, unlike Find::File::Rule::name, accepts
# a single glob and no regexps since that's all we need here)
sub long_name {
    my $glob = shift;

    return sub {
        ( undef, undef, my $fullname ) = @_;

        if ( $fullname =~ glob_to_regex($glob) ) {
            return 1;
        } else {
            return 0;
        }
    }
}

# ---- Script setup

# check command line opts for autopkgtest mode
my $autopkgtest = ( "--autopkgtest" ~~ @ARGV );

# This checks whether the debhelper compat is 10 or above.  With
# debhelper compat below 9, dh_elpa_test will get run more in more
# than one sequence, including inside fakeroot, which can cause tests
# to fail
if ( get_buildoption("nocheck") || compat(9) ) {
	exit 0;
}

# note that we don't need package.elpa-test since we are testing all
# lisp we can find in the *source* package
my $options = Config::Tiny->new;
if ( -f "debian/elpa-test") {
    verbose_print("I: Ignoring DH_ELPA_TEST_* envvars since debian/elpa-test exists");
    $options = Config::Tiny->read( "debian/elpa-test" );
} else {
    my @envvars = ("DH_ELPA_TEST_DISABLE",
                   "DH_ELPA_TEST_BUTTERCUP_LOAD_PATH",
                   "DH_ELPA_TEST_BUTTERCUP_PATTERNS",
                   "DH_ELPA_TEST_ERT_EXCLUDE",
                   "DH_ELPA_TEST_ERT_HELPER",
                   "DH_ELPA_TEST_ERT_EVAL",
                   "DH_ELPA_TEST_ERT_LOAD_PATH"
                  );
    foreach my $envvar ( @envvars ) {
        if (defined $ENV{$envvar}) {
            my $short = lc(substr($envvar, 13));
            print "W: environment variable $envvar is deprecated; see dh_elpa_test(1)\n";
            $options->{_}->{$short} = $ENV{$envvar};
        }
    }
}

my @non_test_files;
if ($autopkgtest) {
    # Since we were not invoked by the dh sequencer, we need to check
    # here whether tests have been disabled.  Note that we can't
    # replace the test in elpa.pm with this one because we can't
    # (cleanly) disable dh_auto_test from within dh_elpa_test
    if ( defined $options->{_}->{ "disable" } ) {
        exit 0;
    }

    my $rule = File::Find::Rule->new;
    $rule
      ->or(File::Find::Rule
           ->name('.pc', 'debian', '.git')
           ->directory->prune->discard,
           File::Find::Rule->new);
    $rule
      ->file()
      ->name( '*.el' )
      ->none(File::Find::Rule->grep( "ert-deftest" ), # ERT
             File::Find::Rule->grep( "\\(describe \"" ) # Buttercup
            );

    if ( defined $options->{_}->{'autopkgtest_keep'} ) {
        foreach my $glob (split(',', $options->{_}->{'autopkgtest_keep'} )) {
            # We want the user to be able to say
            #     autopkgtest_keep = test/resources/*
            # and have that affect all subdirs of resources
            $Text::Glob::strict_wildcard_slash = 0;
            # TODO should we do this for ert_exclude too?
            $rule->not_exec( long_name($glob) );
        }
    }

    @non_test_files = $rule->in('.');

    foreach my $old ( @non_test_files ) {
        my $new = $old =~ s|\.el$|.disabled|r;
        rename $old, $new or die "Failed to rename: $!\n";
    }
}

# these are from dh_elpa
# TODO have dh_elpa export them so we can import them, instead of copy/paste
my $dhelpadir="/usr/share/emacs/site-lisp/elpa";
my $elpadir="/usr/share/emacs/site-lisp/elpa-src";

my $control = Debian::Control->new();
$control->read("debian/control");

if ($autopkgtest) {
    # save stderr handle for restoration
    {
        no warnings 'once';
        open(OLDERR, ">&", \*STDERR);
    }

    # redirect stderr to stdout while we run our tests

    # emacs --batch and ERT itself both produce a lot of output on
    # stderr even when there has been no error, and adt-run interprets
    # this as a test failure

    # Recent autopkgtest has a 'allow-stderr' restriction prevents
    # that interpretation.  However, relying on that would require
    # 'allow-stderr' to be specified in the d/tests/control file for
    # every package using dh_elpa_test.  It's cleaner just to redirect
    # here.

    open(STDERR, ">&STDOUT");
    # unbuffer them to ensure lines appear in the right order
    select STDERR; $| = 1;
    select STDOUT; $| = 1;
}

# ---- Buttercup

if ($control->source->Build_Depends->has( "elpa-buttercup" )) {
    my @args = qw{ buttercup -L . };
    if (defined $options->{_}->{'buttercup_load_path'}) {
        foreach my $dir (split(',', $options->{_}->{'buttercup_load_path'})) {
            push @args, ('-L', "$dir");
        }
    }
    if (defined $options->{_}->{'buttercup_patterns'}) {
        foreach my $pattern (split(',', $options->{_}->{'buttercup_patterns'})) {
            push @args, ('-p', "$pattern");
        }
    }
    print_and_doit(@args);
}

# ---- ERT

my $rule = File::Find::Rule->new;
$rule
  ->or(File::Find::Rule
       ->name('.pc', 'debian')
       ->directory->prune->discard,
       File::Find::Rule->new);
$rule
  ->file()
  ->name( '*.el' )
  ->grep( "ert-deftest" );
if (defined $options->{_}->{'ert_exclude'}) {
    foreach my $glob (split(',', $options->{_}->{'ert_exclude'})) {
        $rule->not_exec( long_name($glob) );
    }
}
my @ert_files = $rule->in('.');

if (@ert_files) {
    my @args = qw{ emacs -batch -Q -l package };
    push @args, ("--eval", "(add-to-list 'package-directory-list \"$dhelpadir\")");
    push @args, ("--eval", "(add-to-list 'package-directory-list \"$elpadir\")");
    push @args, ("-f", "package-initialize");

    # work around the fact that s-el and dash-el are not packaged with
    # dh_elpa so aren't in $dhelpadir
    push @args, ("-L", "/usr/share/emacs/site-lisp/s-el")
      if ($control->source->Build_Depends->has( "s-el" ));
    push @args, ("-L", "/usr/share/emacs/site-lisp/dash-el")
      if ($control->source->Build_Depends->has( "dash-el" ));

    # add the user's load-path entries
    if (defined $options->{_}->{'ert_load_path'}) {
        foreach my $dir (split(',', $options->{_}->{'ert_load_path'})) {
            push @args, ('-L', "$dir");
        }
    }

    # make some guesses about where stuff that needs to be in
    # load-path will be
    push @args, ("-L", ".");
    push @args, ("-L", "test") if ( -d "test" );
    push @args, ("-L", "tests") if ( -d "tests" );
    # TODO maybe we should just add all dirs containing files in @ert_files?

    # now finish adding the user's stuff
    push @args, ("--eval", $options->{_}->{'ert_eval'})
      if (defined $options->{_}->{'ert_eval'});
    foreach my $ert_file (@ert_files) {
        push @args, ("-l", "$ert_file");
    }
    if (defined $options->{_}->{'ert_helper'}) {
        push @args, ("-l", $options->{_}->{'ert_helper'});
    } else {
        push @args, ("--eval", "(ert-run-tests-batch-and-exit)");
    }

    print_and_doit(@args);
}

# ---- Cleanup

END {
    if ($autopkgtest) {
        # restore stderr now we've finished running tests
        open(STDERR, ">&OLDERR");

        # Restore files that we renamed so that we comply with DEP8
        # rw-build-tree
        foreach my $new ( @non_test_files ) {
            my $old = $new =~ s|\.el$|.disabled|r;
            rename $old, $new or die "Failed to rename: $!\n";
        }
    }
}