.. _building_wsl_build: Build a WSL Container Image =========================== .. sidebar:: Abstract This page explains how to build a WSL/Appx container image. WSL stands for Windows Subsystem Linux, and it is a zip-based container format consumable by Windows 10 with WSL enabled. {kiwi} can build WSL images using the :command:`appx` utility. Make sure you have installed the package that provides the command on your build host. Once the build host has the :command:`appx` installed, the following image type setup is required in the XML description :file:`config.xml`: .. code:: xml The :file:`/meta/data` path specifies a path that provides additional information required for the :command:`WSL-DistroLauncher`. This component consists out of a Windows(`exe`) executable file and an :file:`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} is not responsible for providing the meta data required for the :command:`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 :file:`AppxManifest.xml` is changed by {kiwi} if the :file:`containerconfig` section is provided in the XML description. In the context of a WSL image, the following container configuration parameters are taken into account: .. code:: xml Container Description Text All information provided here, including the entire section, is optional. If the information is not specified, the existing :file:`AppxManifest.xml` is left untouched. created_by Specifies the name of a publisher organization. An appx container must to be signed off with a digital signature. If the image is build in the Open Build Service (OBS), this is done automatically. Outside of OBS, you must o 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} doesn not validate the specified name string, because there is no common criteria for various the container architectures. package_version Specifies the version identification for the container. {kiwi} validates it against the `Microsoft Package Version Numbering `_ rules. launcher Specifies the binary file name of the launcher :file:`.exe` file. .. warning:: {kiwi} does not check the configuration in :file:`AppxManifest.xml` ifor validity or completeness. The following example shows how to build a WSL image based on openSUSE Tumbleweed: 1. Check the example image descriptions, see :ref:`example-descriptions`. #. Include the ``Virtualization/WSL`` repository to the list ((replace `` with the desired distribution)): .. code:: bash $ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/WSL/ WSL #. Install :command:`fb-util-for-appx` utility and the package that provides the :command:`WSL-DistroLauncher` metadata. See the previous note on :file:`/meta/data`. .. code:: bash $ zypper in fb-util-for-appx DISTRO_APPX_METADATA_PACKAGE .. note:: When building images with the Open Build Servic,e make sure to add the packages from the zypper command above to the project configuration via :command:`osc meta -e prjconf` along with the line :file:`support: PACKAGE_NAME` for each package that needs to be installed on the Open Build Service worker that runs the {kiwi} build process. #. Configure the image type: Add the following type and container configuration to :file:`kiwi/build-tests/{exc_description_wsl}/appliance.kiwi`: .. code:: xml Tumbleweed Appliance text based .. warning:: If the configured metadata path does not exist, the build will fail. Furthermore, {kiwi} does not check whether the metadata is complete or is valid according to the requirements of the :command:`WSL-DistroLauncher` #. Build the image with {kiwi}: .. code:: bash $ sudo kiwi-ng system build \ --description kiwi/build-tests/{exc_description_wsl} \ --set-repo {exc_repo_tumbleweed} \ --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 :file:`Microsoft-Windows-Subsystem-Linux`. For further details on how to setup the Windows machine, see: `Windows Subsystem for Linux `__