Re: How to use Meson (was: [PATCH 00/10] meson: wire up missing HTML documentation])

[Patrick Steinhardt <ps@pks.im>]

On Fri, Jan 03, 2025 at 08:58:00AM +0100, Toon Claes wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> > Yup, you are always expected to set up the top-level source directory,
> > not any of the subdirectories. The build instructions are then processed
> > linearly in Meson, so variables declared before a call to `subdir()`
> > would be accessible in the subdirectory, as well.
> 
> With Makefiles I can build individual targets (like `make docs`), or run
> `make` in the docs/ subdir, is something like that also possible with
> Meson? Or are you always configuring what to build in `meson configure`
> and building all that with `meson compile`?

You can in theory. It's already possible to build individual parts of
Git, e.g.:

    # We need to discern these two `git` targets because the same name
    # is defined once as a static library and once as an executable.
    $ meson compile git:static_library
    $ meson compile git:executable
    $ meson compile Documentation/git-add.1

We can also have a target equivalent to `make docs` by adding
`alias_target()`s to Meson. I ain't got these wired up yet, but it could
look like the patch at the end of this mail. And then you can simply say
`meson compile docs`. It does require you to have docs configured
though, otherwise the 'Documentation/' subdirectory does not get pulled
included in the first place.

Patrick

diff --git a/Documentation/meson.build b/Documentation/meson.build
index 2a26fa8a5f..4f8e2e7ebb 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -204,6 +204,8 @@ manpages = {
   'gitworkflows.txt' : 7,
 }
 
+docs_target = []
+
 docs_backend = get_option('docs_backend')
 if docs_backend == 'auto'
   if find_program('asciidoc', required: false).found()
@@ -364,10 +366,12 @@ foreach manpage, category : manpages
       install: true,
       install_dir: get_option('mandir') / 'man' + category.to_string(),
     )
+
+    docs_target += manpage_target
   endif
 
   if get_option('docs').contains('html')
-    custom_target(
+    docs_target += custom_target(
       command: asciidoc_common_options + [
         '--backend=' + asciidoc_html,
         '--doctype=manpage',
@@ -419,7 +423,7 @@ if get_option('docs').contains('html')
     depends: documentation_deps,
   )
 
-  custom_target(
+  docs_target += custom_target(
     command: [
       xsltproc,
       '--xinclude',
@@ -447,7 +451,7 @@ if get_option('docs').contains('html')
   ]
 
   foreach article : articles
-    custom_target(
+    docs_target += custom_target(
       command: asciidoc_common_options + [
         '--backend=' + asciidoc_html,
         '--out-file=@OUTPUT@',
@@ -502,3 +506,5 @@ if configured_manpages != actual_manpages
     error('Man page configured, but not found:\n\n - ' + '\n - '.join(superfluous_manpage))
   endif
 endif
+
+alias_target('docs', docs_target)