[PATCH v5 2/2] meta: Generate WSL image for Windows Subsystem for Linux

["'Clara Kowalsky' via isar-users" <isar-users@googlegroups.com>]

This allows to generate a `.wsl` file for Windows Subsystem for Linux,
based on the tar image type. WSL uses the Windows-provided kernel, so
make sure that other layers like isar-cip-core do not set the
KERNEL_NAME for this machine.

The wsl-config recipe ships the configuration files /etc/wsl.conf and
/etc/wsl-distribution.conf as templates.
See https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro#create-wsl-configuration-files

The variables in the configuration files can be overwritten in
downstream layers:
- WSL_DEFAULT_USER specifies which user runs when the WSL distro is
  launched. Default: "root"
- WSL_DEFAULT_UID specifies the default UID used during first-run/OOBE
  installation. Default: "0"
- WSL_DEFAULT_NAME specifies the name that the distro is registered
  under. Default: "${DISTRO}-${MACHINE}"
Whole configuration files can be replaced or added by bbappending the
wsl-config recipe.

This was tested with WSL2, in plain Isar and in downstream layer.

Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
---
 doc/user_manual.md                            |  1 +
 kas/machine/Kconfig                           |  8 ++++
 kas/machine/wsl.yaml                          |  7 +++
 meta-isar/conf/local.conf.sample              |  3 +-
 meta-isar/conf/machine/wsl.conf               | 13 ++++++
 meta-isar/conf/mc.conf                        |  2 +
 meta-isar/conf/multiconfig/wsl-bookworm.conf  |  7 +++
 meta-isar/conf/multiconfig/wsl-trixie.conf    |  7 +++
 meta/classes-recipe/image.bbclass             |  2 +-
 meta/classes-recipe/imagetypes_wsl.bbclass    | 13 ++++++
 meta/recipes-support/wsl-config/files/oobe.sh |  4 ++
 .../files/wsl-distribution.conf.tmpl          |  6 +++
 .../wsl-config/files/wsl.conf.tmpl            |  5 +++
 .../wsl-config/wsl-config_0.1.bb              | 45 +++++++++++++++++++
 testsuite/citest.py                           | 18 ++++++++
 testsuite/data/targets.yml                    |  4 ++
 16 files changed, 143 insertions(+), 2 deletions(-)
 create mode 100644 kas/machine/wsl.yaml
 create mode 100644 meta-isar/conf/machine/wsl.conf
 create mode 100644 meta-isar/conf/multiconfig/wsl-bookworm.conf
 create mode 100644 meta-isar/conf/multiconfig/wsl-trixie.conf
 create mode 100644 meta/classes-recipe/imagetypes_wsl.bbclass
 create mode 100644 meta/recipes-support/wsl-config/files/oobe.sh
 create mode 100644 meta/recipes-support/wsl-config/files/wsl-distribution.conf.tmpl
 create mode 100644 meta/recipes-support/wsl-config/files/wsl.conf.tmpl
 create mode 100644 meta/recipes-support/wsl-config/wsl-config_0.1.bb

diff --git a/doc/user_manual.md b/doc/user_manual.md
index dcc3f560..f3b1acb9 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -514,6 +514,7 @@ Currently, the following image types are provided:
  - `ubi` - image for use on mtd nand partitions employing UBI
  - `ubifs` - raw UBI filesystem image, normally used together with UBI partitions
  - `ova` - Open Virtual Appliance: image for use on VirtualBox or VMware
+ - `wsl` - tar file for Windows Subsystem for Linux
  - `squashfs` - raw squashfs filesystem image
  - `fit` - FIT image as used by U-Boot
  - `oci-archive`, `docker-archive`, `docker-daemon`, `containers-storage` - see [generating container images](#generate-container-image-with-root-filesystem)
diff --git a/kas/machine/Kconfig b/kas/machine/Kconfig
index 1e360be6..2895368c 100644
--- a/kas/machine/Kconfig
+++ b/kas/machine/Kconfig
@@ -253,6 +253,13 @@ config MACHINE_HYPER_V
 	select CODENAME_TRIXIE
 	select ARCH_AMD64
 
+config MACHINE_WSL
+	bool "wsl"
+	select DISTRO_DEBIAN
+	select CODENAME_BOOKWORM
+	select CODENAME_TRIXIE
+	select ARCH_AMD64
+
 config MACHINE_X86_PC
 	bool "x86 PC"
 	select DISTRO_DEBIAN
@@ -297,6 +304,7 @@ config KAS_INCLUDE_MACHINE
 	default "kas/machine/virtualbox.yaml" if MACHINE_VIRTUALBOX
 	default "kas/machine/vmware.yaml" if MACHINE_VMWARE
 	default "kas/machine/hyper-v-amd64.yaml" if MACHINE_HYPER_V
+	default "kas/machine/wsl.yaml" if MACHINE_WSL
 	default "kas/machine/x86-pc.yaml" if MACHINE_X86_PC
 
 endmenu
diff --git a/kas/machine/wsl.yaml b/kas/machine/wsl.yaml
new file mode 100644
index 00000000..f043b02a
--- /dev/null
+++ b/kas/machine/wsl.yaml
@@ -0,0 +1,7 @@
+# This software is a part of Isar.
+# Copyright (c) Siemens AG, 2026
+
+header:
+  version: 14
+
+machine: wsl
diff --git a/meta-isar/conf/local.conf.sample b/meta-isar/conf/local.conf.sample
index 9b0b3746..6e1e1546 100644
--- a/meta-isar/conf/local.conf.sample
+++ b/meta-isar/conf/local.conf.sample
@@ -155,8 +155,9 @@ CONF_VERSION = "1"
 IMAGE_INSTALL = "hello-isar example-raw example-module-${KERNEL_NAME} enable-fsck isar-exclude-docs samefile hello isar-disable-apt-cache cowsay example-prebuilt"
 
 #
-# Container machines don't need example module and enable-fsck.
+# Container and WSL machines don't need example module and enable-fsck.
 IMAGE_INSTALL:remove:container-amd64 = "example-module-${KERNEL_NAME} enable-fsck"
+IMAGE_INSTALL:remove:wsl = "example-module-${KERNEL_NAME} enable-fsck"
 
 #
 # Machines with secure boot should use signed modules.
diff --git a/meta-isar/conf/machine/wsl.conf b/meta-isar/conf/machine/wsl.conf
new file mode 100644
index 00000000..b1a3b89b
--- /dev/null
+++ b/meta-isar/conf/machine/wsl.conf
@@ -0,0 +1,13 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+DISTRO_ARCH ?= "amd64"
+
+IMAGE_FSTYPES ?= "wsl"
+
+# Configure rootfs for WSL boot
+IMAGE_INSTALL:append = " wsl-config"
+# Enable systemd-user session model
+IMAGE_PREINSTALL:append = " dbus dbus-user-session"
diff --git a/meta-isar/conf/mc.conf b/meta-isar/conf/mc.conf
index 649430a2..df3a38b0 100644
--- a/meta-isar/conf/mc.conf
+++ b/meta-isar/conf/mc.conf
@@ -89,4 +89,6 @@ BBMULTICONFIG = " \
     qemuamd64-sid \
     qemuarm64-sid \
     qemuriscv64-resolute \
+    wsl-bookworm \
+    wsl-trixie \
 "
diff --git a/meta-isar/conf/multiconfig/wsl-bookworm.conf b/meta-isar/conf/multiconfig/wsl-bookworm.conf
new file mode 100644
index 00000000..5e9f3697
--- /dev/null
+++ b/meta-isar/conf/multiconfig/wsl-bookworm.conf
@@ -0,0 +1,7 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+MACHINE ?= "wsl"
+DISTRO ?= "debian-bookworm"
diff --git a/meta-isar/conf/multiconfig/wsl-trixie.conf b/meta-isar/conf/multiconfig/wsl-trixie.conf
new file mode 100644
index 00000000..8ef796e4
--- /dev/null
+++ b/meta-isar/conf/multiconfig/wsl-trixie.conf
@@ -0,0 +1,7 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+MACHINE ?= "wsl"
+DISTRO ?= "debian-trixie"
diff --git a/meta/classes-recipe/image.bbclass b/meta/classes-recipe/image.bbclass
index d02f99da..0329c3f8 100644
--- a/meta/classes-recipe/image.bbclass
+++ b/meta/classes-recipe/image.bbclass
@@ -174,7 +174,7 @@ IMAGE_BASETYPES = "${@get_image_basetypes(d)}"
 
 # image types
 IMAGE_CLASSES ??= ""
-IMGCLASSES = "imagetypes imagetypes_wic imagetypes_vm imagetypes_container squashfs \
+IMGCLASSES = "imagetypes imagetypes_wic imagetypes_vm imagetypes_wsl imagetypes_container squashfs \
                 imagetypes_ddi"
 IMGCLASSES += "${IMAGE_CLASSES}"
 inherit ${IMGCLASSES}
diff --git a/meta/classes-recipe/imagetypes_wsl.bbclass b/meta/classes-recipe/imagetypes_wsl.bbclass
new file mode 100644
index 00000000..e216ef5d
--- /dev/null
+++ b/meta/classes-recipe/imagetypes_wsl.bbclass
@@ -0,0 +1,13 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+# This class allows to generate WSL import artifacts.
+#
+
+IMAGE_TYPEDEP:wsl = "tar"
+
+IMAGE_CMD:wsl() {
+    gzip -f -9 -n -c "${DEPLOY_DIR_IMAGE}/${IMAGE_FULLNAME}.tar" > "${IMAGE_FILE_HOST}"
+}
diff --git a/meta/recipes-support/wsl-config/files/oobe.sh b/meta/recipes-support/wsl-config/files/oobe.sh
new file mode 100644
index 00000000..e9ddfd16
--- /dev/null
+++ b/meta/recipes-support/wsl-config/files/oobe.sh
@@ -0,0 +1,4 @@
+#! /usr/bin/bash
+
+# Generic OOBE hook for Isar-generated WSL images
+exit 0
diff --git a/meta/recipes-support/wsl-config/files/wsl-distribution.conf.tmpl b/meta/recipes-support/wsl-config/files/wsl-distribution.conf.tmpl
new file mode 100644
index 00000000..1b1a7c1b
--- /dev/null
+++ b/meta/recipes-support/wsl-config/files/wsl-distribution.conf.tmpl
@@ -0,0 +1,6 @@
+# See https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro#add-the-wsl-distribution-configuration-file
+
+[oobe]
+command = /usr/libexec/wsl/oobe.sh
+defaultUid = ${WSL_DEFAULT_UID}
+defaultName = ${WSL_DEFAULT_NAME}
diff --git a/meta/recipes-support/wsl-config/files/wsl.conf.tmpl b/meta/recipes-support/wsl-config/files/wsl.conf.tmpl
new file mode 100644
index 00000000..862ca252
--- /dev/null
+++ b/meta/recipes-support/wsl-config/files/wsl.conf.tmpl
@@ -0,0 +1,5 @@
+[boot]
+systemd=true
+
+[user]
+default=${WSL_DEFAULT_USER}
diff --git a/meta/recipes-support/wsl-config/wsl-config_0.1.bb b/meta/recipes-support/wsl-config/wsl-config_0.1.bb
new file mode 100644
index 00000000..c1bf9732
--- /dev/null
+++ b/meta/recipes-support/wsl-config/wsl-config_0.1.bb
@@ -0,0 +1,45 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+inherit dpkg-raw
+
+DESCRIPTION = "WSL configuration files"
+MAINTAINER = "isar-users <isar-users@googlegroups.com>"
+
+PROVIDES := "${BPN}"
+DEBIAN_PROVIDES := "${BPN}"
+PN .= "-${MACHINE}"
+
+WSL_DEFAULT_USER ?= "root"
+WSL_DEFAULT_UID ?= "0"
+WSL_DEFAULT_NAME ?= "${DISTRO}-${MACHINE}"
+
+SRC_URI = " \
+    file://oobe.sh \
+    file://wsl.conf.tmpl \
+    file://wsl-distribution.conf.tmpl \
+    "
+
+TEMPLATE_FILES = " \
+    wsl.conf.tmpl \
+    wsl-distribution.conf.tmpl \
+    "
+
+TEMPLATE_VARS += " \
+    WSL_DEFAULT_USER \
+    WSL_DEFAULT_UID \
+    WSL_DEFAULT_NAME \
+    "
+
+do_install[cleandirs] += " \
+    ${D}/etc \
+    ${D}/usr/libexec/wsl \
+    "
+
+do_install() {
+    install -m 0644 "${WORKDIR}/wsl.conf" "${D}/etc"
+    install -m 0644 "${WORKDIR}/wsl-distribution.conf" "${D}/etc"
+    install -m 0755 "${WORKDIR}/oobe.sh" "${D}/usr/libexec/wsl"
+}
diff --git a/testsuite/citest.py b/testsuite/citest.py
index ca4b7cd8..197ed11a 100644
--- a/testsuite/citest.py
+++ b/testsuite/citest.py
@@ -1352,6 +1352,24 @@ class ContainerImageTest(CIBaseTest):
         self.perform_build_test(targets, container=True)
 
 
+class WSLImageTest(CIBaseTest):
+
+    """
+    Test WSL images creation
+
+    :avocado: tags=wslbuild,full,wsl
+    """
+
+    def test_wsl_image(self):
+        targets = [
+            'mc:wsl-bookworm:isar-image-base',
+            'mc:wsl-trixie:isar-image-base',
+        ]
+
+        self.init()
+        self.perform_build_test(targets, image_install='')
+
+
 class ContainerSdkTest(CIBaseTest):
 
     """
diff --git a/testsuite/data/targets.yml b/testsuite/data/targets.yml
index f27ae2d7..a4474829 100644
--- a/testsuite/data/targets.yml
+++ b/testsuite/data/targets.yml
@@ -161,6 +161,10 @@ a: !mux
     name: qemuarm64-sid
   qemuriscv64-resolute:
     name: qemuriscv64-resolute
+  wsl-bookworm:
+    name: wsl-bookworm
+  wsl-trixie:
+    name: wsl-trixie
 b: !mux
   base:
     image: isar-image-base
-- 
2.54.0

-- 
You received this message because you are subscribed to the Google Groups "isar-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/isar-users/20260817092033.442221-2-clara.kowalsky%40siemens.com.