Re: [PATCH] Documentation/build-docdep.perl: generate sorted output

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

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@gmail.com>
> ---
>  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";
	     }
	 }