Skip to content

Commit 07cb297

Browse files
anarazelanarazel
committed
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
1 parent 6614cfb commit 07cb297

File tree

8 files changed

+148
-8
lines changed

8 files changed

+148
-8
lines changed

‎doc/src/sgml/Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)'
5555

5656
GENERATED_SGML = version.sgml \
5757
features-supported.sgml features-unsupported.sgml errcodes-table.sgml \
58-
keywords-table.sgml wait_event_types.sgml
58+
keywords-table.sgml targets-meson.sgml wait_event_types.sgml
5959

6060
ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
6161

@@ -110,6 +110,9 @@ keywords-table.sgml: $(top_srcdir)/src/include/parser/kwlist.h $(wildcard $(srcd
110110
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
111111
$(PERL) $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl --docs $<
112112

113+
targets-meson.sgml: targets-meson.txt $(srcdir)/generate-targets-meson.pl
114+
$(PERL) $(srcdir)/generate-targets-meson.pl $^ > $@
115+
113116
##
114117
## Generation of some text files.
115118
##

‎doc/src/sgml/docguide.sgml‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -434,20 +434,19 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
434434
<title>Building the Documentation with Meson</title>
435435

436436
<para>
437-
Two options are provided for building the documentation using Meson.
438-
Change to the <filename>build</filename> directory before running
439-
one of these commands, or add <option>-C build</option> to the command.
437+
To build the documentation using Meson, change to the
438+
<filename>build</filename> directory before running one of these commands,
439+
or add <option>-C build</option> to the command.
440440
</para>
441441

442442
<para>
443443
To build just the <acronym>HTML</acronym> version of the documentation:
444444
<screen>
445445
<prompt>build$ </prompt><userinput>ninja html</userinput>
446446
</screen>
447-
To build all forms of the documentation:
448-
<screen>
449-
<prompt>build$ </prompt><userinput>ninja alldocs</userinput>
450-
</screen>
447+
For a list of other documentation targets see
448+
<xref linkend="targets-meson-documentation"/>.
449+
451450
The output appears in the
452451
subdirectory <filename>build/doc/src/sgml</filename>.
453452
</para>

‎doc/src/sgml/filelist.sgml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
<!ENTITY high-availability SYSTEM "high-availability.sgml">
3939
<!ENTITY installbin SYSTEM "install-binaries.sgml">
4040
<!ENTITY installation SYSTEM "installation.sgml">
41+
<!ENTITY targets-meson SYSTEM "targets-meson.sgml">
4142
<!ENTITY installw SYSTEM "install-windows.sgml">
4243
<!ENTITY maintenance SYSTEM "maintenance.sgml">
4344
<!ENTITY manage-ag SYSTEM "manage-ag.sgml">

‎doc/src/sgml/generate-targets-meson.pl‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
#!/usr/bin/perl
2+
#
3+
# Generate the targets-meson.sgml file from targets-meson.txt
4+
# Copyright (c) 2000-2023, PostgreSQL Global Development Group
5+
6+
use strict;
7+
use warnings;
8+
9+
my $targets_meson_file = $ARGV[0];
10+
open my $targets_meson, '<', $targets_meson_file or die;
11+
12+
print
13+
"<!-- autogenerated from doc/src/sgml/targets-meson.txt, do not edit -->\n";
14+
15+
# Find the start of each group of targets
16+
while (<$targets_meson>)
17+
{
18+
next if /^#/;
19+
20+
if (/^(.*) Targets:$/)
21+
{
22+
my $targets = $1;
23+
my $targets_id = lc $targets;
24+
25+
print qq(
26+
<sect3 id="targets-meson-$targets_id">
27+
<title>$targets Targets</title>
28+
29+
<variablelist>
30+
);
31+
32+
# Each target in the group
33+
while (<$targets_meson>)
34+
{
35+
next if /^#/;
36+
last if !/^\s+([^ ]+)\s+(.+)/;
37+
38+
my $target = $1;
39+
my $desc = $2;
40+
my $target_id = $1;
41+
42+
$target_id =~ s/\//-/g;
43+
44+
print qq(
45+
<varlistentry id="meson-target-${target_id}">
46+
<term><option>${target}</option></term>
47+
<listitem>
48+
<para>
49+
${desc}
50+
</para>
51+
</listitem>
52+
</varlistentry>
53+
);
54+
}
55+
56+
print qq(
57+
</variablelist>
58+
</sect3>
59+
);
60+
}
61+
}
62+
63+
close $targets_meson;

‎doc/src/sgml/installation.sgml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3200,6 +3200,21 @@ ninja install
32003200
</variablelist>
32013201
</sect3>
32023202
</sect2>
3203+
3204+
<sect2 id="targets-meson">
3205+
<title><literal>meson</literal> Build Targets</title>
3206+
3207+
<para>
3208+
Individual build targets can be built using <command>ninja</command> <replaceable>target</replaceable>.
3209+
3210+
When no target is specified, everything except documentation is
3211+
built. Individual build products can be built using the path/filename as
3212+
<replaceable>target</replaceable>.
3213+
</para>
3214+
3215+
&targets-meson;
3216+
</sect2>
3217+
32033218
</sect1>
32043219

32053220
<sect1 id="install-post">

‎doc/src/sgml/meson.build‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,15 @@ doc_generated += custom_target('keywords-table.sgml',
7171
capture: true,
7272
)
7373

74+
doc_generated += custom_target('targets-meson.sgml',
75+
input: files('targets-meson.txt'),
76+
output: 'targets-meson.sgml',
77+
command: [perl, files('generate-targets-meson.pl'), '@INPUT@'],
78+
build_by_default: false,
79+
install: false,
80+
capture: true,
81+
)
82+
7483
# For everything else we need at least xmllint
7584
if not xmllint_bin.found()
7685
subdir_done()

‎doc/src/sgml/targets-meson.txt‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Copyright (c) 2023, PostgreSQL Global Development Group
2+
#
3+
# Description of important meson targets, used for the 'help' target and
4+
# installation.sgml (via generate-targets-meson.pl). Right now the parsers are
5+
# extremely simple. Both parsers ignore comments. The help target prints
6+
# everything else. For xml everything without a leading newline is a group,
7+
# remaining lines are target separated by whitespace from their description
8+
#
9+
Code Targets:
10+
all Build everything other than documentation
11+
backend Build backend and related modules
12+
bin Build frontend binaries
13+
contrib Build contrib modules
14+
pl Build procedual languages
15+
16+
Developer Targets:
17+
reformat-dat-files Rewrite catalog data files into standard format
18+
expand-dat-files Expand all data files to include defaults
19+
update-unicode Update unicode data to new version
20+
21+
Documentation Targets:
22+
html Build documentation in multi-page HTML format
23+
man Build documentation in man page format
24+
docs Build documentation in multi-page HTML and man page format
25+
doc/src/sgml/postgres-A4.pdf Build documentation in PDF format, with A4 pages
26+
doc/src/sgml/postgres-US.pdf Build documentation in PDF format, with US letter pages
27+
doc/src/sgml/postgres.html Build documentation in single-page HTML format
28+
alldocs Build documentation in all supported formats
29+
30+
Installation Targets:
31+
install Install postgres, excluding documentation
32+
install-docs Install documentation in multi-page HTML and man page formats
33+
install-html Install documentation in multi-page HTML format
34+
install-man Install documentation in man page format
35+
install-quiet Like "install", but installed files are not displayed
36+
install-world Install postgres, including multi-page HTML and man page documentation
37+
uninstall Remove installed files
38+
39+
Other Targets:
40+
clean Remove all build products
41+
test Run all enabled tests (including contrib)
42+
world Build everything, including documentation
43+
help List important targets

‎meson.build‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3335,6 +3335,13 @@ alias_target('testprep', testprep_targets)
33353335
alias_target('world', all_built, docs)
33363336
alias_target('install-world', install_quiet, installdocs)
33373337

3338+
run_target('help',
3339+
command: [
3340+
perl, '-ne', 'next if /^#/; print',
3341+
files('doc/src/sgml/targets-meson.txt'),
3342+
]
3343+
)
3344+
33383345

33393346

33403347
###############################################################

0 commit comments

Comments
 (0)