Обсуждение: meson documentation build open issues

Поиск

Список

Период

Сортировка

meson documentation build open issues

От

Peter Eisentraut

Дата:

15 марта 2023 г., 10:14:09

I have identified several open issues with the documentation build under 
Meson (approximately in priority order):

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

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

3. The various build targets and their combinations are mismatching and 
incomplete.  For example:

Top-level GNUmakefile has these targets:

- docs (builds html and man)
- html
- man

(Those are the formats that are part of a distribution build.)

doc/src/sgml/Makefile has these documented targets:

- default target is html
- all (builds html and man, maps to top-level "docs")
- html
- man
- postgres-A4.pdf
- postgres-US.pdf
- check

as well as (undocumented):

- htmlhelp
- postgres.html
- postgres.txt
- epub
- postgres.epub
- postgres.info

meson has the following documented targets:

- docs (builds only html)
- alldocs (builds all formats, including obscure ones)

as well as the following undocumented targets:

- html
- man
- html_help [sic]
- postgres-A4.pdf
- postgres-US.pdf
- postgres.epub

- [info is not implemented at all]
- [didn't find an equivalent of check]

As you can see, this is all over the place.  I'd like to arrive at some 
consistency across all build systems for handling each tier of 
documentation formats, in terms of what is documented, what the targets 
are named, and how they are grouped.

4. There doesn't appear to be a way to install the documentation.
(There are also some open questions in the top-level meson.build about
the installation directories, but I suppose if we can't install them
then exactly where to install them hasn't been thought about too
much.)

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

Re: meson documentation build open issues

От

Andres Freund

Дата:

16 марта 2023 г., 06:55:33

Hi,

On 2023-03-15 08:14:09 +0100, Peter Eisentraut wrote:
> I have identified several open issues with the documentation build under
> Meson (approximately in priority order):
>
> 1. Image files are not handled at all, so they don't show up in the final
> product.

Hm. Somehow I thought I'd tackled that at some point. Ah. I got there for the
PDF output, but didn't realize it's also an issue for the html output.

For FO it sufficed to set the img.src.path param. For HTML that's not enough,
because that just adjusts the link to the file - but we don't want to link to
the source file. We actually solved this for the single-page html version - we
just embed the svg.  I wonder if we should just do that as well.

Another way would be to emit the files into the desired place as part of the
stylesheet. While it requires touching xslt, it does seems somewhat more
elegant than just copying files around. I did implement that, curious what you
think.

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

Should we add a meson option?

> 3. The various build targets and their combinations are mismatching and
> incomplete.  For example:
>
> Top-level GNUmakefile has these targets:
>
> - docs (builds html and man)
> - html
> - man
>
> (Those are the formats that are part of a distribution build.)
>
> doc/src/sgml/Makefile has these documented targets:
>
> - default target is html
> - all (builds html and man, maps to top-level "docs")
> - html
> - man
> - postgres-A4.pdf
> - postgres-US.pdf
> - check
>
> as well as (undocumented):
>
> - htmlhelp
> - postgres.html
> - postgres.txt
> - epub
> - postgres.epub
> - postgres.info
>
> meson has the following documented targets:
>
> - docs (builds only html)
> - alldocs (builds all formats, including obscure ones)
>
> as well as the following undocumented targets:
>
> - html
> - man
> - html_help [sic]

renamed in the attached patch.

> - postgres-A4.pdf
> - postgres-US.pdf
> - postgres.epub

Note that these are actually named doc/src/sgml/{html,man,...}, not top-level
targets.

> - [info is not implemented at all]

Would be easy to implement, but not sure it's worth doing.

> - [didn't find an equivalent of check]

That's probably worth doing - should it be run as an actual test, or be a
target?

> 4. There doesn't appear to be a way to install the documentation.
> (There are also some open questions in the top-level meson.build about
> the installation directories, but I suppose if we can't install them
> then exactly where to install them hasn't been thought about too
> much.)

WIP patch for that attached. There's now
  install-doc-man
  install-doc-html
run targets and a
  install-docs
alias target.

I did end up getting stuck when hacking on this, and ended up adding css
support for nochunk and support for the website style for htmlhelp and
nochunk, as well as obsoleting the need for copying the css files... But
perhaps that's a bit too much.

Greetings,

Andres Freund

Вложения

Re: meson documentation build open issues

От

Andres Freund

Дата:

20 марта 2023 г., 05:33:38

Hi,

On 2023-03-15 20:55:33 -0700, Andres Freund wrote:
> WIP patch for that attached. There's now
>   install-doc-man
>   install-doc-html
> run targets and a
>   install-docs
> alias target.
> 
> 
> I did end up getting stuck when hacking on this, and ended up adding css
> support for nochunk and support for the website style for htmlhelp and
> nochunk, as well as obsoleting the need for copying the css files... But
> perhaps that's a bit too much.

Updated set of patches attached. This one works in older meson versions too
and adds install-world and install-quiet targets.

I also ended up getting so frustrated at the docs build speed that I started
to hack a bit on that. I attached a patch shaving a few seconds off the
buildtime.

I think we can make the docs build in parallel and incrementally, by building
the different parts of the docs in parallel, using --stringparam rootid,
e.g. building each 'part' separately.

A very very rough draft attached:

parallel with parts:
real    0m10.831s
user    0m58.295s
sys    0m1.402s

normal:
real    0m32.215s
user    0m31.876s
sys    0m0.328s

1/3 of the build time at 2x the cost is nothing to sneeze at.

Greetings,

Andres Freund

Hi,

On 2023-03-22 11:59:17 -0700, Andres Freund wrote:
> Unless somebody sees a reason to wait, I am planning to commit:
>   meson: add install-{quiet, world} targets
>   meson: add install-{docs,doc-html,doc-man} targets
>   meson: make install_test_files more generic, rename to install_files

I've done that now.

> For the .css: docbook-xsl actually has support for writing the .css: [1] - but
> it requires the .css file be valid xml. I wonder if the cleanest approch would
> be to have a build step to create .css.xml - then the non-chunked build's
> generate.css.header would do the right thing.

We don't even need to do that! The attached patch just creates a wrapper
css.xml that loads the .css via an entity reference.

I think this looks reasonably complicated, given that it gives us a working
stylesheet for the non-chunked output?

I don't know if my hack of putting the paramters in stylesheet-common.xsl is
reasonable. Perhaps we should just include stylesheet-html-common.xsl in
stylesheet-hh.xsl, then this uglyness wouldn't be required.

Greetings,

Andres Freund

On Tue, 28 Mar 2023 at 10:46, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:

On 24.03.23 17:58, Andres Freund wrote:
> On 2023-03-24 11:59:23 +0100, Peter Eisentraut wrote:
>> Another option here is to remove support for htmlhelp.
>
> That might actually be the best path - it certainly doesn't look like anybody
> has been actively using it. Or otherwise somebody would have complained about
> there not being any instructions on how to actually compile a .chm file. And
> perhaps complained that it takes next to forever to build.
>
> I also have the impression that people don't use the .chm stuff much anymore,
> but that might just be me not using windows.

I think in ancient times, pgadmin used it for its internal help.

Yes, very ancient :-). We use Sphinx now.

But I have heard less about htmlhelp over the years than about the info
format.

Dave Page
Blog: https://pgsnake.blogspot.com
Twitter: @pgsnake

EDB: https://www.enterprisedb.com

Re: meson documentation build open issues

От

Peter Eisentraut

Дата:

05 апреля 2023 г., 13:24:04

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.

Re: meson documentation build open issues

От

Andres Freund

Дата:

05 апреля 2023 г., 17:45:12

Hi,

On 2023-04-05 12:24:04 +0200, Peter Eisentraut wrote:
> On 15.03.23 08:14, Peter Eisentraut wrote:
> > 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.

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.


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

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

Greetings,

Andres Freund

Re: meson documentation build open issues

От

Peter Eisentraut

Дата:

06 апреля 2023 г., 12:11:57

On 05.04.23 16:45, Andres Freund 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.

Ok, not a topic for this thread then.

>>> 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.
> 
> I'm not following - install-world install docs if the docs feature is
> 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.

Re: meson documentation build open issues

От

Andrew Dunstan

Дата:

07 апреля 2023 г., 17:39:56

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

On 05.04.23 16:45, Andres Freund 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.

Ok, not a topic for this thread then.

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.

I'm not following - install-world install docs if the docs feature is
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.

"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

Re: meson documentation build open issues

От

Peter Eisentraut

Дата:

12 апреля 2023 г., 18:30:28

On 07.04.23 16:39, Andrew Dunstan wrote:
>>>>> 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.
>>>
>>> I'm not following - install-world install docs if the docs feature is
>>> 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.
> 
> "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'drather 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.

Re: meson documentation build open issues

От

Christoph Berg

Дата:

03 ноября 2023 г., 17:26:05

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

* 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

Re: meson documentation build open issues

От

Andres Freund

Дата:

03 ноября 2023 г., 19:38:48

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

Re: meson documentation build open issues

От

Christoph Berg

Дата:

03 ноября 2023 г., 21:19:17

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

Re: meson documentation build open issues

От

Andres Freund

Дата:

03 ноября 2023 г., 21:53:44

Hi,

On 2023-11-03 19:19:17 +0100, Christoph Berg wrote:
> 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.

My understanding of the intent of the options is to make meson error out if
the required dependencies are not available, not that it controls when the
build targets are built.

The reason for that is simply that the docs take too long to build.


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

The summary does include both. LLVM is 'llvm', man/html docs is 'docs' and pdf
docs as 'docs_pdf'.


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

Yes, you can trigger building any file that way.

The following is *not* an argument the docs targets shouldn't be documented
(working on a patch), just something that might be helpful until then /
separately. You can see which targets are built with

ninja -t targets all|grep doc/src/


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

Ugh, that's obviously a bug. I'll fix it.


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

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


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

I don't really remember why I did that, but it's platform specific, maybe
that's why I did it that way?


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

I have a patch locally, will send it together with a few others in a bit.

Greetings,

Andres Freund

Re: meson documentation build open issues

От

Christoph Berg

Дата:

03 ноября 2023 г., 22:19:18

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.

> The summary does include both. LLVM is 'llvm', man/html docs is 'docs' and pdf
> docs as 'docs_pdf'.

Sorry, I should have looked closer. :(

> The following is *not* an argument the docs targets shouldn't be documented
> (working on a patch), just something that might be helpful until then /
> separately. You can see which targets are built with
> 
> ninja -t targets all|grep doc/src/

Thanks.

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

> > Why isn't it "auto" like the others?
> 
> I don't really remember why I did that, but it's platform specific, maybe
> that's why I did it that way?

Isn't that kind the point of autodetecting things? Aren't bonjour and
bsd_auth autodetected as well?

> > > 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.
> 
> I have a patch locally, will send it together with a few others in a bit.

Thanks!

Christoph

Re: meson documentation build open issues

От

Andres Freund

Дата:

04 ноября 2023 г., 00:16:01

Hi,


On 2023-11-03 20:19:18 +0100, Christoph Berg wrote:
> 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.


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


> > > Why isn't it "auto" like the others?
> >
> > I don't really remember why I did that, but it's platform specific, maybe
> > that's why I did it that way?
>
> Isn't that kind the point of autodetecting things? Aren't bonjour and
> bsd_auth autodetected as well?

I'd be happy to change it, unless somebody objects?


> > > > 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.
> >
> > I have a patch locally, will send it together with a few others in a bit.
>
> Thanks!

Attached.

0001 - the bugfix for install-man only installing man1, I'll push that soon
0002 - Document --with-selinux/-Dselinux options centrally
0003 - Add doc-{html,man} targets

       I'm not quite sure it's worth it, but it's basically free, so ...

0004 - Documentation for important build targets

       I'm not entirely happy with the formatting, but it looks like that's
       mostly a CSS issue. I started a thread on fixing that on -www.

0005 - Add -Dpkglibdir option

       I guess we might want to do the same for configure if we decide to do
       this?

Greetings,

Andres Freund

On 07.11.23 17:08, Andres Freund wrote:
>> make world
>> make check-world
>> make install-world
>>
>> that encompasses everything.
>>
>> Now with meson to handle the documentation one needs to remember a variety of additional targets.  (There is a risk
thatonce this gets more widespread, more people will submit broken documentation.)

> install-world with meson also installs docs.

Ok, I didn't know about ninja install-world.  That works for me.  Maybe 
a "world" target would also be good.

I played around with this a bit and noticed some files missing or in the 
wrong place.  See two attached patches (plus e9f075f9a1 already committed).

Hi,

I really like the idea of an 'help' target that prints the targets. It seemed
annoying to document such targets in both the sgml docs and the input for a
the help target. Particularly due to the redundancies between id attributes,
the target name etc.

First I generated the list of targets from within meson.build, only to later
realize that that would not work when building the docs via make. So I instead
added doc/src/sgml/meson-targets.txt which is lightly postprocessed for the
'help' target, and slightly more processed when building the docs.

That does have some downsides, e.g. it'd be more complicated to only print
targets if a relevant option is enabled. But I think it's acceptable that way.


Example output:

$ ninja help
[0/1 1   0%] Running external command help (wrapped by meson to set env)
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

Documentation Targets:
  docs                         Build documentation in multi-page HTML format
  doc-html                     Build documentation in multi-page HTML format
  doc-man                      Build documentation in 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-doc-html             Install documentation in multi-page HTML format
  install-doc-man              Install documentation in man page format
  install-docs                 Install documentation in multi-page HTML and man page formats
  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


Because of the common source, some of the descriptions in the state of this
patch are a bit shorter than in the preceding commit. But I don't think that
hurts much.

Greetings,

Andres Freund

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

On 21.11.23 14:23, Peter Eisentraut wrote:
> On 21.11.23 02:56, Andres Freund wrote:
>> One remaining question is whether we should adjust 
>> install-doc-{html,man} to
>> be install-{html,man}, to match the docs targets.
> 
> Ah didn't notice that one; yes please.

I think this was done?

Вход в личный кабинет

Восстановление пароля

Подтверждение аккаунта

Изменение пароля

Обсуждение: meson documentation build open issues

Вложения

Вложения

Вложения

Вложения

Вложения

Вложения

Вложения