Fix the 'realclean' make target

[jkeenan]

I am experiencing another problem in synching podlators into Perl 5 blead. Let's start in a checkout of the main branch in the podlators repository.

$ gitst
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean
$ git describe
release/v6.0.1

Inside Makefile.PL, we observe:

108     # Clean some additional files.
109     clean     => { FILES => File::Spec->catdir('t', 'tmp') },
110     realclean => { FILES => scalar(scripts('pod2text', 'pod2man')) },

Let's create and inspect a Makefile:

$ perl Makefile.PL
Checking if your kit is complete...
Looks good
Generating a Unix-style Makefile
Writing Makefile for Pod
Writing MYMETA.yml and MYMETA.json

$ vi Makefile
...
  28 #     VERSION => q[v6.0.1]
  29 #     clean => { FILES=>q[t/tmp] }
  30 #     realclean => { FILES=>q[2] }
  31 #     test => { TESTS=>q[t/*/*.t] }

That realclean target at line 30 looks weird. Shouldn't we have been expecting an array (or reference to an array) of files?

Let's see what files exist before we run make:

$ find . -type f -name '*pod2*'
./scripts/pod2text.PL
./scripts/pod2man.PL

Now let's call make:

$ make
...
"/home/jkeenan/perl5/perlbrew/perls/perl-5.40.0/bin/perl" "-Iblib/arch" "-Iblib/lib" scripts/pod2man.PL scripts/pod2man 
Extracting pod2man (with variable substitutions)
"/home/jkeenan/perl5/perlbrew/perls/perl-5.40.0/bin/perl" "-Iblib/arch" "-Iblib/lib" scripts/pod2text.PL scripts/pod2text 
Extracting pod2text (with variable substitutions)
cp scripts/pod2man blib/script/pod2man
"/home/jkeenan/perl5/perlbrew/perls/perl-5.40.0/bin/perl" -MExtUtils::MY -e 'MY->fixin(shift)' -- blib/script/pod2man
cp scripts/pod2text blib/script/pod2text
"/home/jkeenan/perl5/perlbrew/perls/perl-5.40.0/bin/perl" -MExtUtils::MY -e 'MY->fixin(shift)' -- blib/script/pod2text
...

Let's see what files exist now:

$ find . -type f -name '*pod2*'
./scripts/pod2text.PL
./scripts/pod2man.PL
./scripts/pod2man
./scripts/pod2text
./blib/script/pod2man
./blib/script/pod2text
./blib/man1/pod2man.1
./blib/man1/pod2text.1

Note that we now have pod2man and pod2text in 2 locations. The only locations we need, however, are those in blib/script/ as that's the directory (INST_SCRIPT) from which they will be installed. We're not going to be doing anything more with scripts/pod2man or scripts/pod2text -- but we have to make sure they get cleaned up!

Let's call make clean:

$ make clean
...
$ find . -type f -name '*pod2*'
./scripts/pod2text.PL
./scripts/pod2man.PL
./scripts/pod2man
./scripts/pod2text

So make clean does not delete those two files. Let's try make realclean:

$ make realclean
make: *** No rule to make target 'realclean'.  Stop.

Bummer! We no longer have a Makefile. (Why not? Should we? Subject for a different ticket.) Let's get back to where we were.

$ git clean -dfx
Removing Makefile.old
Removing scripts/pod2man
Removing scripts/pod2text

$ perl Makefile.PL && make && make realclean
...
$ find . -type f -name '*pod2*'
./scripts/pod2text.PL
./scripts/pod2man.PL
./scripts/pod2man
./scripts/pod2text

So neither make clean nor make realclean removes the superfluous copies of scripts/pod2man and scripts/pod2text.

What If We Change Makefile.PL Line 30?

A diff of the change suggested in this pull request:

$ git diff -w main..realclean-20240713
diff --git a/Makefile.PL b/Makefile.PL
index f1e40f4..6ba71ce 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -107,7 +107,7 @@ my %metadata = (
 
     # Clean some additional files.
     clean     => { FILES => File::Spec->catdir('t', 'tmp') },
-    realclean => { FILES => scalar(scripts('pod2text', 'pod2man')) },
+    realclean => { FILES => [ scripts('pod2text', 'pod2man') ] },
 
     # Dependencies on other modules.
     PREREQ_PM => { 'Pod::Simple' => 3.26 },

Let's try it, then re-inspect Makefile.

$ perl Makefile.PL
...
$ vi Makefile
...
  28 #     VERSION => q[v6.0.1]
  29 #     clean => { FILES=>q[t/tmp] }
  30 #     realclean => { FILES=>[q[scripts/pod2text], q[scripts/pod2man]] }
  31 #     test => { TESTS=>q[t/*/*.t] }

That feels better. Let's try make and then see what files we've got.

$ make
...
$ find . -type f -name '*pod2*'
./scripts/pod2text.PL
./scripts/pod2man.PL
./scripts/pod2man
./scripts/pod2text
./blib/script/pod2man
./blib/script/pod2text
./blib/man1/pod2man.1
./blib/man1/pod2text.1

8 files, same as above. Since we only changed realclean, we'll skip clean.

$ make realclean
...
$ find . -type f -name '*pod2*'
./scripts/pod2text.PL
./scripts/pod2man.PL

We've deleted everything created during the build process and are back to just the two "executable-generator' files in the source code.

Now, I suspect, but I cannot (yet) prove that this problem in Makefile.PL is implicated in a Continuous Integration test failure I'm having when I try to sync podlators-6.0.1 into Perl 5 blead. See: https://github.com/Perl/perl5/actions/runs/9921736345/job/27413104765?pr=22402#step:11:7234. In this CI rig -- in which I am not an expert -- we have a target called distclean which is not removing two files, and then we have a target called manicheck that is announcing:

Run perl Porting/manicheck --exitstatus
  perl Porting/manicheck --exitstatus
  shell: /usr/bin/bash -e {0}
  env:
    PERL_SKIP_TTY_TEST: 1
    CONTINUOUS_INTEGRATION: 1
  
cpan/podlators/scripts/pod2text		not in MANIFEST
cpan/podlators/scripts/pod2man		not in MANIFEST
Error: Process completed with exit code 2.

... that there are two files not found in the core's MANIFEST which are still found in the build tree. Of course, those two files should not be in MANIFEST, because they are generated during make by scripts/pod2text.PL and scripts/pod2man.PL. But they should have been deleted during the distclean target -- and my hunch (as yet unproven) is that they are not deleted because of the current problem in podlator's Makefile.PL. (I do not yet know why the CI failure is only showing up on this pull request.)

[rra]

Thanks, fixed in 6395999. Sounds like I should make a v6.0.2 release with that fix so that you can clear the Perl CI failure. Sorry about that; clearly 6f67869 was not well-thought-through and introduced multiple problems.

[jkeenan]

Based on an experiment I did in a branch in Perl core (https://github.com/Perl/perl5/actions/runs/9927740169), I think this change will PASS all of the core's CI tests. So I look forward to a v6.0.2 release. Thanks.

[rra]

Thank you for testing! v6.0.2 has been released.