From 70c2253d1967ab4ffca9d0b241b111515e072118 Mon Sep 17 00:00:00 2001 From: Andres Freund 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 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 4c63a7e7689..bd42b3ef16b 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 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 + "\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 8e926a3a8cb..b23b35cd8e7 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 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