Re: meson documentation build open issues

Hi,

On 2023-11-03 15:26:05 +0100, Christoph Berg wrote:
> Re: Peter Eisentraut
> > > "meson compile" doesn't seem to build the docs by default ( see <https://buildfarm.postgresql.org/cgi-bin/show_stage_log.pl?nm=crake&dt=2023-04-06%2018%3A17%3A04&stg=build>),
> > > and I'd rather it didn't, building the docs is a separate and optional
> > > step for the buildfarm.
> >
> > You can control this with the "docs" option for meson, as of recently.
>
> I've been looking into switching the Debian PG 17 build to meson, but
> I'm running into several problems.
>
> * The docs are still not built by default, and -Ddocs=enabled doesn't
> change that

Maybe I am missing something - they aren't built by default in autoconf
either?

> * None of the "build docs" targets are documented in install-meson.html

Hm, odd, I thought they were, but you are right. There were some docs patches
that we never really could find agreement upon :/

> * "ninja -C build alldocs" works, but it's impossible to see what
> flavors it's actually building. Everything is autodetected, and
> perhaps I would like to no build the .txt/something variants,
> but I have no idea what switch that is, or what package I have to
> uninstall so it's not autodetected (only html and pdf are
> documented.)

I think a package build should probably turn off auto-detection (
meson setup --auto-features=disabled) and enable specific features that are
desired - in which case you get errors if they are not available. Which
presumably is the behaviour you'd like?

> Are there any other targets for the individual formats? (I could
> probably use one for the manpages only, without the html.)

Yes, there are.
ninja doc/src/sgml/{postgres-A4.pdf,html,postgres.html,man1}

Perhaps more interesting for your purposes, there are the
install-doc-{html,man} targets.

I remember discussing adding doc-{html,man} targets alongside
install-doc-{html,man}, not sure why we ended up not doing that. I'd be in
favor of adding them.

I've also been wondering about a 'help' target that documents important
targets in a interactively usable way.

> Non-doc issues:
>
> * LLVM is off by default (ok), when I enable it with -Dllvm=auto, it
> gets detected, but no .bc files are built, nor installed

Support for that has not yet been merged.

> * selinux is not autodetected. It needs -Dselinux=auto, but that's not
> documented in install-meson.html

Uh, huh. There's no documentation for --with-selinux in the installation.sgml
either, just in sepgsql.sgml. So when the relevant docs got translated to
meson, -Dselinux= wasn't documented either.

> * There is no split between libdir and pkglibdir. We had used that in
> the past for libpq -> /usr/lib/x86_64-linux-gnu and PG stuff ->
> /usr/lib/postgresql/17/lib.

I don't think the autoconf build currently exposes separately configuring
pkglibdir either, I think that's a debian patch? I'm entirely open to adding
an explicit configuration option for this though.

Thanks for looking at this, it's quite helpful!

Greetings,

Andres Freund