Build a WSL Container Image

KIWI NG can build WSL images using the appx utility. Make sure you have installed the package that provides the command on your build host.

Once the build host has the appx command installed, the following image type setup is required in the XML description, config.xml:

<type image="appx" metadata_path="/meta/data"/>

The /meta/data path specifies a path that provides additional information required for the WSL-DistroLauncher. This component consists of a Windows (exe) executable file and an AppxManifest.xml file that references other files, like icons and resource configurations for the startup of the container under Windows.

Note

/meta/data

Except for the root filesystem tarball, KIWI NG is not responsible for providing the metadata required for the WSL-DistroLauncher. It is expected that the given metadata path contains all the needed information. Typically, this information is delivered in a package provided by the distribution, and it is installed on the build host.

Setup of the WSL-DistroLauncher

The contents of the AppxManifest.xml are changed by KIWI NG if the containerconfig section is provided in the XML description. In the context of a WSL image, the following container configuration parameters are taken into account:

<containerconfig name="my-wsl-container">
    <history
        created_by="Organisation"
        author="Name"
        application_id="AppIdentification"
        package_version="https://docs.microsoft.com/en-us/windows/uwp/publish/package-version-numbering"
        launcher="WSL-DistroLauncher-exe-file"
    >Container Description Text</history>
</containerconfig>

All information provided here, including the entire section, is optional. If the information is not specified, the existing AppxManifest.xml is left untouched.

created_by: Specifies the name of a publisher organization. An appx container must be signed off with a digital signature. If the image is built in the Open Build Service (OBS), this is done automatically. Outside of OBS, you must make sure that the given publisher organization name matches the certificate used for signing.
author: Provides the name of the author and maintainer of this container.
application_id: Specifies an ID name for the container. The name must start with a letter, and only alphanumeric characters are allowed. KIWI NG does not validate the specified name string because there are no common criteria for the various container architectures.
package_version: Specifies the version identification for the container. KIWI NG validates it against the Microsoft Package Version Numbering rules.
launcher: Specifies the binary file name of the launcher .exe file.

Warning

KIWI NG does not check the configuration in AppxManifest.xml for validity or completeness.

The following example shows how to build a WSL image based on openSUSE Tumbleweed:

Check the example image descriptions; see Example Appliance Descriptions.
Include the Virtualization/WSL repository in the list (replace <DIST> with the desired distribution):
```
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/WSL/<DIST> WSL
```
Install the fb-util-for-appx utility and the package that provides the WSL-DistroLauncher metadata. See the previous note on /meta/data.
```
$ zypper in fb-util-for-appx DISTRO_APPX_METADATA_PACKAGE
```
Note

When building images with the Open Build Service, make sure to add the packages from the zypper command above to the project configuration via osc meta -e prjconf along with the line support: PACKAGE_NAME for each package that needs to be installed on the Open Build Service worker that runs the KIWI NG build process.

Configure the image type:

Add the following type and container configuration to kiwi/build-tests/x86/tumbleweed/test-image-wsl/appliance.kiwi:

<type image="appx" metadata_path="/meta/data">
    <containerconfig name="Tumbleweed">
        <history
            created_by="SUSE"
            author="KIWI-Team"
            application_id="tumbleweed"
            package_version="2003.12.0.0"
            launcher="openSUSE-Tumbleweed.exe"
        >Tumbleweed Appliance text based</history>
    </containerconfig>
</type>

Warning

If the configured metadata path does not exist, the build will fail. Furthermore, KIWI NG does not check whether the metadata is complete or is valid according to the requirements of the WSL-DistroLauncher.

Build the image with KIWI NG:

$ sudo kiwi-ng system build \
    --description kiwi/build-tests/x86/tumbleweed/test-image-wsl \
    --set-repo https://download.opensuse.org/tumbleweed/repo/oss \
    --target-dir /tmp/myimage

Testing the WSL image

For testing the image, you need a Windows 10 system. Before you proceed, enable the optional feature named Microsoft-Windows-Subsystem-Linux. For further details on how to set up the Windows machine, see Windows Subsystem for Linux.