Re: [PATCH v6] build: regenerate config-list.h when Documentation changes

["SZEDER Gábor" <szeder.dev@gmail.com>]

On Sat, Feb 21, 2026 at 09:07:17AM -0500, D. Ben Knoble wrote:
> The Meson-based build doesn't know when to rebuild config-list.h, so the
> header is sometimes stale.
> 
> For example, an old build directory might have config-list.h from before
> 4173df5187 (submodule: introduce extensions.submodulePathConfig,
> 2026-01-12), which added submodule.<name>.gitdir to the list. Without
> it, t9902-completion.sh fails. Regenerating the config-list.h artifact
> from sources fixes the artifact and the test.
> 
> Since Meson does not have (or want) builtin support for globbing like
> Make, teach generate-configlist.sh to also generate a list of
> Documentation files its output depends on, and incorporate that into the
> Meson build.
> 
> We assume that if a user adds a new file under
> Documentation/config then they will also edit one of the existing files
> to include that new file, and that will trigger a rebuild. Also mark the
> generator script as a dependency.
> 
> While we're at it, teach the Makefile to use the same "the script knows
> it's dependencies" logic.
> 
> For Meson, combining the following commands helps debug dependencies:
> 
>     ninja -C <builddir> -t deps config-list.h
>     ninja -C <builddir> -t browse config-list.h
> 
> The former lists all the dependencies discovered from our output ".d"
> file (the config documentation) and the latter shows the dependency on
> the script itself, among other useful edges in the dependency graph.
> 
> Helped-by: Patrick Steinhardt <ps@pks.im>
> Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
> Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
> ---
> 
> Notes (benknoble/commits):
>     Changes from v5 (<611a94cd988e3795bc63dba2f1b270aa0d058bd2.1771425395.git.ben.knoble+github@gmail.com>):
>     
>     • Reword a confusing sentence in the commit message
> 
>  Makefile               |  5 +++--
>  generate-configlist.sh | 11 ++++++++++-
>  meson.build            |  5 ++++-
>  3 files changed, 17 insertions(+), 4 deletions(-)
> 
> diff --git a/Makefile b/Makefile
> index 7f37ad8f58..6f926ffb1f 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -2688,9 +2688,10 @@ $(BUILT_INS): git$X
>  	cp $< $@
>  
>  config-list.h: generate-configlist.sh
> +	@mkdir -p .depend
> +	$(QUIET_GEN)$(SHELL_PATH) ./generate-configlist.sh . $@ .depend/config-list.h.d
>  
> -config-list.h: Documentation/*config.adoc Documentation/config/*.adoc
> -	$(QUIET_GEN)$(SHELL_PATH) ./generate-configlist.sh . $@
> +-include .depend/config-list.h.d

This breaks the build when something disappears from
Documentation/config/:

  $ git checkout origin/seen
  HEAD is now at 57edfa3ce8 Merge branch 'ty/setup-error-tightening' into seen
  $ ls -l Documentation/config/hook.adoc 
  -rw-rw-r-- 1 szeder szeder 3828 Feb 23 07:50 Documentation/config/hook.adoc
  $ git grep hook.adoc
  Documentation/git-hook.adoc:include::config/hook.adoc[]
  Documentation/howto/meson.build:  'rebuild-from-update-hook.adoc',
  Documentation/meson.build:  'git-hook.adoc' : 1,
  $ make V=1 config-list.h
  /bin/sh ./generate-configlist.sh . config-list.h .depend/config-list.h.d
  $ git checkout 0aabf70f60
  Previous HEAD position was 57edfa3ce8 Merge branch 'ty/setup-error-tightening' into seen
  HEAD is now at 0aabf70f60 build: regenerate config-list.h when Documentation changes
  $ ls -l Documentation/config/hook.adoc 
  ls: cannot access 'Documentation/config/hook.adoc': No such file or directory
  $ git grep hook.adoc
  Documentation/howto/meson.build:  'rebuild-from-update-hook.adoc',
  Documentation/meson.build:  'git-hook.adoc' : 1,
  $ make V=1 config-list.h
  GIT_VERSION=2.53.0.119.g0aabf70f60
  make: *** No rule to make target 'Documentation/config/hook.adoc', needed by 'config-list.h'.  Stop.
  $ grep hook.adoc .depend/config-list.h.d 
  config-list.h: ./Documentation/config/hook.adoc


>  command-list.h: generate-cmdlist.sh command-list.txt
>  
> diff --git a/generate-configlist.sh b/generate-configlist.sh
> index 75c39ade20..39ac8845ab 100755
> --- a/generate-configlist.sh
> +++ b/generate-configlist.sh
> @@ -2,10 +2,11 @@
>  
>  SOURCE_DIR="$1"
>  OUTPUT="$2"
> +DEPFILE="$3"
>  
>  if test -z "$SOURCE_DIR" || ! test -d "$SOURCE_DIR" || test -z "$OUTPUT"
>  then
> -	echo >&2 "USAGE: $0 <SOURCE_DIR> <OUTPUT>"
> +	echo >&2 "USAGE: $0 <SOURCE_DIR> <OUTPUT> [<DEPFILE>]"
>  	exit 1
>  fi
>  
> @@ -36,3 +37,11 @@ print_config_list () {
>  	echo
>  	print_config_list
>  } >"$OUTPUT"
> +
> +if test -n "$DEPFILE"
> +then
> +	QUOTED_OUTPUT="$(printf '%s\n' "$OUTPUT" | sed 's,[&/\],\\&,g')"
> +	printf '%s\n' "$SOURCE_DIR"/Documentation/*config.adoc \
> +		"$SOURCE_DIR"/Documentation/config/*.adoc |
> +		sed -e 's/[# ]/\\&/g' -e "s/^/$QUOTED_OUTPUT: /" >"$DEPFILE"
> +fi
> diff --git a/meson.build b/meson.build
> index 762e2d0fc0..74b459b004 100644
> --- a/meson.build
> +++ b/meson.build
> @@ -720,11 +720,14 @@ endif
>  
>  builtin_sources += custom_target(
>    output: 'config-list.h',
> +  depfile: 'config-list.h.d',
> +  depend_files: [ 'generate-configlist.sh' ],
>    command: [
>      shell,
> -    meson.current_source_dir() + '/generate-configlist.sh',
> +    meson.current_source_dir() / 'generate-configlist.sh',
>      meson.current_source_dir(),
>      '@OUTPUT@',
> +    '@DEPFILE@',
>    ],
>    env: script_environment,
>  )
> 
> Diff-intervalle contre v5 :
> 1:  611a94cd98 ! 1:  5dcd4e9308 build: regenerate config-list.h when Documentation changes
>     @@ Commit message
>          it, t9902-completion.sh fails. Regenerating the config-list.h artifact
>          from sources fixes the artifact and the test.
>      
>     -    Teach the meson build to depend on the Documentation files that
>     -    generate-configlist.sh reads by having it an additional output as a list
>     -    of dependency files, since Meson does not have (or want) builtin support
>     -    for globbing like Make. We assume that if a user adds a new file under
>     +    Since Meson does not have (or want) builtin support for globbing like
>     +    Make, teach generate-configlist.sh to also generate a list of
>     +    Documentation files its output depends on, and incorporate that into the
>     +    Meson build.
>     +
>     +    We assume that if a user adds a new file under
>          Documentation/config then they will also edit one of the existing files
>          to include that new file, and that will trigger a rebuild. Also mark the
>          generator script as a dependency.
>     @@ Commit message
>      
>      
>       ## Notes (benknoble/commits) ##
>     -    Changes from v4 (<9cdcc9de04f0f8fff657f0474b31c063466ed808.1771280837.git.ben.knoble+github@gmail.com>):
>     +    Changes from v5 (<611a94cd988e3795bc63dba2f1b270aa0d058bd2.1771425395.git.ben.knoble+github@gmail.com>):
>      
>     -    • Include Patrick's suggested Makefile changes. Note there's no quiet
>     -      equivalent for mdkir that isn't for the current target's containing
>     -      directory…
>     -    • Make depfile output efficient again, thanks to Phillip.
>     -
>     -    I've kept printf instead of echo (from Patrick/Junio) because I think it
>     -    is easier to reason about ("it works" vs. "did I use this in a way that
>     -    might cause problems").
>     -
>     -    Junio asked about other problematic bytes: the other one I could think
>     -    of (since all the inputs should be paths, anyway) is newlines. I gave
>     -    meson's depfile.py a glance [1], and it looks like they don't handle
>     -    newlines in paths. Other whitespace doesn't appear to be an issue (see
>     -    "elif c in {' ', '\n'}"); I think _most_ characters are just added to
>     -    the filename.
>     -
>     -    [1]: https://github.com/mesonbuild/meson/blob/master/mesonbuild/depfile.py
>     +    • Reword a confusing sentence in the commit message
>      
>       ## Makefile ##
>      @@ Makefile: $(BUILT_INS): git$X
> 
> base-commit: 4a7958ca1415077ce9b1d0a38223ede55da779d9
> -- 
> 2.53.0
>