{"thread":{"id":"58667","subject":"[PATCH] Documentation/build-docdep.perl: generate sorted output","startedAt":"2022-10-21T10:30:08Z","lastAt":"2022-10-21T17:57:14Z","messageCount":3,"participants":["SZEDER Gábor","Ævar Arnfjörð Bjarmason","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"465454","messageId":"20221021102950.539148-1-szeder.dev@gmail.com","threadId":"58667","inReplyTo":null,"subject":"[PATCH] Documentation/build-docdep.perl: generate sorted output","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2022-10-21T10:29:50Z","receivedAt":"2022-10-21T10:30:08Z","isPatch":true,"sender":{"key":"szeder.dev@gmail.com","avatar":"https://avatars.githubusercontent.com/u/116324?v=4"},"body":"To make sure that our manpages are rebuilt when any of the included\nsource files change and only the affected manpages are rebuilt,\n'build-docdep.perl' scans our documentation source files for include\ndirectives, and outputs 'make' dependencies to be included by\n'Documentation/Makefile'.  This script relies on Perl's hash data\nstructures, and generates its output while iterating over them, and\nsince hashes in Perl are very much unordered, the output varies\ngreatly from run to run, both the order of targets and the order of\ndependencies of each target.\n\nThis lack of ordering doesn't matter for 'make', because it cares\nneither about the order of targets in a Makefile nor about the order\nof a target's dependencies.  However, it does matter to developers\nlooking into build issues potentially involving these generated\ndependencies, as it's rather hard to tell whether there are any\nrelevant (i.e. not order-only) changes among the dependencies compared\nto the previous run.\n\nSo let's make 'build-docdep.perl's output stable and ordered by\nsorting the keys of the hashes before iterating over them.\n\nSigned-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n---\n Documentation/build-docdep.perl | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl\nindex ba4205e030..1b3ac8fdd9 100755\n--- a/Documentation/build-docdep.perl\n+++ b/Documentation/build-docdep.perl\n@@ -38,9 +38,10 @@\n     }\n }\n \n-while (my ($text, $included) = each %include) {\n+foreach my $text (sort keys %include) {\n+    my $included = $include{$text};\n     if (! exists $included{$text} &&\n \t(my $base = $text) =~ s/\\.txt$//) {\n-\tprint \"$base.html $base.xml : \", join(\" \", keys %$included), \"\\n\";\n+\tprint \"$base.html $base.xml : \", join(\" \", sort keys %$included), \"\\n\";\n     }\n }\n-- \n2.38.1.339.gbbb58f2828\n\n"},{"id":"465486","messageId":"221021.86ilkddsor.gmgdl@evledraar.gmail.com","threadId":"58667","inReplyTo":"20221021102950.539148-1-szeder.dev@gmail.com","subject":"Re: [PATCH] Documentation/build-docdep.perl: generate sorted output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-21T16:52:26Z","receivedAt":"2022-10-21T16:53:59Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Oct 21 2022, SZEDER Gábor wrote:\n\n> To make sure that our manpages are rebuilt when any of the included\n> source files change and only the affected manpages are rebuilt,\n> 'build-docdep.perl' scans our documentation source files for include\n> directives, and outputs 'make' dependencies to be included by\n> 'Documentation/Makefile'.  This script relies on Perl's hash data\n> structures, and generates its output while iterating over them, and\n> since hashes in Perl are very much unordered, the output varies\n> greatly from run to run, both the order of targets and the order of\n> dependencies of each target.\n>\n> This lack of ordering doesn't matter for 'make', because it cares\n> neither about the order of targets in a Makefile nor about the order\n> of a target's dependencies.  However, it does matter to developers\n> looking into build issues potentially involving these generated\n> dependencies, as it's rather hard to tell whether there are any\n> relevant (i.e. not order-only) changes among the dependencies compared\n> to the previous run.\n>\n> So let's make 'build-docdep.perl's output stable and ordered by\n> sorting the keys of the hashes before iterating over them.\n>\n> Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>\n> ---\n>  Documentation/build-docdep.perl | 5 +++--\n>  1 file changed, 3 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl\n> index ba4205e030..1b3ac8fdd9 100755\n> --- a/Documentation/build-docdep.perl\n> +++ b/Documentation/build-docdep.perl\n> @@ -38,9 +38,10 @@\n>      }\n>  }\n>  \n> -while (my ($text, $included) = each %include) {\n> +foreach my $text (sort keys %include) {\n> +    my $included = $include{$text};\n>      if (! exists $included{$text} &&\n>  \t(my $base = $text) =~ s/\\.txt$//) {\n> -\tprint \"$base.html $base.xml : \", join(\" \", keys %$included), \"\\n\";\n> +\tprint \"$base.html $base.xml : \", join(\" \", sort keys %$included), \"\\n\";\n>      }\n>  }\n\nThis looks good to me, FWIW I ran this ad-hoc test and it's the same,\ni.e. we end up with the same order as the initial glob order on the FS:\n\t\n\tdiff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl\n\tindex ba4205e0302..6f6e6c62eb8 100755\n\t--- a/Documentation/build-docdep.perl\n\t+++ b/Documentation/build-docdep.perl\n\t@@ -1,9 +1,13 @@\n\t #!/usr/bin/perl\n\t+use strict;\n\t+use warnings;\n\t \n\t my %include = ();\n\t my %included = ();\n\t \n\t-for my $text (<*.txt>) {\n\t+my @txt = <*.txt>;\n\t+\n\t+for my $text (@txt) {\n\t     open I, '<', $text || die \"cannot read: $text\";\n\t     while (<I>) {\n\t \tif (/^include::/) {\n\t@@ -38,9 +42,11 @@\n\t     }\n\t }\n\t \n\t-while (my ($text, $included) = each %include) {\n\t+\n\t+for my $text (grep { exists $include{$_} } @txt) {\n\t+    my $included = $include{$text};\n\t     if (! exists $included{$text} &&\n\t \t(my $base = $text) =~ s/\\.txt$//) {\n\t-\tprint \"$base.html $base.xml : \", join(\" \", keys %$included), \"\\n\";\n\t+\tprint \"$base.html $base.xml : \", join(\" \", sort keys %$included), \"\\n\";\n\t     }\n\t }\n\t\n"},{"id":"465499","messageId":"xmqqh6zxkqku.fsf@gitster.g","threadId":"58667","inReplyTo":"20221021102950.539148-1-szeder.dev@gmail.com","subject":"Re: [PATCH] Documentation/build-docdep.perl: generate sorted output","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-21T17:57:05Z","receivedAt":"2022-10-21T17:57:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"SZEDER Gábor <szeder.dev@gmail.com> writes:\n\n> So let's make 'build-docdep.perl's output stable and ordered by\n> sorting the keys of the hashes before iterating over them.\n\nMakes sense.  Will queue.\n"}]}