On Fri, Oct 21 2022, SZEDER Gábor wrote:
> To make sure that our manpages are rebuilt when any of the included
> source files change and only the affected manpages are rebuilt,
> 'build-docdep.perl' scans our documentation source files for include
> directives, and outputs 'make' dependencies to be included by
> 'Documentation/Makefile'. This script relies on Perl's hash data
> structures, and generates its output while iterating over them, and
> since hashes in Perl are very much unordered, the output varies
> greatly from run to run, both the order of targets and the order of
> dependencies of each target.
>
> This lack of ordering doesn't matter for 'make', because it cares
> neither about the order of targets in a Makefile nor about the order
> of a target's dependencies. However, it does matter to developers
> looking into build issues potentially involving these generated
> dependencies, as it's rather hard to tell whether there are any
> relevant (i.e. not order-only) changes among the dependencies compared
> to the previous run.
>
> So let's make 'build-docdep.perl's output stable and ordered by
> sorting the keys of the hashes before iterating over them.
>
> Signed-off-by: SZEDER Gábor <szeder.dev@xxxxxxxxx>
> ---
> Documentation/build-docdep.perl | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl
> index ba4205e030..1b3ac8fdd9 100755
> --- a/Documentation/build-docdep.perl
> +++ b/Documentation/build-docdep.perl
> @@ -38,9 +38,10 @@
> }
> }
>
> -while (my ($text, $included) = each %include) {
> +foreach my $text (sort keys %include) {
> + my $included = $include{$text};
> if (! exists $included{$text} &&
> (my $base = $text) =~ s/\.txt$//) {
> - print "$base.html $base.xml : ", join(" ", keys %$included), "\n";
> + print "$base.html $base.xml : ", join(" ", sort keys %$included), "\n";
> }
> }
This looks good to me, FWIW I ran this ad-hoc test and it's the same,
i.e. we end up with the same order as the initial glob order on the FS:
diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl
index ba4205e0302..6f6e6c62eb8 100755
--- a/Documentation/build-docdep.perl
+++ b/Documentation/build-docdep.perl
@@ -1,9 +1,13 @@
#!/usr/bin/perl
+use strict;
+use warnings;
my %include = ();
my %included = ();
-for my $text (<*.txt>) {
+my @txt = <*.txt>;
+
+for my $text (@txt) {
open I, '<', $text || die "cannot read: $text";
while (<I>) {
if (/^include::/) {
@@ -38,9 +42,11 @@
}
}
-while (my ($text, $included) = each %include) {
+
+for my $text (grep { exists $include{$_} } @txt) {
+ my $included = $include{$text};
if (! exists $included{$text} &&
(my $base = $text) =~ s/\.txt$//) {
- print "$base.html $base.xml : ", join(" ", keys %$included), "\n";
+ print "$base.html $base.xml : ", join(" ", sort keys %$included), "\n";
}
}
