{"thread":{"id":"64127","subject":"[PATCH 0/3] ci: don't compile whole project when testing docs with Meson","startedAt":"2025-09-11T09:16:19Z","lastAt":"2025-09-16T16:24:44Z","messageCount":14,"participants":["Patrick Steinhardt","Junio C Hamano","Karthik Nayak"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"526113","messageId":"20250911-b4-pks-meson-docs-target-v1-0-a92c666ecef9@pks.im","threadId":"64127","inReplyTo":null,"subject":"[PATCH 0/3] ci: don't compile whole project when testing docs with Meson","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-11T09:16:05Z","receivedAt":"2025-09-11T09:16:19Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Hi,\n\nthese two patches introduce a new \"docs\" alias into Meson and use it in\nour \"documentation\" CI jobs so that we stop compiling all of Git only to\nverify the generated manpages. This fixes the issue reported by Gábor in\n[1].\n\nThanks!\n\nPatrick\n\n[1]: <aLCf0UaTxy5Nxpv/@szeder.dev>\n\n---\nPatrick Steinhardt (3):\n      meson: introduce a \"docs\" alias to compile documentation only\n      meson: print docs backend as part of the summary\n      ci: don't compile whole project when testing docs with Meson\n\n Documentation/howto/meson.build     |  4 ++--\n Documentation/meson.build           |  8 ++++----\n Documentation/technical/meson.build |  4 ++--\n ci/test-documentation.sh            |  4 ++--\n contrib/contacts/meson.build        |  4 ++--\n contrib/subtree/meson.build         |  4 ++--\n meson.build                         | 10 ++++++++++\n 7 files changed, 24 insertions(+), 14 deletions(-)\n\n\n---\nbase-commit: ab427cd991100e94792fce124b0934135abdea4b\nchange-id: 20250911-b4-pks-meson-docs-target-56d8a21e84bf\n\n"},{"id":"526114","messageId":"20250911-b4-pks-meson-docs-target-v1-1-a92c666ecef9@pks.im","threadId":"64127","inReplyTo":"20250911-b4-pks-meson-docs-target-v1-0-a92c666ecef9@pks.im","subject":"[PATCH 1/3] meson: introduce a \"docs\" alias to compile documentation only","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-11T09:16:06Z","receivedAt":"2025-09-11T09:16:21Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Meson does not currently provide a target to compile documentation,\nonly. Instead, users needs to compile the whole project, which may be\nway more than they really intend to do.\n\nIntroduce a new \"docs\" alias to plug this gap. This alias can be invoked\ne.g. with `meson compile docs`.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n Documentation/howto/meson.build     | 4 ++--\n Documentation/meson.build           | 8 ++++----\n Documentation/technical/meson.build | 4 ++--\n contrib/contacts/meson.build        | 4 ++--\n contrib/subtree/meson.build         | 4 ++--\n meson.build                         | 7 +++++++\n 6 files changed, 19 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/howto/meson.build b/Documentation/howto/meson.build\nindex 81000028c0..ece20244af 100644\n--- a/Documentation/howto/meson.build\n+++ b/Documentation/howto/meson.build\n@@ -29,7 +29,7 @@ howto_index = custom_target(\n   output: 'howto-index.adoc',\n )\n \n-custom_target(\n+doc_targets += custom_target(\n   command: asciidoc_html_options,\n   input: howto_index,\n   output: 'howto-index.html',\n@@ -51,7 +51,7 @@ foreach howto : howto_sources\n     capture: true,\n   )\n \n-  custom_target(\n+  doc_targets += custom_target(\n     command: asciidoc_html_options,\n     input: howto_stripped,\n     output: fs.stem(howto_stripped.full_path()) + '.html',\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex e34965c5b0..44f94cdb7b 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -377,7 +377,7 @@ foreach manpage, category : manpages\n       output: fs.stem(manpage) + '.xml',\n     )\n \n-    custom_target(\n+    doc_targets += custom_target(\n       command: [\n         xmlto,\n         '-m', '@INPUT0@',\n@@ -400,7 +400,7 @@ foreach manpage, category : manpages\n   endif\n \n   if get_option('docs').contains('html')\n-    custom_target(\n+    doc_targets += custom_target(\n       command: asciidoc_common_options + [\n         '--backend=' + asciidoc_html,\n         '--doctype=manpage',\n@@ -452,7 +452,7 @@ if get_option('docs').contains('html')\n     depends: documentation_deps,\n   )\n \n-  custom_target(\n+  doc_targets += custom_target(\n     command: [\n       xsltproc,\n       '--xinclude',\n@@ -481,7 +481,7 @@ if get_option('docs').contains('html')\n   ]\n \n   foreach article : articles\n-    custom_target(\n+    doc_targets += custom_target(\n       command: asciidoc_common_options + [\n         '--backend=' + asciidoc_html,\n         '--out-file=@OUTPUT@',\ndiff --git a/Documentation/technical/meson.build b/Documentation/technical/meson.build\nindex a13aafcfbb..858af811a7 100644\n--- a/Documentation/technical/meson.build\n+++ b/Documentation/technical/meson.build\n@@ -46,7 +46,7 @@ api_index = custom_target(\n   output: 'api-index.adoc',\n )\n \n-custom_target(\n+doc_targets += custom_target(\n   command: asciidoc_html_options,\n   input: api_index,\n   output: 'api-index.html',\n@@ -56,7 +56,7 @@ custom_target(\n )\n \n foreach article : api_docs + articles\n-  custom_target(\n+  doc_targets += custom_target(\n     command: asciidoc_html_options,\n     input: article,\n     output: fs.stem(article) + '.html',\ndiff --git a/contrib/contacts/meson.build b/contrib/contacts/meson.build\nindex 73d82dfe52..c8fdb35ed9 100644\n--- a/contrib/contacts/meson.build\n+++ b/contrib/contacts/meson.build\n@@ -20,7 +20,7 @@ if get_option('docs').contains('man')\n     output: 'git-contacts.xml',\n   )\n \n-  custom_target(\n+  doc_targets += custom_target(\n     command: [\n       xmlto,\n       '-m', '@INPUT@',\n@@ -39,7 +39,7 @@ if get_option('docs').contains('man')\n endif\n \n if get_option('docs').contains('html')\n-  custom_target(\n+  doc_targets += custom_target(\n     command: asciidoc_common_options + [\n       '--backend=' + asciidoc_html,\n       '--doctype=manpage',\ndiff --git a/contrib/subtree/meson.build b/contrib/subtree/meson.build\nindex 98dd8e0c8e..46cdbcc30c 100644\n--- a/contrib/subtree/meson.build\n+++ b/contrib/subtree/meson.build\n@@ -38,7 +38,7 @@ if get_option('docs').contains('man')\n     output: 'git-subtree.xml',\n   )\n \n-  custom_target(\n+  doc_targets += custom_target(\n     command: [\n       xmlto,\n       '-m', '@INPUT@',\n@@ -57,7 +57,7 @@ if get_option('docs').contains('man')\n endif\n \n if get_option('docs').contains('html')\n-  custom_target(\n+  doc_targets += custom_target(\n     command: asciidoc_common_options + [\n       '--backend=' + asciidoc_html,\n       '--doctype=manpage',\ndiff --git a/meson.build b/meson.build\nindex b3dfcc0497..40b2a2dc54 100644\n--- a/meson.build\n+++ b/meson.build\n@@ -2101,11 +2101,18 @@ endif\n \n subdir('bin-wrappers')\n if get_option('docs') != []\n+  doc_targets = []\n   subdir('Documentation')\n endif\n \n subdir('contrib')\n \n+# Note that the target is intentionally configured after including the\n+# 'contrib' directory, as some tool there also have their own manpages.\n+if get_option('docs') != []\n+  alias_target('docs', doc_targets)\n+endif\n+\n exclude_from_check_headers = [\n   'compat/',\n   'unicode-width.h',\n\n-- \n2.51.0.450.g87641ccf93.dirty\n\n"},{"id":"526115","messageId":"20250911-b4-pks-meson-docs-target-v1-2-a92c666ecef9@pks.im","threadId":"64127","inReplyTo":"20250911-b4-pks-meson-docs-target-v1-0-a92c666ecef9@pks.im","subject":"[PATCH 2/3] meson: print docs backend as part of the summary","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-11T09:16:07Z","receivedAt":"2025-09-11T09:16:24Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Our documentation can be built with either Asciidoc or Asciidoctor as\nbackend. When Meson is configured to build documentation, then it will\nautomatically detect which of these tools is available and use them.\nIt's not obvious to the user though which of these backends is used\nunless the user explicitly asks for one backend via `-Ddocs_backend=`.\n\nImprove the status quo by printing the docs backend as part of the\n\"backends\" summary.\n\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n meson.build | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/meson.build b/meson.build\nindex 40b2a2dc54..4a504fc26d 100644\n--- a/meson.build\n+++ b/meson.build\n@@ -2103,6 +2103,8 @@ subdir('bin-wrappers')\n if get_option('docs') != []\n   doc_targets = []\n   subdir('Documentation')\n+else\n+  docs_backend = 'none'\n endif\n \n subdir('contrib')\n@@ -2251,6 +2253,7 @@ summary({\n \n summary({\n   'csprng': csprng_backend,\n+  'docs': docs_backend,\n   'https': https_backend,\n   'sha1': sha1_backend,\n   'sha1_unsafe': sha1_unsafe_backend,\n\n-- \n2.51.0.450.g87641ccf93.dirty\n\n"},{"id":"526116","messageId":"20250911-b4-pks-meson-docs-target-v1-3-a92c666ecef9@pks.im","threadId":"64127","inReplyTo":"20250911-b4-pks-meson-docs-target-v1-0-a92c666ecef9@pks.im","subject":"[PATCH 3/3] ci: don't compile whole project when testing docs with Meson","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-11T09:16:08Z","receivedAt":"2025-09-11T09:16:27Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Our \"documentation\" CI jobs, unsurprisingly, performs a couple of tests\non our documentation. The job knows to not only test the documentation\ngenerated by our Makefile, but also by Meson.\n\nIn the latter case with Meson we end up building the whole project,\nincluding all of the binaries. This is of course quite excessive and a\nwaste of compute cycles, as we don't care about these binaries at all.\n\nFix this by using the new \"docs\" target that we introduced in the\npreceding commit.\n\nReported-by: SZEDER Gábor <szeder.dev@gmail.com>\nSigned-off-by: Patrick Steinhardt <ps@pks.im>\n---\n ci/test-documentation.sh | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nindex 49f87f50fd..5e4fd8fbd7 100755\n--- a/ci/test-documentation.sh\n+++ b/ci/test-documentation.sh\n@@ -48,13 +48,13 @@ check_unignored_build_artifacts\n \n # Build docs with Meson and AsciiDoc\n meson setup build-asciidoc -Ddocs=html,man -Ddocs_backend=asciidoc\n-meson compile -C build-asciidoc\n+meson compile -C build-asciidoc docs\n check_docs build-asciidoc AsciiDoc\n rm -rf build-asciidoc\n \n # Build docs with Meson and AsciiDoctor\n meson setup build-asciidoctor -Ddocs=html,man -Ddocs_backend=asciidoctor\n-meson compile -C build-asciidoctor\n+meson compile -C build-asciidoctor docs\n check_docs build-asciidoctor Asciidoctor\n rm -rf build-asciidoctor\n \n\n-- \n2.51.0.450.g87641ccf93.dirty\n\n"},{"id":"526142","messageId":"xmqqwm64orc1.fsf@gitster.g","threadId":"64127","inReplyTo":"20250911-b4-pks-meson-docs-target-v1-0-a92c666ecef9@pks.im","subject":"Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-11T17:02:22Z","receivedAt":"2025-09-11T17:02:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> these two patches introduce a new \"docs\" alias into Meson and use it in\n> our \"documentation\" CI jobs so that we stop compiling all of Git only to\n> verify the generated manpages. This fixes the issue reported by Gábor in\n> [1].\n\nThere are three patches ;-).\n\nThe end-user facing get_option() is called \"docs\", unlike what the\n\"make\" side understands, which is \"make doc\", even though internally\nwe call the target internally as \"doc_targets\" (not \"docs_target\").\n\nI wonder if we want to let people say \"meson compile doc\" to match\nthe other world?\n\nWill queue.  Thanks.\n\n>\n> Thanks!\n>\n> Patrick\n>\n> [1]: <aLCf0UaTxy5Nxpv/@szeder.dev>\n>\n> ---\n> Patrick Steinhardt (3):\n>       meson: introduce a \"docs\" alias to compile documentation only\n>       meson: print docs backend as part of the summary\n>       ci: don't compile whole project when testing docs with Meson\n>\n>  Documentation/howto/meson.build     |  4 ++--\n>  Documentation/meson.build           |  8 ++++----\n>  Documentation/technical/meson.build |  4 ++--\n>  ci/test-documentation.sh            |  4 ++--\n>  contrib/contacts/meson.build        |  4 ++--\n>  contrib/subtree/meson.build         |  4 ++--\n>  meson.build                         | 10 ++++++++++\n>  7 files changed, 24 insertions(+), 14 deletions(-)\n>\n>\n> ---\n> base-commit: ab427cd991100e94792fce124b0934135abdea4b\n> change-id: 20250911-b4-pks-meson-docs-target-56d8a21e84bf\n"},{"id":"526298","messageId":"aMeshpRtFWyE0ja4@pks.im","threadId":"64127","inReplyTo":"xmqqwm64orc1.fsf@gitster.g","subject":"Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-15T06:04:54Z","receivedAt":"2025-09-15T06:05:01Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, Sep 11, 2025 at 10:02:22AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> \n> > these two patches introduce a new \"docs\" alias into Meson and use it in\n> > our \"documentation\" CI jobs so that we stop compiling all of Git only to\n> > verify the generated manpages. This fixes the issue reported by Gábor in\n> > [1].\n> \n> There are three patches ;-).\n\nOops, yeah. I added the summary patch close before sending this out :)\n\n> The end-user facing get_option() is called \"docs\", unlike what the\n> \"make\" side understands, which is \"make doc\", even though internally\n> we call the target internally as \"doc_targets\" (not \"docs_target\").\n> \n> I wonder if we want to let people say \"meson compile doc\" to match\n> the other world?\n> \n> Will queue.  Thanks.\n\nThe reason why I picked 'docs' is that the accompanying user-facing\noption is also named the same way. It's thus a bit more consistent with\nitself to call the target 'docs' as well.\n\nSo I slightly lean towards keeping 'docs', but I don't feel too strongly\nabout it.\n\nPatrick\n"},{"id":"526402","messageId":"xmqqcy7re2df.fsf@gitster.g","threadId":"64127","inReplyTo":"aMeshpRtFWyE0ja4@pks.im","subject":"Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-15T23:13:00Z","receivedAt":"2025-09-15T23:13:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n>> I wonder if we want to let people say \"meson compile doc\" to match\n>> the other world?\n>> \n>> Will queue.  Thanks.\n>\n> The reason why I picked 'docs' is that the accompanying user-facing\n> option is also named the same way. It's thus a bit more consistent with\n> itself to call the target 'docs' as well.\n\nSorry, but I am not sure what user-facing \"docs\" option you are\nreferring to; is this some earlier mistake we made that is way too\nentrenched to fix?  I do know about the \"make docs\" that barfs with\n\"*** No rule to make target 'docs'.  Stop.\", and I would call it\nuser-facing.  I would say it is a bit too old to \"correct\" without\ndisrupting existing users.\n\nThanks.\n\n"},{"id":"526421","messageId":"aMkGluKUBfq6VNOQ@pks.im","threadId":"64127","inReplyTo":"xmqqcy7re2df.fsf@gitster.g","subject":"Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-16T06:41:26Z","receivedAt":"2025-09-16T06:41:33Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Sep 15, 2025 at 04:13:00PM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> \n> >> I wonder if we want to let people say \"meson compile doc\" to match\n> >> the other world?\n> >> \n> >> Will queue.  Thanks.\n> >\n> > The reason why I picked 'docs' is that the accompanying user-facing\n> > option is also named the same way. It's thus a bit more consistent with\n> > itself to call the target 'docs' as well.\n> \n> Sorry, but I am not sure what user-facing \"docs\" option you are\n> referring to; is this some earlier mistake we made that is way too\n> entrenched to fix?  I do know about the \"make docs\" that barfs with\n> \"*** No rule to make target 'docs'.  Stop.\", and I would call it\n> user-facing.  I would say it is a bit too old to \"correct\" without\n> disrupting existing users.\n\nI meant the Meson option `-Ddocs=man,html`. I feel it's more natural\nthere if the accompanying target is also called \"docs\" there.\n\nAnother option is that we could also just have both. In that case users\nof the Makefile could continue to use the \"doc\" target with Meson, as\nthey are used to. And users that are used to Meson can use the \"docs\"\ntarget.\n\nPatrick\n"},{"id":"526433","messageId":"CAOLa=ZRVaBp6DAM4gYXFjCRORYxObvWn5egrPAOcGZ42mxnsgg@mail.gmail.com","threadId":"64127","inReplyTo":"20250911-b4-pks-meson-docs-target-v1-1-a92c666ecef9@pks.im","subject":"Re: [PATCH 1/3] meson: introduce a \"docs\" alias to compile documentation only","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-09-16T09:14:56Z","receivedAt":"2025-09-16T09:14:59Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> Meson does not currently provide a target to compile documentation,\n> only. Instead, users needs to compile the whole project, which may be\n> way more than they really intend to do.\n>\n> Introduce a new \"docs\" alias to plug this gap. This alias can be invoked\n> e.g. with `meson compile docs`.\n>\n\nSo earlier we would compile the documentation always (while the\ndependencies are met). Now we move this to a \"docs\" subcommand...\n\n[snip]\n\n> diff --git a/meson.build b/meson.build\n> index b3dfcc0497..40b2a2dc54 100644\n> --- a/meson.build\n> +++ b/meson.build\n> @@ -2101,11 +2101,18 @@ endif\n>\n>  subdir('bin-wrappers')\n>  if get_option('docs') != []\n> +  doc_targets = []\n>    subdir('Documentation')\n>  endif\n>\n>  subdir('contrib')\n>\n> +# Note that the target is intentionally configured after including the\n> +# 'contrib' directory, as some tool there also have their own manpages.\n> +if get_option('docs') != []\n> +  alias_target('docs', doc_targets)\n> +endif\n> +\n\nShouldn't we also add it to 'meson_options.txt' with default set to\ntrue? That would ensure that `meson compile` would also build the docs.\n\n>  exclude_from_check_headers = [\n>    'compat/',\n>    'unicode-width.h',\n>\n> --\n> 2.51.0.450.g87641ccf93.dirty\n"},{"id":"526434","messageId":"CAOLa=ZSXXk9iwnU6a9BR-jfhs0XU8MXQqa8edpOajfORV2uY5w@mail.gmail.com","threadId":"64127","inReplyTo":"20250911-b4-pks-meson-docs-target-v1-3-a92c666ecef9@pks.im","subject":"Re: [PATCH 3/3] ci: don't compile whole project when testing docs with Meson","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-09-16T09:16:53Z","receivedAt":"2025-09-16T09:16:55Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> Our \"documentation\" CI jobs, unsurprisingly, performs a couple of tests\n> on our documentation. The job knows to not only test the documentation\n> generated by our Makefile, but also by Meson.\n>\n> In the latter case with Meson we end up building the whole project,\n> including all of the binaries. This is of course quite excessive and a\n> waste of compute cycles, as we don't care about these binaries at all.\n>\n> Fix this by using the new \"docs\" target that we introduced in the\n> preceding commit.\n>\n> Reported-by: SZEDER Gábor <szeder.dev@gmail.com>\n> Signed-off-by: Patrick Steinhardt <ps@pks.im>\n> ---\n>  ci/test-documentation.sh | 4 ++--\n>  1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\n> index 49f87f50fd..5e4fd8fbd7 100755\n> --- a/ci/test-documentation.sh\n> +++ b/ci/test-documentation.sh\n> @@ -48,13 +48,13 @@ check_unignored_build_artifacts\n>\n>  # Build docs with Meson and AsciiDoc\n>  meson setup build-asciidoc -Ddocs=html,man -Ddocs_backend=asciidoc\n> -meson compile -C build-asciidoc\n> +meson compile -C build-asciidoc docs\n>  check_docs build-asciidoc AsciiDoc\n>  rm -rf build-asciidoc\n>\n>  # Build docs with Meson and AsciiDoctor\n>  meson setup build-asciidoctor -Ddocs=html,man -Ddocs_backend=asciidoctor\n> -meson compile -C build-asciidoctor\n> +meson compile -C build-asciidoctor docs\n>  check_docs build-asciidoctor Asciidoctor\n>  rm -rf build-asciidoctor\n>\n>\n\nThis makes sense. I really like how a lot of our CI config is forge\nagnostic. I opened the patch expecting to review GitHub/GitLab changes.\nGlad I didn't have to.\n\n> --\n> 2.51.0.450.g87641ccf93.dirty\n"},{"id":"526435","messageId":"CAOLa=ZRXdnMbkxVTPa=8NVNBpshQsyNP3HRb_5u51StBu5R8Xg@mail.gmail.com","threadId":"64127","inReplyTo":"20250911-b4-pks-meson-docs-target-v1-0-a92c666ecef9@pks.im","subject":"Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-09-16T09:17:42Z","receivedAt":"2025-09-16T09:17:44Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> Hi,\n>\n> these two patches introduce a new \"docs\" alias into Meson and use it in\n> our \"documentation\" CI jobs so that we stop compiling all of Git only to\n> verify the generated manpages. This fixes the issue reported by Gábor in\n> [1].\n>\n\nOne small question from my side on the first patch, regarding the build\noptions. Looks good otherwise.\n\n[snip]\n"},{"id":"526439","messageId":"aMk0CdaN8pzEPf7m@pks.im","threadId":"64127","inReplyTo":"CAOLa=ZRVaBp6DAM4gYXFjCRORYxObvWn5egrPAOcGZ42mxnsgg@mail.gmail.com","subject":"Re: [PATCH 1/3] meson: introduce a \"docs\" alias to compile documentation only","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-09-16T09:55:21Z","receivedAt":"2025-09-16T09:55:28Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Sep 16, 2025 at 04:14:56AM -0500, Karthik Nayak wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> > diff --git a/meson.build b/meson.build\n> > index b3dfcc0497..40b2a2dc54 100644\n> > --- a/meson.build\n> > +++ b/meson.build\n> > @@ -2101,11 +2101,18 @@ endif\n> >\n> >  subdir('bin-wrappers')\n> >  if get_option('docs') != []\n> > +  doc_targets = []\n> >    subdir('Documentation')\n> >  endif\n> >\n> >  subdir('contrib')\n> >\n> > +# Note that the target is intentionally configured after including the\n> > +# 'contrib' directory, as some tool there also have their own manpages.\n> > +if get_option('docs') != []\n> > +  alias_target('docs', doc_targets)\n> > +endif\n> > +\n> \n> Shouldn't we also add it to 'meson_options.txt' with default set to\n> true? That would ensure that `meson compile` would also build the docs.\n\nWe already have the \"docs\" option in \"meson_options.txt\". In fact, it is\nnot even possible to have an option that is _not_ declared in that file\n:)\n\nThe option accepts an array of choices, where the choices can be \"man\"\nor \"html\" to build manpages, HTML sites, both or none. So as soon as the\nuser made at least one choice we enable the \"docs\" target automatically.\n\nPatrick\n"},{"id":"526443","messageId":"CAOLa=ZSvra91ca_-rgNq1UoNQg6-n1nF4F7NgjuAc-mpNBTS4A@mail.gmail.com","threadId":"64127","inReplyTo":"aMk0CdaN8pzEPf7m@pks.im","subject":"Re: [PATCH 1/3] meson: introduce a \"docs\" alias to compile documentation only","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-09-16T11:50:31Z","receivedAt":"2025-09-16T11:50:33Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> On Tue, Sep 16, 2025 at 04:14:56AM -0500, Karthik Nayak wrote:\n>> Patrick Steinhardt <ps@pks.im> writes:\n>> > diff --git a/meson.build b/meson.build\n>> > index b3dfcc0497..40b2a2dc54 100644\n>> > --- a/meson.build\n>> > +++ b/meson.build\n>> > @@ -2101,11 +2101,18 @@ endif\n>> >\n>> >  subdir('bin-wrappers')\n>> >  if get_option('docs') != []\n>> > +  doc_targets = []\n>> >    subdir('Documentation')\n>> >  endif\n>> >\n>> >  subdir('contrib')\n>> >\n>> > +# Note that the target is intentionally configured after including the\n>> > +# 'contrib' directory, as some tool there also have their own manpages.\n>> > +if get_option('docs') != []\n>> > +  alias_target('docs', doc_targets)\n>> > +endif\n>> > +\n>>\n>> Shouldn't we also add it to 'meson_options.txt' with default set to\n>> true? That would ensure that `meson compile` would also build the docs.\n>\n> We already have the \"docs\" option in \"meson_options.txt\". In fact, it is\n> not even possible to have an option that is _not_ declared in that file\n> :)\n>\n\nNice. I should've verified, I was merely looking at the diff-stat\n\n> The option accepts an array of choices, where the choices can be \"man\"\n> or \"html\" to build manpages, HTML sites, both or none. So as soon as the\n> user made at least one choice we enable the \"docs\" target automatically.\n>\n\nOkay that makes sense! The default is set to '[]'. Okay looks good.\nThanks for clarifying.\n\n> Patrick\n"},{"id":"526453","messageId":"xmqqqzw6nz5i.fsf@gitster.g","threadId":"64127","inReplyTo":"aMkGluKUBfq6VNOQ@pks.im","subject":"Re: [PATCH 0/3] ci: don't compile whole project when testing docs with Meson","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-16T16:24:41Z","receivedAt":"2025-09-16T16:24:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> I meant the Meson option `-Ddocs=man,html`. I feel it's more natural\n> there if the accompanying target is also called \"docs\" there.\n\nAhh.  OK, so if I said \"meson -Ddocs=\" to choose neither format,\nthat would essentially be the same as \"do build the binaries but not\nthe docs\"?\n\nI guess that is from the very beginning 904339ed (Introduce support\nfor the Meson build system, 2024-12-06) that get_option('docs') is\npart of the build system, so it *is* way too late to fix it now.\n\n> Another option is that we could also just have both. In that case users\n> of the Makefile could continue to use the \"doc\" target with Meson, as\n> they are used to. And users that are used to Meson can use the \"docs\"\n> target.\n\nMeaning you'd allow one to be an alias for the other?  I am not sure\nif it is worth it for something small like this.  Let's leave things\nas they are.\n\nThanks.\n"}]}