Add the possibility to generate documentation at build time

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6236)

Configurations/common.tmpl

@@ -151,10 +151,18 @@
                              generator_incs => $unified_info{includes}->{$script},
                              generator_deps => $unified_info{depends}->{$script},
                              deps => $unified_info{depends}->{$src},
-                             incs => [ @{$unified_info{includes}->{$obj}},
-                                       @{$unified_info{includes}->{$bin}} ],
-                             defs => [ @{$unified_info{defines}->{$obj}},
-                                       @{$unified_info{defines}->{$bin}} ],
+                             incs => [ defined $obj
+                                           ? @{$unified_info{includes}->{$obj}}
+                                           : (),
+                                       defined $bin
+                                           ? @{$unified_info{includes}->{$bin}}
+                                           : () ],
+                             defs => [ defined $obj
+                                           ? @{$unified_info{defines}->{$obj}}
+                                           : (),
+                                       defined $bin
+                                           ? @{$unified_info{defines}->{$bin}}
+                                           : () ],
                              %opts);
          foreach (@{$unified_info{depends}->{$src}}) {
              dogenerate($_, $obj, $bin, %opts);
@@ -436,6 +444,22 @@
      $cache{$dir} = 1;
  }
 
+ # dodocs is responsible for building documentation from .pods.
+ # It will call generatesrc.
+ sub dodocs {
+     my $type = shift;
+     my $section = shift;
+     foreach my $doc (@{$unified_info{"${type}docs"}->{$section}}) {
+         next if $cache{$doc};
+         $OUT .= generatesrc(src => $doc,
+                             generator => $unified_info{generate}->{$doc});
+         foreach ((@{$unified_info{depends}->{$doc}})) {
+             dogenerate($_, undef, undef, %opts);
+         }
+         $cache{$doc} = 1;
+     }
+ }
+
  # Start with populating the cache with all the overrides
  %cache = map { $_ => 1 } @{$unified_info{overrides}};
 
@@ -448,6 +472,7 @@
  foreach (@{$unified_info{modules}})   { domodule($_); }
  foreach (@{$unified_info{programs}})  { dobin($_);    }
  foreach (@{$unified_info{scripts}})   { doscript($_); }
-
+ foreach (sort keys %{$unified_info{htmldocs}}) { dodocs('html', $_); }
+ foreach (sort keys %{$unified_info{mandocs}})  { dodocs('man', $_); }
  foreach (sort keys %{$unified_info{dirinfo}})  { dodir($_); }
 -}

Configure

@@ -1777,6 +1777,8 @@ if ($builder eq "unified") {
         my %defines = ();
         my %depends = ();
         my %generate = ();
+        my %htmldocs = ();
+        my %mandocs = ();
 
         # Support for $variablename in build.info files.
         # Embedded perl code is the ultimate master, still.  If its output
@@ -1837,6 +1839,10 @@ if ($builder eq "unified") {
         # don't use it if the build tree is different.
         my $src_configdata = cleanfile($srcdir, "configdata.pm", $blddir);
 
+
+        if ($buildinfo_debug) {
+            print STDERR "DEBUG: Reading ",catfile($sourced, $f),"\n";
+        }
         push @{$config{build_infos}}, catfile(abs2rel($sourced, $blddir), $f);
         my $template =
             Text::Template->new(TYPE => 'FILE',
@@ -1948,7 +1954,14 @@ if ($builder eq "unified") {
                                          @s);
                 }
             },
-
+            qr/^\s* HTMLDOCS ${index_re} = ${value_re} $/x
+            => sub { push @{$htmldocs{$expand_variables->($+{INDEX})}},
+                         tokenize($expand_variables->($+{VALUE}))
+                         if !@skip || $skip[$#skip] > 0 },
+            qr/^\s* MANDOCS ${index_re} = ${value_re} $/x
+            => sub { push @{$mandocs{$expand_variables->($+{INDEX})}},
+                         tokenize($expand_variables->($+{VALUE}))
+                         if !@skip || $skip[$#skip] > 0 },
             qr/^\s* ORDINALS ${index_re} = ${value_re} $/x
             => sub { push @{$ordinals{$expand_variables->($+{INDEX})}},
                          tokenize($expand_variables->($+{VALUE}))
@@ -2206,6 +2219,20 @@ EOF
                 }
             }
         }
+
+        foreach my $section (keys %htmldocs) {
+            foreach (@{$htmldocs{$section}}) {
+                my $htmldocs = cleanfile($buildd, $_, $blddir);
+                $unified_info{htmldocs}->{$section}->{$htmldocs} = 1;
+            }
+        }
+
+        foreach my $section (keys %mandocs) {
+            foreach (@{$mandocs{$section}}) {
+                my $mandocs = cleanfile($buildd, $_, $blddir);
+                $unified_info{mandocs}->{$section}->{$mandocs} = 1;
+            }
+        }
     }
 
     my $ordinals_text = join(', ', sort keys %ordinals);
@@ -2366,7 +2393,8 @@ EOF
         $unified_info{$_} = [ sort keys %{$unified_info{$_}} ];
     }
     # Two level structures
-    foreach my $l1 (("sources", "shared_sources", "ldadd", "depends")) {
+    foreach my $l1 (("sources", "shared_sources", "ldadd", "depends",
+                     "htmldocs", "mandocs")) {
         foreach my $l2 (sort keys %{$unified_info{$l1}}) {
             my @items =
                 sort
@@ -2412,7 +2440,11 @@ EOF
     my %loopinfo = ( "lib" => [ @{$unified_info{libraries}} ],
                      "dso" => [ @{$unified_info{modules}} ],
                      "bin" => [ @{$unified_info{programs}} ],
-                     "script" => [ @{$unified_info{scripts}} ] );
+                     "script" => [ @{$unified_info{scripts}} ],
+                     "docs" => [ (map { @{$unified_info{htmldocs}->{$_} // []} }
+                                  keys %{$unified_info{htmldocs} // {}}),
+                                 (map { @{$unified_info{mandocs}->{$_} // []} }
+                                  keys %{$unified_info{mandocs} // {}}) ] );
     foreach my $type (keys %loopinfo) {
         foreach my $product (@{$loopinfo{$type}}) {
             my %dirs = ();