meson: Document build targets, add 'help' target

Currently important build targets are somewhat hard to discover. This commit documents important meson build targets in the sgml documentation. But it's awkward to have to lookup build targets in the docs when hacking, so this also adds a 'help' target, printing out the same information. To avoid having to duplicate information in two places, generate both docbook and interactive docs from a single source. Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Discussion: https://postgr.es/m/20231108232121.ww542mt6lfo6f26f@awork3.anarazel.de
postgres · Nov 21, 2023 · 07cb297 · 07cb297
1 parent 6614cfb
commit 07cb297
Show file tree

Hide file tree

Showing 8 changed files with 148 additions and 8 deletions.
diff --git 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
@@ -434,20 +434,19 @@ 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>
     To build just the <acronym>HTML</acronym> version of the documentation:
 <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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git 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'),
+  ]
+)
+
 
 
 ###############################################################