From 70c2253d1967ab4ffca9d0b241b111515e072118 Mon Sep 17 00:00:00 2001
From: Andres Freund <andres@anarazel.de>
Date: Fri, 3 Nov 2023 14:06:25 -0700
Subject: [PATCH v3 4/5] meson: Document build targets, add 'help' target

Author:
Reviewed-by:
Discussion: https://postgr.es/m/20231108232121.ww542mt6lfo6f26f@awork3.anarazel.de
Backpatch:
---
 meson.build                            |  7 +++
 doc/src/sgml/Makefile                  |  5 +-
 doc/src/sgml/docguide.sgml             | 13 +++---
 doc/src/sgml/filelist.sgml             |  1 +
 doc/src/sgml/generate-targets-meson.pl | 63 ++++++++++++++++++++++++++
 doc/src/sgml/installation.sgml         | 15 ++++++
 doc/src/sgml/meson.build               |  9 ++++
 doc/src/sgml/targets-meson.txt         | 43 ++++++++++++++++++
 8 files changed, 148 insertions(+), 8 deletions(-)
 create mode 100644 doc/src/sgml/generate-targets-meson.pl
 create mode 100644 doc/src/sgml/targets-meson.txt

diff --git a/meson.build b/meson.build
index 588788aad4d..ee58ee7a065 100644
--- a/meson.build
+++ b/meson.build
@@ -3335,6 +3335,13 @@ alias_target('testprep', testprep_targets)
 alias_target('world', all_built, docs)
 alias_target('install-world', install_quiet, installdocs)
 
+run_target('help',
+  command: [
+    perl, '-ne', 'next if /^#/; print',
+    files('doc/src/sgml/targets-meson.txt'),
+  ]
+)
+
 
 
 ###############################################################
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 53100828a64..2ef818900fd 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -55,7 +55,7 @@ override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)'
 
 GENERATED_SGML = version.sgml \
 	features-supported.sgml features-unsupported.sgml errcodes-table.sgml \
-	keywords-table.sgml wait_event_types.sgml
+	keywords-table.sgml targets-meson.sgml wait_event_types.sgml
 
 ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
 
@@ -110,6 +110,9 @@ keywords-table.sgml: $(top_srcdir)/src/include/parser/kwlist.h $(wildcard $(srcd
 wait_event_types.sgml: $(top_srcdir)/src/backend/utils/activity/wait_event_names.txt $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl
 	$(PERL) $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl --docs $<
 
+targets-meson.sgml: targets-meson.txt $(srcdir)/generate-targets-meson.pl
+	$(PERL) $(srcdir)/generate-targets-meson.pl $^ > $@
+
 ##
 ## Generation of some text files.
 ##
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index b319621fdb8..c129215dd3c 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -434,9 +434,9 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
   <title>Building the Documentation with Meson</title>
 
    <para>
-    Two options are provided for building the documentation using Meson.
-    Change to the <filename>build</filename> directory before running
-    one of these commands, or add <option>-C build</option> to the command.
+    To build the documentation using Meson, change to the
+    <filename>build</filename> directory before running one of these commands,
+    or add <option>-C build</option> to the command.
    </para>
 
    <para>
@@ -444,10 +444,9 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
 <screen>
 <prompt>build$ </prompt><userinput>ninja html</userinput>
 </screen>
-    To build all forms of the documentation:
-<screen>
-<prompt>build$ </prompt><userinput>ninja alldocs</userinput>
-</screen>
+    For a list of other documentation targets see
+    <xref linkend="targets-meson-documentation"/>.
+
     The output appears in the
     subdirectory <filename>build/doc/src/sgml</filename>.
    </para>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 4c63a7e7689..bd42b3ef16b 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -38,6 +38,7 @@
 <!ENTITY high-availability      SYSTEM "high-availability.sgml">
 <!ENTITY installbin    SYSTEM "install-binaries.sgml">
 <!ENTITY installation  SYSTEM "installation.sgml">
+<!ENTITY targets-meson  SYSTEM "targets-meson.sgml">
 <!ENTITY installw      SYSTEM "install-windows.sgml">
 <!ENTITY maintenance   SYSTEM "maintenance.sgml">
 <!ENTITY manage-ag     SYSTEM "manage-ag.sgml">
diff --git a/doc/src/sgml/generate-targets-meson.pl b/doc/src/sgml/generate-targets-meson.pl
new file mode 100644
index 00000000000..56a94d6ead9
--- /dev/null
+++ b/doc/src/sgml/generate-targets-meson.pl
@@ -0,0 +1,63 @@
+#!/usr/bin/perl
+#
+# Generate the targets-meson.sgml file from targets-meson.txt
+# Copyright (c) 2000-2023, PostgreSQL Global Development Group
+
+use strict;
+use warnings;
+
+my $targets_meson_file = $ARGV[0];
+open my $targets_meson, '<', $targets_meson_file or die;
+
+print
+  "<!-- autogenerated from doc/src/sgml/targets-meson.txt, do not edit -->\n";
+
+# Find the start of each group of targets
+while (<$targets_meson>)
+{
+	next if /^#/;
+
+	if (/^(.*) Targets:$/)
+	{
+		my $targets = $1;
+		my $targets_id = lc $targets;
+
+		print qq(
+<sect3 id="targets-meson-$targets_id">
+ <title>$targets Targets</title>
+
+ <variablelist>
+);
+
+		# Each target in the group
+		while (<$targets_meson>)
+		{
+			next if /^#/;
+			last if !/^\s+([^ ]+)\s+(.+)/;
+
+			my $target = $1;
+			my $desc = $2;
+			my $target_id = $1;
+
+			$target_id =~ s/\//-/g;
+
+			print qq(
+  <varlistentry id="meson-target-${target_id}">
+    <term><option>${target}</option></term>
+    <listitem>
+     <para>
+      ${desc}
+     </para>
+    </listitem>
+  </varlistentry>
+);
+		}
+
+		print qq(
+ </variablelist>
+</sect3>
+);
+	}
+}
+
+close $targets_meson;
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 8e926a3a8cb..b23b35cd8e7 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -3200,6 +3200,21 @@ ninja install
     </variablelist>
    </sect3>
   </sect2>
+
+  <sect2 id="targets-meson">
+   <title><literal>meson</literal> Build Targets</title>
+
+   <para>
+    Individual build targets can be built using <command>ninja</command> <replaceable>target</replaceable>.
+
+    When no target is specified, everything except documentation is
+    built. Individual build products can be built using the path/filename as
+    <replaceable>target</replaceable>.
+   </para>
+
+   &targets-meson;
+  </sect2>
+
  </sect1>
 
  <sect1 id="install-post">
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index dfdb1d0daa7..e1a85dc607b 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -71,6 +71,15 @@ doc_generated += custom_target('keywords-table.sgml',
   capture: true,
 )
 
+doc_generated += custom_target('targets-meson.sgml',
+  input: files('targets-meson.txt'),
+  output: 'targets-meson.sgml',
+  command: [perl, files('generate-targets-meson.pl'), '@INPUT@'],
+  build_by_default: false,
+  install: false,
+  capture: true,
+)
+
 # For everything else we need at least xmllint
 if not xmllint_bin.found()
   subdir_done()
diff --git a/doc/src/sgml/targets-meson.txt b/doc/src/sgml/targets-meson.txt
new file mode 100644
index 00000000000..2495790429e
--- /dev/null
+++ b/doc/src/sgml/targets-meson.txt
@@ -0,0 +1,43 @@
+# Copyright (c) 2023, PostgreSQL Global Development Group
+#
+# Description of important meson targets, used for the 'help' target and
+# installation.sgml (via generate-targets-meson.pl). Right now the parsers are
+# extremely simple. Both parsers ignore comments. The help target prints
+# everything else. For xml everything without a leading newline is a group,
+# remaining lines are target separated by whitespace from their description
+#
+Code Targets:
+  all                          Build everything other than documentation
+  backend                      Build backend and related modules
+  bin                          Build frontend binaries
+  contrib                      Build contrib modules
+  pl                           Build procedual languages
+
+Developer Targets:
+  reformat-dat-files           Rewrite catalog data files into standard format
+  expand-dat-files             Expand all data files to include defaults
+  update-unicode               Update unicode data to new version
+
+Documentation Targets:
+  html                         Build documentation in multi-page HTML format
+  man                          Build documentation in man page format
+  docs                         Build documentation in multi-page HTML and man page format
+  doc/src/sgml/postgres-A4.pdf Build documentation in PDF format, with A4 pages
+  doc/src/sgml/postgres-US.pdf Build documentation in PDF format, with US letter pages
+  doc/src/sgml/postgres.html   Build documentation in single-page HTML format
+  alldocs                      Build documentation in all supported formats
+
+Installation Targets:
+  install                      Install postgres, excluding documentation
+  install-docs                 Install documentation in multi-page HTML and man page formats
+  install-html                 Install documentation in multi-page HTML format
+  install-man                  Install documentation in man page format
+  install-quiet                Like "install", but installed files are not displayed
+  install-world                Install postgres, including multi-page HTML and man page documentation
+  uninstall                    Remove installed files
+
+Other Targets:
+  clean                        Remove all build products
+  test                         Run all enabled tests (including contrib)
+  world                        Build everything, including documentation
+  help                         List important targets
-- 
2.38.0

