Debian Codegraph @

doc/source/building_images/build_wsl_container.rst

raw
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>`__.