Hi,
On 2023-11-14 16:30:24 -0800, Andres Freund wrote:
> On 2023-11-14 16:22:31 -0800, Andres Freund wrote:
> > > v2-0004-meson-Add-world-target.patch
> > >
> > > AFAICT, this world target doesn't include the man target. (Again, this
> > > would all work better if we added "man" to "docs".)
> >
> > I agree with that sentiment - I only moved to the current arrangement after
> > Tom argued forcefully against building both.
>
> Another message in this thread made me realize that I actually hadn't
> implemented it at all - it was Tom in 969509c3f2e
>
> In HEAD, also document how to build docs using Meson, and adjust
> "ninja docs" to just build the HTML docs, for consistency with the
> default behavior of doc/src/sgml/Makefile.
>
>
> I think that change was just ill-advised, given that the top-level make target
> actually *does* build both html and man:
>
> > The situation in the make world is weird:
> > "make docs" in the toplevel builds both, because it's defined as
> >
> > docs:
> > $(MAKE) -C doc all
>
> Notwithstanding this:
>
> > Buf if you "make -C doc/src/sgml" (or are in doc/src/sgml), we only build
> > html, as the default target is explicitly just html:
>
> As the obvious thing for people that really just want to build html with ninja
> would be to just use the doc-html (to-be-renamed to "html") target.
I pushed the first two commits (the selinux stuff) and worked a bit more on
the subsequent ones.
- As requested, I've renamed the 'doc-html' and 'doc-man' targets to just 'html'
and 'man'. Which then seems to also necessitates renaming the existing
install-doc-{html,man}. I'm not so sure about this change, likely because I
use autocomplete to remember the spelling of ninja (or make) targets, which
is easier with [install-]doc-{html,man} than with [install-]{html,man}.
- I added a commit to change what 'docs' builds, undoing that part of
969509c3f2e. I also moved the 'all' target in doc/src/sgml/Makefile up to
the 'html' target to make things less confusing there, as discussed in the
thread referenced in the commit message.
Because of the 'html' target, Tom can still just build html easily.
- I renamed 'meson-targets.txt' to 'targets-meson.txt' and renamed other files
to match. One reason is that meson tries to prevent conflict between its
internal targets by prefixing them with 'meson-', and the old names
conflicted with that rule. If we ever wanted to add something similar for
make, the new naming also seems better.
- I added documentation for some developer targets (reformat-dat-files,
expand-dat-files, update-unicode)
I didn't move 'world' in the docs, as it doesn't quite seem right in the "code
targets" section?
I attached the pkglibdir thing again, even though I don't plan to push it or
really review it further. Thought it might still be interesting for Christoph.
Greetings,
Andres Freund
>From 52a94efbcac0520716c792a33f0216e22584c72a Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Wed, 15 Nov 2023 18:53:03 -0800
Subject: [PATCH v3 1/5] meson: docs: Add {html,man} targets, rename
install-doc-*
We have toplevel html, man targets in the autoconf build as well. It'd be odd
to have an 'html' target but have the install target be 'install-doc-html',
thus rename the install targets to match.
Reviewed-by: Christoph Berg <m...@debian.org>
Discussion: https://postgr.es/m/20231103163848.26egkh5qdgw3v...@awork3.anarazel.de
---
doc/src/sgml/meson.build | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index 90e2c062fa8..e5a38e060c7 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -142,7 +142,8 @@ if docs_dep.found()
'--install-dir-contents', dir_doc_html, html],
build_always_stale: true, build_by_default: false,
)
- alias_target('install-doc-html', install_doc_html)
+ alias_target('html', html)
+ alias_target('install-html', install_doc_html)
# build and install multi-page html docs as part of docs target
docs += html
@@ -231,7 +232,8 @@ if docs_dep.found()
'--install-dirs', dir_man, '@INPUT@'],
build_always_stale: true, build_by_default: false,
)
- alias_target('install-doc-man', install_doc_man)
+ alias_target('man', man)
+ alias_target('install-man', install_doc_man)
# even though we don't want to build man pages as part of 'docs', we do want
# to install them as part of install-docs
--
2.38.0
>From 69b85a8224aaa52aa5896fbfa6952ae18c184219 Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Fri, 17 Nov 2023 10:29:19 -0800
Subject: [PATCH v3 2/5] docs: Change what 'docs' meson target builds
This undoes the change in what the 'docs' target builds 969509c3f2e. Tom was
concerned with having a target to just build the html docs, which a prior
commit now provided explicitly.
A subsequent commit will overhaul the documentation for the documentation
targets.
While at it, move all target in doc/src/sgml/Makefile up to just after the
default "html" target, and add a comment explaining "all" is *not* the default
target.
Author:
Reviewed-by:
Discussion: https://postgr.es/m/20230209203855.njrepiupc3rme...@awork3.anarazel.de
Discussion: https://postgr.es/m/20231103163848.26egkh5qdgw3v...@awork3.anarazel.de
Backpatch:
---
doc/src/sgml/Makefile | 4 ++--
doc/src/sgml/docguide.sgml | 2 +-
doc/src/sgml/meson.build | 4 ++--
3 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 49d35dd0d6e..53100828a64 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -15,6 +15,8 @@
# Make "html" the default target, since that is what most people tend
# to want to use.
html:
+# Note that all is *not* the default target in this directory
+all: html man
# We don't need the tree-wide headers or install support here.
NO_GENERATED_HEADERS=yes
@@ -25,8 +27,6 @@ top_builddir = ../../..
include $(top_builddir)/src/Makefile.global
-all: html man
-
ifndef DBTOEPUB
DBTOEPUB = $(missing) dbtoepub
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index fd72b3975ad..b319621fdb8 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -442,7 +442,7 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
<para>
To build just the <acronym>HTML</acronym> version of the documentation:
<screen>
-<prompt>build$ </prompt><userinput>ninja docs</userinput>
+<prompt>build$ </prompt><userinput>ninja html</userinput>
</screen>
To build all forms of the documentation:
<screen>
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index e5a38e060c7..dfdb1d0daa7 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -235,9 +235,9 @@ if docs_dep.found()
alias_target('man', man)
alias_target('install-man', install_doc_man)
- # even though we don't want to build man pages as part of 'docs', we do want
- # to install them as part of install-docs
+ # built and installed as part of the the docs target
installdocs += install_doc_man
+ docs += man
endif
--
2.38.0
>From 40f0eae1be25aec792638cfe48145c79de8bb8de Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Fri, 17 Nov 2023 10:29:32 -0800
Subject: [PATCH v3 3/5] meson: Add 'world' target
We have this for make as well.
Author:
Reviewed-by:
Discussion: https://postgr.es/m/
Backpatch:
---
meson.build | 2 ++
1 file changed, 2 insertions(+)
diff --git a/meson.build b/meson.build
index 286d7e42698..588788aad4d 100644
--- a/meson.build
+++ b/meson.build
@@ -3331,6 +3331,8 @@ alias_target('bin', bin_targets + [libpq_st])
alias_target('pl', pl_targets)
alias_target('contrib', contrib_targets)
alias_target('testprep', testprep_targets)
+
+alias_target('world', all_built, docs)
alias_target('install-world', install_quiet, installdocs)
--
2.38.0
>From 70c2253d1967ab4ffca9d0b241b111515e072118 Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
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.ww542mt6lfo6f...@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
<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>
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 @@
<!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
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
+ "<!-- 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
index 8e926a3a8cb..b23b35cd8e7 100644
--- 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
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
>From 96d6424087cf2d35b81df032050e2c1fc07ee74a Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Fri, 3 Nov 2023 10:06:00 -0700
Subject: [PATCH v3 5/5] meson: Add -Dpkglibdir option
Author:
Reviewed-by:
Discussion: https://postgr.es/m/20231103163848.26egkh5qdgw3v...@awork3.anarazel.de
Backpatch:
---
meson.build | 9 ++++++---
meson_options.txt | 3 +++
doc/src/sgml/installation.sgml | 18 +++++++++++++++---
3 files changed, 24 insertions(+), 6 deletions(-)
diff --git a/meson.build b/meson.build
index ee58ee7a065..ed4c664e6eb 100644
--- a/meson.build
+++ b/meson.build
@@ -492,9 +492,12 @@ endif
dir_lib = get_option('libdir')
-dir_lib_pkg = dir_lib
-if not (dir_prefix_contains_pg or dir_lib_pkg.contains('pgsql') or dir_lib_pkg.contains('postgres'))
- dir_lib_pkg = dir_lib_pkg / pkg
+dir_lib_pkg = get_option('pkglibdir')
+if dir_lib_pkg == ''
+ dir_lib_pkg = dir_lib
+ if not (dir_prefix_contains_pg or dir_lib_pkg.contains('pgsql') or dir_lib_pkg.contains('postgres'))
+ dir_lib_pkg = dir_lib_pkg / pkg
+ endif
endif
dir_pgxs = dir_lib_pkg / 'pgxs'
diff --git a/meson_options.txt b/meson_options.txt
index be1b327f544..82441b4d524 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -70,6 +70,9 @@ option('darwin_sysroot', type: 'string', value: '',
option('rpath', type: 'boolean', value: true,
description: 'Embed shared library search path in executables')
+option('pkglibdir', type: 'string', value: '',
+ description: 'Directory to install / load dynamically loadable modules from')
+
# External dependencies
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index b23b35cd8e7..3b6e49dbdbb 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -2254,9 +2254,21 @@ ninja install
<term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
<listitem>
<para>
- Sets the location to install libraries and dynamically loadable
- modules. The default is
- <filename><replaceable>PREFIX</replaceable>/lib</filename>.
+ Sets the location to install libraries. The default is
+ <filename><replaceable>PREFIX</replaceable>/lib</filename>. This
+ option, unless <xref linkend='configure-pkglibdir-meson'/> is
+ specified, also controls where dynamically loadable modules get
+ installed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-pkglibdir-meson">
+ <term><option>-Dpkglibdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the location to dynamically loadable modules. The default is set
+ by <xref linkend='configure-libdir-meson'/>.
</para>
</listitem>
</varlistentry>
--
2.38.0
