Обсуждение: Is there an undocumented Syntax Check in Meson?
$subject
Make has one:
This needs updating:
I've been using "ninja html" which isn't shown here. Also, as a sanity check, running that command takes my system 1 minute. Any idea what percentile that falls into?
David J.
"David G. Johnston" <david.g.johnston@gmail.com> writes: > I've been using "ninja html" which isn't shown here. Also, as a sanity > check, running that command takes my system 1 minute. Any idea what > percentile that falls into? On my no-longer-shiny-new workstation, "make" in doc/src/sgml (which builds just the HTML docs) takes right about 30s in HEAD. Can't believe that the overhead would be noticeably different between make and meson, since it's a simple command sequence with no opportunity for parallelism. regards, tom lane
"David G. Johnston" <david.g.johnston@gmail.com> writes: > $subject > > Make has one: > https://www.postgresql.org/docs/current/docguide-build.html#DOCGUIDE-BUILD-SYNTAX-CHECK > > This needs updating: > https://www.postgresql.org/docs/current/docguide-build-meson.html > > I've been using "ninja html" which isn't shown here. Also, as a sanity > check, running that command takes my system 1 minute. Any idea what > percentile that falls into? My laptop (8-core i7-11800H @ 2.30GHz) takes 22s to do `ninja html` after `ninja clean`. > David J. - ilmari
"David G. Johnston" <david.g.johnston@gmail.com> writes: > $subject > > Make has one: > https://www.postgresql.org/docs/current/docguide-build.html#DOCGUIDE-BUILD-SYNTAX-CHECK > > This needs updating: > https://www.postgresql.org/docs/current/docguide-build-meson.html > > I've been using "ninja html" which isn't shown here. The /devel/ version has a link to the full list of doc targets: https://www.postgresql.org/docs/devel/install-meson.html#TARGETS-MESON-DOCUMENTATION Attached is a patch which adds a check-docs target for meson, which takes 0.3s on my laptop. - ilmari From d54104493b9d97b95a890e47b395723d9b152447 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org> Date: Thu, 9 May 2024 19:59:46 +0100 Subject: [PATCH] Add a check-docs target for meson This allows checking the syntax of the docs much faster than rebuilding them all, similar to `make -C doc/src/sgml check`. --- doc/src/sgml/meson.build | 10 ++++++++++ doc/src/sgml/targets-meson.txt | 1 + 2 files changed, 11 insertions(+) diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build index e418de83a7..51eed7b31d 100644 --- a/doc/src/sgml/meson.build +++ b/doc/src/sgml/meson.build @@ -112,6 +112,16 @@ postgres_full_xml = custom_target('postgres-full.xml', docs += postgres_full_xml alldocs += postgres_full_xml +checkdocs = custom_target('check-docs', + input: 'postgres.sgml', + output: 'check-docs', + depfile: 'postgres-full.xml.d', + command: [xmllint, '--nonet', '--valid', '--noout', + '--path', '@OUTDIR@', '@INPUT@'], + depends: doc_generated, + build_by_default: false, +) +alias_target('check-docs', checkdocs) if xsltproc_bin.found() xsltproc_flags = [ diff --git a/doc/src/sgml/targets-meson.txt b/doc/src/sgml/targets-meson.txt index bd470c87a7..ba426707be 100644 --- a/doc/src/sgml/targets-meson.txt +++ b/doc/src/sgml/targets-meson.txt @@ -26,6 +26,7 @@ Documentation Targets: 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 + check-docs Check the syntax of the documentation Installation Targets: install Install postgres, excluding documentation -- 2.39.2
Hi, On 2024-05-09 20:12:38 +0100, Dagfinn Ilmari Mannsåker wrote: > Attached is a patch which adds a check-docs target for meson, which > takes 0.3s on my laptop. Nice. > +checkdocs = custom_target('check-docs', > + input: 'postgres.sgml', > + output: 'check-docs', > + depfile: 'postgres-full.xml.d', > + command: [xmllint, '--nonet', '--valid', '--noout', > + '--path', '@OUTDIR@', '@INPUT@'], > + depends: doc_generated, > + build_by_default: false, > +) > +alias_target('check-docs', checkdocs) Isn't the custom target redundant with postgres_full_xml? I.e. you could just have the alias_target depend on postgres_full_xml? Greetings, Andres Freund
On Thu, May 9, 2024 at 12:12 PM Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> wrote:
"David G. Johnston" <david.g.johnston@gmail.com> writes:
> I've been using "ninja html" which isn't shown here.
The /devel/ version has a link to the full list of doc targets:
https://www.postgresql.org/docs/devel/install-meson.html#TARGETS-MESON-DOCUMENTATION
I knew I learned about the html target from the docs. Forgot to use the devel ones this time around.
Attached is a patch which adds a check-docs target for meson, which
takes 0.3s on my laptop.
Thanks.
David J.
Andres Freund <andres@anarazel.de> writes: > Hi, > > On 2024-05-09 20:12:38 +0100, Dagfinn Ilmari Mannsåker wrote: >> Attached is a patch which adds a check-docs target for meson, which >> takes 0.3s on my laptop. > > Nice. > > >> +checkdocs = custom_target('check-docs', >> + input: 'postgres.sgml', >> + output: 'check-docs', >> + depfile: 'postgres-full.xml.d', >> + command: [xmllint, '--nonet', '--valid', '--noout', >> + '--path', '@OUTDIR@', '@INPUT@'], >> + depends: doc_generated, >> + build_by_default: false, >> +) >> +alias_target('check-docs', checkdocs) > > Isn't the custom target redundant with postgres_full_xml? I.e. you could just > have the alias_target depend on postgres_full_xml? We could, but that would actually rebuild postgres-full.xml, not just check the syntax (but that only takes 0.1-0.2s longer), and only run if the docs have been modified since it was last built (which I guess is fine, since if you haven't modified the docs you can't have introduced any syntax errors). It's already possible to run that target directly, i.e. ninja doc/src/sgml/postgres-full.xml We could just document that in the list of meson doc targets, but a shortcut alias would roll off the fingers more easily and be more discoverable. > Greetings, > > Andres Freund - ilmari
Hi, On 2024-05-09 09:23:37 -0700, David G. Johnston wrote: > This needs updating: > https://www.postgresql.org/docs/current/docguide-build-meson.html You mean it should have a syntax target? Or that something else is out of date? > Also, as a sanity check, running that command takes my system 1 minute. Any > idea what percentile that falls into? I think that's on the longer end - what OS/environment is this on? Even on ~5yo CPU with turbo boost disabled it's 48s for me. FWIW, the single-page html is a good bit faster, 29s on the same system. I remember the build being a lot slower on windows, fwiw, due to the number of files being opened/created. I guess that might also be the case on slow storage, due to filesystem journaling. Greetings, Andres Freund
Hi, On 2024-05-09 20:53:27 +0100, Dagfinn Ilmari Mannsåker wrote: > Andres Freund <andres@anarazel.de> writes: > > On 2024-05-09 20:12:38 +0100, Dagfinn Ilmari Mannsåker wrote: > >> Attached is a patch which adds a check-docs target for meson, which > >> takes 0.3s on my laptop. > >> +checkdocs = custom_target('check-docs', > >> + input: 'postgres.sgml', > >> + output: 'check-docs', > >> + depfile: 'postgres-full.xml.d', > >> + command: [xmllint, '--nonet', '--valid', '--noout', > >> + '--path', '@OUTDIR@', '@INPUT@'], > >> + depends: doc_generated, > >> + build_by_default: false, > >> +) > >> +alias_target('check-docs', checkdocs) > > > > Isn't the custom target redundant with postgres_full_xml? I.e. you could just > > have the alias_target depend on postgres_full_xml? > > We could, but that would actually rebuild postgres-full.xml, not just > check the syntax (but that only takes 0.1-0.2s longer), I don't think this is performance critical enough to worry about 0.1s. If anything I think the performance argument goes the other way round - doing the validation work multiple times is a waste of time... > and only run if the docs have been modified since it was last built (which I > guess is fine, since if you haven't modified the docs you can't have > introduced any syntax errors). That actually seems good to me. > It's already possible to run that target directly, i.e. > > ninja doc/src/sgml/postgres-full.xml > > We could just document that in the list of meson doc targets, but a > shortcut alias would roll off the fingers more easily and be more > discoverable. Agreed. Greetings, Andres Freund
On Thu, May 9, 2024 at 1:16 PM Andres Freund <andres@anarazel.de> wrote:
Hi,
On 2024-05-09 09:23:37 -0700, David G. Johnston wrote:
> This needs updating:
> https://www.postgresql.org/docs/current/docguide-build-meson.html
You mean it should have a syntax target? Or that something else is out of
date?
v17 looks good, I like the auto-generation. I failed to notice I was looking at v16 when searching for a check docs target.
> Also, as a sanity check, running that command takes my system 1 minute. Any
> idea what percentile that falls into?
I think that's on the longer end - what OS/environment is this on? Even on
~5yo CPU with turbo boost disabled it's 48s for me. FWIW, the single-page
html is a good bit faster, 29s on the same system.
Ubuntu 22.04 running in AWS Workspaces Power.
Amazon EC2 t3.xlarge
Intel® Xeon(R) Platinum 8259CL CPU @ 2.50GHz × 4
16GiB Ram
David J.
Andres Freund <andres@anarazel.de> writes: > Hi, > > On 2024-05-09 20:53:27 +0100, Dagfinn Ilmari Mannsåker wrote: >> Andres Freund <andres@anarazel.de> writes: >> > On 2024-05-09 20:12:38 +0100, Dagfinn Ilmari Mannsåker wrote: >> >> Attached is a patch which adds a check-docs target for meson, which >> >> takes 0.3s on my laptop. >> >> +checkdocs = custom_target('check-docs', >> >> + input: 'postgres.sgml', >> >> + output: 'check-docs', >> >> + depfile: 'postgres-full.xml.d', >> >> + command: [xmllint, '--nonet', '--valid', '--noout', >> >> + '--path', '@OUTDIR@', '@INPUT@'], >> >> + depends: doc_generated, >> >> + build_by_default: false, >> >> +) >> >> +alias_target('check-docs', checkdocs) >> > >> > Isn't the custom target redundant with postgres_full_xml? I.e. you could just >> > have the alias_target depend on postgres_full_xml? >> >> We could, but that would actually rebuild postgres-full.xml, not just >> check the syntax (but that only takes 0.1-0.2s longer), > > I don't think this is performance critical enough to worry about 0.1s. If > anything I think the performance argument goes the other way round - doing the > validation work multiple times is a waste of time... These targets are both build_by_default: false, so the checkdocs target won't both be built when building the docs. But reusing the postgres_full_xml target will save half a second of the half-minute build time if you then go on to actually build the docs without changing anything after the syntax check passes. >> and only run if the docs have been modified since it was last built (which I >> guess is fine, since if you haven't modified the docs you can't have >> introduced any syntax errors). > > That actually seems good to me. > > >> It's already possible to run that target directly, i.e. >> >> ninja doc/src/sgml/postgres-full.xml >> >> We could just document that in the list of meson doc targets, but a >> shortcut alias would roll off the fingers more easily and be more >> discoverable. > > Agreed. Here's a v2 patch that does it that way. Should we document that check-docs actually builds postgres-full.xml, and if so, where? > Greetings, > > Andres Freund - ilmari From 20b5a8e96ec88022b63062f9e4d74d46f09cedd6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org> Date: Thu, 9 May 2024 19:59:46 +0100 Subject: [PATCH v2] Add a check-docs target for meson This is is just an alias for the `postgres-full.xml` target, but is more discoverable and quicker to type. This allows checking the syntax of the docs much faster than actually building them, similar to `make -C doc/src/sgml check`. --- doc/src/sgml/meson.build | 2 ++ doc/src/sgml/targets-meson.txt | 1 + 2 files changed, 3 insertions(+) diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build index e418de83a7..3eb0b99462 100644 --- a/doc/src/sgml/meson.build +++ b/doc/src/sgml/meson.build @@ -112,6 +112,8 @@ postgres_full_xml = custom_target('postgres-full.xml', docs += postgres_full_xml alldocs += postgres_full_xml +# Shortcut to the above for checking doc syntax +alias_target('check-docs', postgres_full_xml) if xsltproc_bin.found() xsltproc_flags = [ diff --git a/doc/src/sgml/targets-meson.txt b/doc/src/sgml/targets-meson.txt index bd470c87a7..ba426707be 100644 --- a/doc/src/sgml/targets-meson.txt +++ b/doc/src/sgml/targets-meson.txt @@ -26,6 +26,7 @@ Documentation Targets: 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 + check-docs Check the syntax of the documentation Installation Targets: install Install postgres, excluding documentation -- 2.39.2