Re: meson documentation build open issues

Re: Andres Freund
> > > 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?

True, but the documentation (and this thread) reads like it should. Or
at least it should, when I explicitly say -Ddocs=enabled.

What would also help is when the tail of the meson output had a list
of features that are enabled. There's the list of "External libraries"
which is quite helpful at figuring out what's still missing, but
perhaps this could be extended:

  Features
    LLVM     : YES (/usr/bin/llvm-config-16)
    DOCS     : YES (html pdf texinfo)

Atm it's hidden in the long initial blurb of "Checking for.." and the
"NO" in there don't really stand out as much, since some of them are
normal.

> > * "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?

I'm still trying to figure out the best spot in that space of options.
Currently I'm still in the phase of getting it to work at all; the end
result might well use that option.

> >   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}

Oh, that was not obvious to me that this "make $some_file" style
command would work. (But it still leaves the problem of knowing which
targets there are.)

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

Hmm, I thought I had tried these, but apparently managed to miss them.
Thanks.

install-doc-man seems to install "man1" only, though?
(It seems to compile man5/man7, but not install them.)

> 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.

That is definitely missing, yes. I found out about "alldocs" only
after reading the meson files, and that took more than it should have.

> > 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.

Oh, that's a showstopper. I thought meson would already be ready for
production use. There is indeed an "experimental" note in
install-requirements.html, but not in install-meson.html

> > * 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.

Ok. It does show up in "External libraries" and was enabled in the
Debian packages before.

Why isn't it "auto" like the others?

> > * 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.

That would definitely be helpful.

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

Thanks for the feedback!
Christoph