| 1 |
.. _building_wsl_build: |
| 2 |
|
| 3 |
Build a WSL Container Image |
| 4 |
=========================== |
| 5 |
|
| 6 |
.. sidebar:: Abstract |
| 7 |
|
| 8 |
This page explains how to build a WSL/Appx container image. WSL stands for |
| 9 |
Windows Subsystem for Linux, and it is a zip-based container format consumable by |
| 10 |
Windows 10 with WSL enabled. |
| 11 |
|
| 12 |
|
| 13 |
{kiwi} can build WSL images using the :command:`appx` |
| 14 |
utility. Make sure you have installed the package that provides |
| 15 |
the command on your build host. |
| 16 |
|
| 17 |
Once the build host has the `appx` command installed, the |
| 18 |
following image type setup is required in the XML description, |
| 19 |
:file:`config.xml`: |
| 20 |
|
| 21 |
.. code:: xml |
| 22 |
|
| 23 |
<type image="appx" metadata_path="/meta/data"/> |
| 24 |
|
| 25 |
The :file:`/meta/data` path specifies a path that provides |
| 26 |
additional information required for the `WSL-DistroLauncher`. |
| 27 |
This component consists of a Windows (`exe`) executable file and |
| 28 |
an :file:`AppxManifest.xml` file that references other files, |
| 29 |
like icons and resource configurations for the startup of the |
| 30 |
container under Windows. |
| 31 |
|
| 32 |
.. note:: **/meta/data** |
| 33 |
|
| 34 |
Except for the root filesystem tarball, {kiwi} is not |
| 35 |
responsible for providing the metadata required for |
| 36 |
the `WSL-DistroLauncher`. It is expected that |
| 37 |
the given metadata path contains all the needed information. |
| 38 |
Typically, this information is delivered in a package |
| 39 |
provided by the distribution, and it is installed on the |
| 40 |
build host. |
| 41 |
|
| 42 |
|
| 43 |
Setup of the WSL-DistroLauncher |
| 44 |
------------------------------- |
| 45 |
|
| 46 |
The contents of the :file:`AppxManifest.xml` are changed by {kiwi} |
| 47 |
if the :file:`containerconfig` section is provided in the XML description. |
| 48 |
In the context of a WSL image, the following container configuration |
| 49 |
parameters are taken into account: |
| 50 |
|
| 51 |
.. code:: xml |
| 52 |
|
| 53 |
<containerconfig name="my-wsl-container"> |
| 54 |
<history |
| 55 |
created_by="Organisation" |
| 56 |
author="Name" |
| 57 |
application_id="AppIdentification" |
| 58 |
package_version="https://docs.microsoft.com/en-us/windows/uwp/publish/package-version-numbering" |
| 59 |
launcher="WSL-DistroLauncher-exe-file" |
| 60 |
>Container Description Text</history> |
| 61 |
</containerconfig> |
| 62 |
|
| 63 |
All information provided here, including the entire section, is optional. If the |
| 64 |
information is not specified, the existing :file:`AppxManifest.xml` is left |
| 65 |
untouched. |
| 66 |
|
| 67 |
created_by |
| 68 |
Specifies the name of a publisher organization. An `appx` container |
| 69 |
must be signed off with a digital signature. If the image is |
| 70 |
built in the Open Build Service (OBS), this is done automatically. |
| 71 |
Outside of OBS, you must make sure that the given publisher organization |
| 72 |
name matches the certificate used for signing. |
| 73 |
|
| 74 |
author |
| 75 |
Provides the name of the author and maintainer of this container. |
| 76 |
|
| 77 |
application_id |
| 78 |
Specifies an ID name for the container. The name must start with |
| 79 |
a letter, and only alphanumeric characters are allowed. {kiwi} does not |
| 80 |
validate the specified name string because there are no common criteria |
| 81 |
for the various container architectures. |
| 82 |
|
| 83 |
package_version |
| 84 |
Specifies the version identification for the container. {kiwi} |
| 85 |
validates it against the `Microsoft Package Version Numbering |
| 86 |
<https://docs.microsoft.com/en-us/windows/uwp/publish/package-version-numbering>`_ rules. |
| 87 |
|
| 88 |
launcher |
| 89 |
Specifies the binary file name of the launcher :file:`.exe` file. |
| 90 |
|
| 91 |
.. warning:: |
| 92 |
|
| 93 |
{kiwi} does not check the configuration in :file:`AppxManifest.xml` |
| 94 |
for validity or completeness. |
| 95 |
|
| 96 |
The following example shows how to build a WSL image based on |
| 97 |
openSUSE Tumbleweed: |
| 98 |
|
| 99 |
1. Check the example image descriptions; |
| 100 |
see :ref:`example-descriptions`. |
| 101 |
|
| 102 |
#. Include the `Virtualization/WSL` repository in the list (replace `<DIST>` |
| 103 |
with the desired distribution): |
| 104 |
|
| 105 |
.. code:: bash |
| 106 |
|
| 107 |
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/WSL/<DIST> WSL |
| 108 |
|
| 109 |
#. Install the `fb-util-for-appx` utility and the package that |
| 110 |
provides the `WSL-DistroLauncher` metadata. See the |
| 111 |
previous note on :file:`/meta/data`. |
| 112 |
|
| 113 |
.. code:: bash |
| 114 |
|
| 115 |
$ zypper in fb-util-for-appx DISTRO_APPX_METADATA_PACKAGE |
| 116 |
|
| 117 |
.. note:: |
| 118 |
|
| 119 |
When building images with the Open Build Service, make sure |
| 120 |
to add the packages from the `zypper` command above to the |
| 121 |
project configuration via `osc meta -e prjconf` along with |
| 122 |
the line `support: PACKAGE_NAME` for |
| 123 |
each package that needs to be installed on the Open Build |
| 124 |
Service worker that runs the {kiwi} build process. |
| 125 |
|
| 126 |
#. Configure the image type: |
| 127 |
|
| 128 |
Add the following type and container configuration to |
| 129 |
:file:`kiwi/build-tests/{exc_description_wsl}/appliance.kiwi`: |
| 130 |
|
| 131 |
.. code:: xml |
| 132 |
|
| 133 |
<type image="appx" metadata_path="/meta/data"> |
| 134 |
<containerconfig name="Tumbleweed"> |
| 135 |
<history |
| 136 |
created_by="SUSE" |
| 137 |
author="KIWI-Team" |
| 138 |
application_id="tumbleweed" |
| 139 |
package_version="2003.12.0.0" |
| 140 |
launcher="openSUSE-Tumbleweed.exe" |
| 141 |
>Tumbleweed Appliance text based</history> |
| 142 |
</containerconfig> |
| 143 |
</type> |
| 144 |
|
| 145 |
.. warning:: |
| 146 |
|
| 147 |
If the configured metadata path does not exist, the build will fail. |
| 148 |
Furthermore, {kiwi} does not check whether the metadata is complete or is |
| 149 |
valid according to the requirements of the `WSL-DistroLauncher`. |
| 150 |
|
| 151 |
#. Build the image with {kiwi}: |
| 152 |
|
| 153 |
.. code:: bash |
| 154 |
|
| 155 |
$ sudo kiwi-ng system build \ |
| 156 |
--description kiwi/build-tests/{exc_description_wsl} \ |
| 157 |
--set-repo {exc_repo_tumbleweed} \ |
| 158 |
--target-dir /tmp/myimage |
| 159 |
|
| 160 |
Testing the WSL image |
| 161 |
--------------------- |
| 162 |
|
| 163 |
For testing the image, you need a Windows 10 system. Before you proceed, enable |
| 164 |
the optional feature named :file:`Microsoft-Windows-Subsystem-Linux`. For |
| 165 |
further details on how to set up the Windows machine, see `Windows Subsystem for Linux |
| 166 |
<https://docs.microsoft.com/en-us/windows/wsl/about>`__. |