Date: Mon, 6 Nov 2023 10:45:27 +0100
From: Christoph Berg <myon@debian.org>
To: Andres Freund <andres@anarazel.de>
Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>,
	Andrew Dunstan <andrew@dunslane.net>, Tom Lane <tgl@sss.pgh.pa.us>,
	pgsql-hackers <pgsql-hackers@postgresql.org>
Subject: Re: meson documentation build open issues
Message-ID: <ZUi1ty-o4dihr3oa@msg.df7cb.de>
Mail-Followup-To: Christoph Berg <myon@debian.org>,
	Andres Freund <andres@anarazel.de>,
	Peter Eisentraut <peter.eisentraut@enterprisedb.com>,
	Andrew Dunstan <andrew@dunslane.net>, Tom Lane <tgl@sss.pgh.pa.us>,
	pgsql-hackers <pgsql-hackers@postgresql.org>
References: <20230405144512.zfzb6vd77dk5dnyr@awork3.anarazel.de>
 <50193d79-e7d1-ea81-1ef3-5670b007c7c3@enterprisedb.com>
 <c3e12a10-5824-f9c7-ad09-c66720df7b2d@dunslane.net>
 <b2437a6f-b083-5abe-6bdf-f5968a666992@enterprisedb.com>
 <ZUUC_T52xTbaXRys@msg.df7cb.de>
 <20231103163848.26egkh5qdgw3vmil@awork3.anarazel.de>
 <ZUU5pRQO6ZUeBsi6@msg.df7cb.de>
 <20231103185344.zhfzturwdbp4d4s5@awork3.anarazel.de>
 <ZUVHttJNHalXcUNx@msg.df7cb.de>
 <20231103211601.bgqx3cfq6pz2lmjw@awork3.anarazel.de>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20231103211601.bgqx3cfq6pz2lmjw@awork3.anarazel.de>
Archived-At: 
 <https://www.postgresql.org/message-id/ZUi1ty-o4dihr3oa%40msg.df7cb.de>
Precedence: bulk

Re: Andres Freund
> > > The reason for that is simply that the docs take too long to build.
> >
> > That why I'd prefer to be able to separate arch:all and arch:any
> > builds, yes.
> 
> What's stopping you from doing that?  I think the only arch:any content we
> have is the docs, and those you can build separately? Doc builds do trigger
> generation of a handful of files besides the docs, but not more.

Historically, .deb files have been required to contain the manpages
for all executables even when there's a separate -doc package. This
means we'd need a separate (hopefully fast) manpage build even when
the arch:any binaries are built. We might get around that by
introducing a new postgresql-manpages-XX arch:all package, but that
might be too much micropackaging.

The install-doc-man target will likely fix it, will play with it a bit
more, thanks.

> > > I'm working on merging it. Having it for core PG isn't a huge difficulty, the
> > > extension story is what's been holding me back...
> >
> > In-core extensions or external ones?
> 
> Both, although the difficulty of doing it is somewhat separate for each.

I'd think most external extensions could stay with pgxs.mk for the
time being.


> +     <varlistentry id="configure-with-sepgsql-meson">
> +      <term><option>-Dselinux={ disabled | auto | enabled }</option></term>
> +      <listitem>
> +       <para>
> +        Build with selinux support, enabling the <xref linkend="sepgsql"/>
> +        extension.

This option defaults to ... auto?


> index 90e2c062fa8..003b57498bb 100644
> --- a/doc/src/sgml/meson.build
> +++ b/doc/src/sgml/meson.build
> @@ -142,6 +142,7 @@ if docs_dep.found()
>        '--install-dir-contents', dir_doc_html, html],
>      build_always_stale: true, build_by_default: false,
>    )
> +  alias_target('doc-html', install_doc_html)
>    alias_target('install-doc-html', install_doc_html)

Shouldn't this just build the html docs, without installing?

> +  alias_target('doc-man', install_doc_html)
>    alias_target('install-doc-man', install_doc_man)

... same


> +     <varlistentry id="meson-target-install-world">
> +       <term><option>install-install-world</option></term>

install-world

> +     <varlistentry id="meson-target-install-doc-man">
> +       <term><option>install-doc-html</option></term>
> +       <listitem>
> +        <para>
> +         Install documentation in man page format.

install-doc-man

> +   <sect3 id="meson-targets-docs">
> +    <title>Documentation Targets</title>

> +     <varlistentry id="meson-target-docs">
> +       <term><option>docs</option></term>
> +       <term><option>doc-html</option></term>
> +       <listitem>
> +        <para>
> +         Build documentation in multi-page HTML format.  Note that
> +         <option>docs</option> does <emphasis>not</emphasis> include building
> +         man page documentation, as man page generation seldom fails when
> +         building HTML documentation succeeds.

Why is that a reason for not building the manpages?

> +   <sect3 id="meson-targets-code">
> +    <title>Code Targets</title>

I would have expected the sections to be in the order
build-docs-install. Having install first seems weird to me.

> +   <sect3 id="meson-targets-other">
> +    <title>Other Targets</title>
> +
> +    <variablelist>
> +
> +     <varlistentry id="meson-target-clean">
> +       <term><option>clean</option></term>
> +       <listitem>
> +        <para>
> +         Remove all build products
> +        </para>
> +       </listitem>
> +     </varlistentry>
> +
> +     <varlistentry id="meson-target-test">
> +       <term><option>test</option></term>
> +       <listitem>
> +        <para>
> +         Remove all enabled tests. Support for some classes of tests can be
> +         enabled / disabled with <xref linkend="configure-tap-tests-meson"/>
> +         and <xref linkend="configure-pg-test-extra-meson"/>.

This should explicitly say if contrib tests are included (or there
needs to be a separate test-world target.)


> Subject: [PATCH v1 5/5] meson: Add -Dpkglibdir option

Will give that a try, thanks!

Christoph