Packaging a WSL Distro to MSIX

This post has been republished via RSS; it originally appeared at: Microsoft Tech Community - Latest Blogs - .

In this post I will demonstrate how to export a WSL distro to a .tar file, and how to use the WSL-DistroLauncher to package it to MSIX.

 

In case you want to know more details about MSIX, or even get some examples about it, please check the post MSIX: Probably you don't know, but you are already using it.

 

There are scenarios where you want to customize a WSL Distro, like settings, apps users, etc, before making it available for your users.

 

Regardless of where you installed the distro (Microsoft Store, Vendor website, GitHub, Docker, etc.), the process will be the same. I mean, once you install your favorite distro, you can customize it as per your needs.

 

For example, let suppose you were working with the openSUSE-Leap-15.3. After installed it, I customized it with the following Apps:

 

  • Text Editor
  • Scribus
  • Thunar File

 

opensuse_startmenu.png

 

 

 

But I got the following encoding error for my Apps:

 

wlsg_encoding.png

 

That I fixed using the steps described at Troubleshooting GUI Linux apps on openSUSE on WSLg.

 

Once everything was working fine and my distro customization is done, now is time to export the distro to .tar.

 

The export command expects the distro name, that can be easily obtained through the following command:

 

wsl -l -v

 

wsllist.png

 

Once we now the distro name, we can export it using:

 

wsl --export openSUSE-LEap-15.3 c:\msix\bb\install.tar

 

Observe that I am naming the distro to install.tar, as this name is expected in the WSL-DistroLaucher project to package the distro to MSIX.

 

The next step is to compress the .tar file to .gz.

 

& "$env:ProgramFiles\7-Zip\7z.exe" a .\install.tar.gz .\install.tar

 

 

compresstar.png

 

WSL Distro-Launcher

 

Now that we have the tar.gz, it is time to use the WSL Distro Launcher that is available on GitHub and that is the C++ reference implementation for a Windows Subsystem for Linux (WSL) distribution installer/launcher application. Every distro package must include a launcher app, which is responsible for completing installation & registration of your distro with WSL, and for launching new distro instances atop WSL.

 

This is the WSL-DistroLaucher solution structure:

 

distrolauncherfiles.png

 

Adding install.tar.gz to the solution

The first part is to add the install.tar.gz file, created previously, to our solution:

 

tarfile.png

 

MyDistro.appxmanifest

Let's start by the manifest file (MyDistro.appxmanifest). This is the manifest used by MSIX applications, and in our case, we are interested in defining the display name, description, assets (images of the applications available on Start menu) of our distro. In my case, I am naming the MSIX package to WSL-openSuse, with the description "My Own WSL openSuse" and using the Windows logo as Assets. In the Visual Assets tab, it is possible to pick up an image and ask to Visual Studio generate all the other images with the required dimensions.

 

manifest.png

 

DistroLauncher.cpp

Any other pre-launch setup is performed in InstallDistribution() method of the DistroLauncher file. This is where distro-specific setup can be performed. As an example, the reference implementation creates a user account and sets this user account as the default for the distro.

 

InstallDistribution.png

 

 

In my case, I just comment the user step to let him to create a local user. Instead, I am creating a hard-coded user called mysuseuser:

 

mysuseuser.png

 

 

DistributionInfo.h & DistributionInfo.cpp

You can edit your distribution-specific information in DistributionInfo.h and DistributionInfo.cpp.

In the DistributionInfo.h, you can change the DistributionInfoName variable and the DistributionInfo WindowTitle with the name of your distribution. That value will be displayed to the user via wslconfig.exe and in other places.

 

Notice that the DistributionInfo::Name must uniquely identify your distribution and cannot change from one version of your app to the next.

 

distributioninfoheader.png

 

 

As I didn't have the usermod option to create the user, I changed the code to use useradd in the method CreateUser of the class DistributionInfo:

 

createuser.png

 

Build the solution

Inside the solution files, there is the build.bat file that is used to build the solution and generate the MSIX file. I am running this file in the Visual Studio Command prompt:

 

build.png

 

Follows the expected result:

 

msixresult.png

 

Sign a MSIX package

MSIX packages must be digitally signed with a trust certificate to be installed.

If we just to install the MSIX created previously, we will receive the following error:

 

error.png

 

In our scenario, build.bat already signed the package with a self-contained certificate. This certificate is used only for testing purpose and requires to be installed on Local Machine\Trusted People of the test environment:

 

certificate.png

 

Windows Subsystem for Linux

Besides signing the MSIX package you have to enable WSL on your environment. As I am using Windows 11, I have enabled it from Microsoft Store:

 

wslpreview.png

 

Install for current user

Finally, after enabling WSL and signing the MSIX file, we can install it:

 

msixinstall.png

 

 

You can install by manually double-clicking in the msix file or using the following command:

 

Add-AppPackage C:\wsl\DistroLauncher-Appx_1.0.0.0_x64.msix

 

The Add-AppPackage command will install the MSIX app only for the current user.

 

Install for all users

Run the following command using an elevated account to install the MSIX app for all users:

 

Add-AppProvisionedPackage -Online -SkipLicense -PackagePath "C:\wsl\DistroLauncher-Appx_1.0.1.0_x64.msix"

 

msixinstallforall.png

 

I hope you liked it.

 

 

 

 

 

REMEMBER: these articles are REPUBLISHED. Your best bet to get a reply is to follow the link at the top of the post to the ORIGINAL post! BUT you're more than welcome to start discussions here:

This site uses Akismet to reduce spam. Learn how your comment data is processed.