Build a WSL Container Image¶
KIWI NG is capable of building WSL images using the appx utility. Make sure you have installed a package that provides this command on your build host.
Once the build host has the appx installed, the
following image type setup is required in the XML description
<type image="appx" metadata_path="/meta/data"/>
/meta/data path specifies a path that provides
additional information required for the WSL-DistroLauncher.
This component consists out of a Windows(
exe) executable file and
AppxManifest.xml file which references other files
like icons and resource configurations for the startup of the
container under Windows.
Except for the root filesystem tarball KIWI NG is not responsible for providing the meta data 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 installed on the build host
Setup of the WSL-DistroLauncher¶
The contents of the
AppxManifest.xml will be changed by KIWI NG
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 not provided the existing
AppxManifest.xml stays untouched.
Provides the name of a publisher organisation. An appx container needs to be signed off with a digital signature. If the image is build in the Open Build Service (OBS) this happens automatically. Outside of OBS one needs to make sure the given publisher organisation name matches the certificate used for signing.
Provides the name of the author and maintainer of this container
Provides an ID name for the container. The name must start with a letter and only allows alphanumeric characters. KIWI NG will not validate the given name string because there is no common criteria between the container architectures. KIWI NG just accepts any text.
Provides the version identification for the container. KIWI NG validates this against the Microsoft Package Version Numbering rules.
Provides the binary file name of the launcher
There is no validation by KIWI NG if the contents of
are valid or complete to run the container. Users will find out at
call time, not before
The following example shows how to build a WSL image based on openSUSE TW:
Make sure you have checked out the example image descriptions, see Example Appliance Descriptions.
Virtualization/WSLrepository to your list:
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/WSL/<DIST> WSL
where the placeholder
<DIST>is the preferred distribution.
Install fb-util-for-appx utility and a package that provides the WSL-DistroLauncher metadata. See the above note about
$ zypper in fb-util-for-appx DISTRO_APPX_METADATA_PACKAGE
If you are building in the Open Build Service make sure to add the packages from the zypper call above to your project config via osc meta -e prjconf and a line of the form
support: PACKAGE_NAMEfor each package that needs to be installed on the Open Build Service worker that runs the KIWI NG build process.
Setup the image type:
Edit the XML description file:
kiwi/build-tests/x86/tumbleweed/test-image-wsl/appliance.kiwiand add the following type and containerconfig:
<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>
If the configured metadata path does not exist the build will fail. Furthermore there is no validation by KIWI NG that the contents of the metadata path are valid or complete with respect 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 http://download.opensuse.org/tumbleweed/repo/oss \ --target-dir /tmp/myimage
Testing the WSL image¶
For testing the image a Windows 10 system is required. As a first step
the optional feature named
must be enabled. For further details on how to setup the Windows machine
see the following documentation:
Windows Subsystem for Linux