Subject: Re: meson documentation build open issues

From: Peter Eisentraut <[email-masked]>
Date: Wed, 5 Apr 2023 12:24:04 +0200

On 15.03.23 08:14, Peter Eisentraut wrote:
> I have identified several open issues with the documentation build under 
> Meson (approximately in priority order):

Some work has been done on this.  Here is my current assessment.

> 1. Image files are not handled at all, so they don't show up in the 
> final product.

This is fixed.

> 2. Defaults to website stylesheet, no way to configure.  This should be 
> adjusted to match the make build.

This is fixed.

> 3. The various build targets and their combinations are mismatching and 
> incomplete.

This has been improved, and I see there is documentation.

I think it's still an issue that "make docs" builds html and man but 
"ninja docs" only builds html.  For some reason the wiki page actually 
claims that ninja docs builds both, but this does not happen for me.

> 4. There doesn't appear to be a way to install the documentation.

This has been addressed.

> 5. There doesn't appear to be an equivalent of "make world" and "make
> install-world" that includes documentation builds.

This has been addressed with the additional meson auto options.  But it 
seems that these options only control building, not installing, so there 
is no "install-world" aspect yet.

---

From: Andres Freund <[email-masked]>
Date: Wed, 5 Apr 2023 07:45:12 -0700

Hi,

On 2023-04-05 12:24:04 +0200, Peter Eisentraut wrote:
> I think it's still an issue that "make docs" builds html and man but "ninja
> docs" only builds html.  For some reason the wiki page actually claims that
> ninja docs builds both, but this does not happen for me.

It used to, but Tom insisted that it should not. I'm afraid that it's not
quite possible to emulate make here. 'make docs' at the toplevel builds both
HTML and manpages. But 'make -C doc/src/sgml', only builds HTML.

> seems that these options only control building, not installing, so there is
> no "install-world" aspect yet.

I'm not following - install-world install docs if the docs feature is
available, and not if not?

Greetings,

Andres Freund

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 6 Apr 2023 11:11:57 +0200

> HTML and manpages. But 'make -C doc/src/sgml', only builds HTML.

Ok, not a topic for this thread then.

> available, and not if not?

I had expected that if meson setup enables the 'docs' feature, then 
meson compile will build the documentation, which happens, and meson 
install will install it, which does not happen.

---

From: Andrew Dunstan <[email-masked]>
Date: Fri, 7 Apr 2023 10:39:56 -0400

On 2023-04-06 Th 05:11, Peter Eisentraut wrote:
>>> "ninja

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

cheers

andrew

--
Andrew Dunstan
EDB:https://www.enterprisedb.com

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 12 Apr 2023 17:30:28 +0200

On 07.04.23 16:39, Andrew Dunstan wrote:
> <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.

---

From: Christoph Berg <[email-masked]>
Date: Fri, 3 Nov 2023 15:26:05 +0100

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>),

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

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

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

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

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

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

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

Christoph

---

From: Andres Freund <[email-masked]>
Date: Fri, 3 Nov 2023 09:38:48 -0700

Hi,

> * The docs are still not built by default, and -Ddocs=enabled doesn't

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 :/

>   uninstall so it's not autodetected (only html and pdf are

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?

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

>   gets detected, but no .bc files are built, nor installed

Support for that has not yet been merged.

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

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