Is there an undocumented Syntax Check in Meson?

"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

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