Re: Is there an undocumented Syntax Check in Meson?
Andres Freund writes:
> Hi,
>
> On 2024-05-09 20:53:27 +0100, Dagfinn Ilmari Mannsåker wrote:
>> Andres Freund 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?=
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.htmlBuild documentation in single-page HTML format
alldocs Build documentation in all supported formats
+ check-docsCheck the syntax of the documentation
Installation Targets:
install Install postgres, excluding documentation
--
2.39.2
Re: Is there an undocumented Syntax Check in Meson?
On Thu, May 9, 2024 at 1:16 PM Andres Freund 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.
Re: Is there an undocumented Syntax Check in Meson?
Hi,
On 2024-05-09 20:53:27 +0100, Dagfinn Ilmari Mannsåker wrote:
> Andres Freund 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
Re: Is there an undocumented Syntax Check in Meson?
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
Re: Is there an undocumented Syntax Check in Meson?
Andres Freund 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
Re: Is there an undocumented Syntax Check in Meson?
On Thu, May 9, 2024 at 12:12 PM Dagfinn Ilmari Mannsåker wrote: > "David G. Johnston" 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.
Re: Is there an undocumented Syntax Check in Meson?
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
Re: Is there an undocumented Syntax Check in Meson?
"David G. Johnston" 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?=
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.htmlBuild documentation in single-page HTML format
alldocs Build documentation in all supported formats
+ check-docsCheck the syntax of the documentation
Installation Targets:
install Install postgres, excluding documentation
--
2.39.2
Re: Is there an undocumented Syntax Check in Meson?
"David G. Johnston" 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
Re: Is there an undocumented Syntax Check in Meson?
"David G. Johnston" 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
Is there an undocumented Syntax Check in Meson?
$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? David J.
