From 07cb29737a4ea9bd28e436eecb4016c3202e3928 Mon Sep 17 00:00:00 2001 From: Andres Freund Date: Mon, 20 Nov 2023 17:46:40 -0800 Subject: [PATCH] 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 Discussion: https://postgr.es/m/20231108232121.ww542mt6lfo6f26f@awork3.anarazel.de --- 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 ++++++++++++++++++ meson.build | 7 +++ 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/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 53100828a6..2ef818900f 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 b319621fdb..c129215dd3 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 Building the Documentation with Meson - Two options are provided for building the documentation using Meson. - Change to the build directory before running - one of these commands, or add to the command. + To build the documentation using Meson, change to the + build directory before running one of these commands, + or add to the command. @@ -444,10 +444,9 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN build$ ninja html - To build all forms of the documentation: - -build$ ninja alldocs - + For a list of other documentation targets see + . + The output appears in the subdirectory build/doc/src/sgml. diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 4c63a7e768..bd42b3ef16 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -38,6 +38,7 @@ + diff --git a/doc/src/sgml/generate-targets-meson.pl b/doc/src/sgml/generate-targets-meson.pl new file mode 100644 index 0000000000..56a94d6ead --- /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 + "\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( + + $targets Targets + + +); + + # 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( + + + + + ${desc} + + + +); + } + + print qq( + + +); + } +} + +close $targets_meson; diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 8e926a3a8c..b23b35cd8e 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -3200,6 +3200,21 @@ ninja install + + + <literal>meson</literal> Build Targets + + + Individual build targets can be built using ninja target. + + When no target is specified, everything except documentation is + built. Individual build products can be built using the path/filename as + target. + + + &targets-meson; + + diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build index dfdb1d0daa..e1a85dc607 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 0000000000..2cd192efda --- /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 diff --git a/meson.build b/meson.build index 588788aad4..ee58ee7a06 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'), + ] +) + ###############################################################