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
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 out of a Windows(exe
) executable file and
an AppxManifest.xml
file which 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 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
if a 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.
- created_by
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.
- author
Provides the name of the author and maintainer of this container
- application_id
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.
- package_version
Provides the version identification for the container. KIWI NG validates this against the Microsoft Package Version Numbering rules.
- launcher
Provides the binary file name of the launcher
.exe
file.
Warning
There is no validation by KIWI NG if the contents of AppxManifest.xml
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.
Include the
Virtualization/WSL
repository 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
/meta/data
$ zypper in fb-util-for-appx DISTRO_APPX_METADATA_PACKAGE
Note
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_NAME
for 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.kiwi
and 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>
Warning
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 Microsoft-Windows-Subsystem-Linux
must be enabled. For further details on how to setup the Windows machine
see the following documentation:
Windows Subsystem for Linux