scripts: image_customization_lib: add include() function

Add a simple way to include image customization Lua snippets.
Can be used to split long files, to include the same options multiple
times in different conditional branches, or even to pass values back to
the including file using return.

Relative paths are interpreted relative to the site root (where
image-customization.lua is located). Relative includes would become
confusing when subdirectories are involved (as they are still interpreted
relative to the site root, and proper tracking of current directory for
each include seems fairly complex for a very niche use case), so we simply
reject this case for now; this way, we can implement this however we
want in the future if deemed necessary, without a breaking change.

Author: neocturne

docs/user/site.rst

@@ -788,6 +788,39 @@ disable_factory()
       disable_factory()
     end
 
+include(path)
+  Includes another image customization file. Relative paths are interpreted relative to the site
+  repository root.
+
+  .. code-block:: lua
+    :caption: target-settings.lua
+
+    features {'wireless-encryption-wpa3'}
+
+  .. code-block:: lua
+    :caption: image-customization.lua
+
+    if target('x86', '64') then
+      include 'target-settings.lua'
+    end
+
+  Values returned from the included file become the return value of ``include``:
+
+  .. code-block:: lua
+    :caption: matches-device.lua
+
+    return device {
+      'openmesh-a40',
+      'openmesh-a60',
+    }
+
+  .. code-block:: lua
+    :caption: image-customization.lua
+
+    if include('matches-device.lua') then
+      packages {'iperf3'}
+    end
+
 Technically, the image customization file is evaluated once for each device, allowing
 to make use of regular Lua *if* statements for device-specific configuration as
 can be seen in the examples.

scripts/image_customization_lib.lua

@@ -99,6 +99,22 @@ local function evaluate_device(env, dev)
 		return dev.options.class == class
 	end
 
+	function funcs.include(path)
+		assert(
+			type(path) == 'string',
+			'incorrect use of include(): path expected as first argument')
+
+		if string.sub(path, 1, 1) ~= '/' then
+			assert(
+				string.find(path, '/') == nil,
+				'incorrect use of include(): including files from subdirectories is unsupported')
+			path = env.GLUON_SITEDIR .. '/' .. path
+		end
+		local f = assert(loadfile(path))
+		setfenv(f, funcs)
+		return f()
+	end
+
 	-- Evaluate the feature definition files
 	setfenv(M.customization_file, funcs)
 	M.customization_file()