fix: Add useful debug message when files are missing from config (#15499)

Improve error messages when image config files reference missing files (PackageLists, scripts, AdditionalFiles, etc.).

Previously, if a referenced file was missing, Make would fail with a confusing message about having no rule to build the validation flag. If the missing file was in a non-existent directory, realpath would also print unhelpful errors before the actual failure.

This was caused by Make's pattern rule matching behavior. The validation rules is $(STATUS_FLAGS_DIR)/validate-image-config%.flag:, which matches the variable validate-config = $(STATUS_FLAGS_DIR)/validate-image-config-$(config_name).flag

The rule had config_other_files = $(if $(CONFIG_FILE),$(call shell_real_build_only, $(SCRIPTS_DIR)/get_config_deps.sh $(CONFIG_FILE)),) as a dependency. If one of those calculated files was missing, then make would consider the pattern matched rule un-usable, and would try to find an alternate rule that did have all its dependencies. Unfortunately, we only have one pattern match rule, so we must ensure that all the dependencies we list are either real files, or valid make targets, so make won't skip it.

Author: dmcilvaney

toolkit/scripts/get_config_deps.sh

@@ -44,6 +44,8 @@ do
 	then
 		echo "$filename"
 	else
-		echo $(realpath "$config_base_dir/$filename")
+		# Use -m to canonicalize paths even if they don't exist
+		# This allows the Makefile to detect missing files and provide a helpful error
+		echo $(realpath -m "$config_base_dir/$filename")
 	fi
 done

toolkit/scripts/imggen.mk

@@ -94,6 +94,20 @@ fetch-external-image-packages: $(image_external_package_cache_summary)
 # Validate the selected config file if any changes occur in the image config base directory.
 # Changes to files located outside the base directory will not be detected.
 validate-image-config: $(validate-config)
+
+# Validate that all config dependencies exist before Make tries to process them as prerequisites
+# If we don't do this, Make will error out with a less-than-helpful message about having no rule to make
+# the validation flag (since its a pattern match and if a dependency is missing, it can't match the pattern)
+# Skip this check for printvar targets so users can still debug with the suggested command
+ifneq ($(CONFIG_FILE),)
+  ifeq ($(filter printvar-%,$(MAKECMDGOALS)),)
+    config_missing_files = $(filter-out $(wildcard $(config_other_files)),$(config_other_files))
+    ifneq ($(config_missing_files),)
+      $(error $(newline)$(newline)ERROR: Image configuration '$(CONFIG_FILE)' missing files:$(newline)$(newline)$(foreach file,$(config_missing_files),  - $(file)$(newline))$(newline)Run this command to see all expected files:$(newline)  make printvar-config_other_files CONFIG_FILE=$(CONFIG_FILE) --quiet$(newline))
+    endif
+  endif
+endif
+
 $(STATUS_FLAGS_DIR)/validate-image-config%.flag: $(go-imageconfigvalidator) $(depend_CONFIG_FILE) $(CONFIG_FILE) $(config_other_files)
 	$(if $(CONFIG_FILE),,$(error Must set CONFIG_FILE=))
 	$(go-imageconfigvalidator) \

toolkit/scripts/utils.mk

@@ -15,6 +15,12 @@ build_arch := $(shell uname -m)
 
 no_repo_acl = $(STATUS_FLAGS_DIR)/no_repo_acl.flag
 
+# Define newline for use in error messages and output formatting
+define newline
+
+
+endef
+
 ######## MISC. MAKEFILE Functions ########
 
 # Creates a folder if it doesn't exist. Also sets the timestamp to 0 if it is