Re: Is there an undocumented Syntax Check in Meson?

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