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
index 53100828a6484264f7b78bf7c5005e67016b8c38..2ef818900fd45463c7341931f21751951b3d1ba7 100644 (file)
@@ -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.
##
index b319621fdb867ec5235c5e858af975a89a9dfca6..c129215dd3c64ca8c3ad944f77f014a7b8a27be3 100644 (file)
@@ -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>
index 4c63a7e76895b5291af18d14b9c3116d7cc63878..bd42b3ef16bc002d4ef2ba0a18424d8bb671e3f2 100644 (file)
<!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">
new file mode 100644
(file)
index 0000000..
56a94d6
--- /dev/null
+#!/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;
index 8e926a3a8cbeb7cc415b16e2da3d9dd676aef529..b23b35cd8e7836270815b4a99337a74f06bc6e6f 100644 (file)
</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">
index dfdb1d0daa7df4632ddba6c09c01b471025d0c00..e1a85dc607b18ad1e58584997f67fdbeaffda8c3 100644 (file)
@@ -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()
new file mode 100644
(file)
index 0000000..
2cd192e
--- /dev/null
+# 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
index 588788aad4da2889e61aff6ec33895b85502bbc7..ee58ee7a065bf17fb7117e4fc2fe0cc5081ed851 100644 (file)
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'),
+ ]
+)
+
###############################################################