{"id":13728975,"url":"https://github.com/Microsoft/WSL-DistroLauncher","last_synced_at":"2025-05-08T01:30:26.059Z","repository":{"id":37602557,"uuid":"91485889","full_name":"microsoft/WSL-DistroLauncher","owner":"microsoft","description":"Sample/reference launcher app for WSL distro Microsoft Store packages.","archived":false,"fork":false,"pushed_at":"2024-07-25T10:46:04.000Z","size":370,"stargazers_count":1670,"open_issues_count":45,"forks_count":516,"subscribers_count":113,"default_branch":"master","last_synced_at":"2024-08-04T02:08:22.065Z","etag":null,"topics":["uwp-apps","wsl"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-16T17:28:17.000Z","updated_at":"2024-08-01T21:27:48.000Z","dependencies_parsed_at":"2024-10-25T19:47:13.611Z","dependency_job_id":"a9a5d972-5cbe-4477-81d9-e4f3d7c12069","html_url":"https://github.com/microsoft/WSL-DistroLauncher","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FWSL-DistroLauncher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FWSL-DistroLauncher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FWSL-DistroLauncher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FWSL-DistroLauncher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/WSL-DistroLauncher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252981362,"owners_count":21835415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["uwp-apps","wsl"],"created_at":"2024-08-03T02:00:53.042Z","updated_at":"2025-05-08T01:30:26.046Z","avatar_url":"https://github.com/microsoft.png","language":"C++","funding_links":[],"categories":["WSL Tools \u0026 Projects","WSL Tools","Tools"],"sub_categories":["10. GUI Apps","Mesh networks"],"readme":"# WSL Distro Launcher Reference Implementation\n\n\u003e [!NOTE]\n\u003e There is a newer method for creating WSL distros please see [this doc page](https://learn.microsoft.com/windows/wsl/build-custom-distro).\n\n## Introduction \nThis 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 \u0026 registration of your distro with WSL, and for launching new distro instances atop WSL.\n\nOnce you've built your distro launcher, packaged it along with the required art assets, manifest, and distro.tar.gz, and digitally signed the package, you will be able to sideload your distro on your own machine(s).\n\n## Goals\nThe goal of this project is to enable:\n\n* Linux distribution owners to package and submit an application that runs on top of WSL to the Microsoft Store\n* Developers to create custom Linux distributions that can be sideloaded onto their dev machine\n\n## Contents\nThis reference launcher provides the following functionality:\n(where `launcher.exe` is replaced by the distro-specific name)\n\n* `launcher.exe`\n  - Launches the user's default shell in the user's home directory.\n\n* `launcher.exe install [--root]`\n  - Install the distribution and do not launch the shell when complete.\n    - `--root`: Do not create a user account and leave the default user set to root.\n\n* `launcher.exe run \u003ccommand line\u003e`\n  - Run the provided command line in the current working directory. If no command line is provided, the default shell is launched.\n  - Everything after `run` is passed to WslLaunchInteractive.\n\n* `launcher.exe config [setting [value]]`\n  - Configure settings for this distribution.\n  - Settings:\n    - `--default-user \u003cusername\u003e`: Sets the default user to \u003cusername\u003e. This must be an existing user.\n\n* `launcher.exe help`\n  - Print usage information.\n\n## Launcher Outline\nThis is the basic flow of how the launcher code is set up.\n\n1. If the distribution is not registered with WSL, register it. Registration extracts the tar.gz file that is included in your distribution appx.\n2. Once the distro is successfully registered, any other pre-launch setup is performed in `InstallDistribution()`. 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.\n    - Note: The commands used to query and create user accounts in this reference implementation are Ubuntu-specific; change as necessary to match the needs of your distro.\n3. Once the distro is configured, parse any other command-line arguments. The details of these arguments are described above, in the [Introduction](#Introduction).\n\n## Project Structure\nThe distro launcher is comprised of two Visual Studio projects - `launcher` and `DistroLauncher-Appx`. The `launcher` project builds the actual executable that is run when a user launches the app. The `DistroLauncher-Appx` builds the distro package with all the correctly scaled assets and other dependencies. Code changes will be built in the `launcher` project (under `DistroLauncher/`). Manifest changes are applied in the `DistroLauncher-Appx` project (under `DistroLauncher-Appx/`). \n\n## Getting Started\n1. Generate a test certificate:\n    1. In Visual Studio, open `DistroLauncher-Appx/MyDistro.appxmanifest`\n    1. Select the Packaging tab\n    1. Select \"Choose Certificate\"\n    1. Click the Configure Certificate drop down and select Create test certificate.\n\n2. Edit your distribution-specific information in `DistributionInfo.h` and `DistributionInfo.cpp`. **NOTE: The `DistributionInfo::Name` variable must uniquely identify your distribution and cannot change from one version of your app to the next.**\n    \u003e Note: The examples for creating a user account and querying the UID are from an Ubuntu-based system, and may need to be modified to work appropriately on your distribution.\n\n3.  Add an icon (.ico) and logo (.png) to the `/images` directory. The logo will be used in the Start Menu and the taskbar for your launcher, and the icon will appear on the Console window.\n    \u003e Note: The icon must be named `icon.ico`.\n\n4. Pick the name you'd like to make this distro callable from the command line. For the rest of the README, I'll be using `mydistro` or `mydistro.exe`. **This is the name of your executable** and should be unique.\n\n5. Make sure to change the name of the project in the `DistroLauncher-Appx/DistroLauncher-Appx.vcxproj` file to the name of your executable we picked in step 4. By default, the lines should look like:\n\n``` xml\n\u003cPropertyGroup Label=\"Globals\"\u003e\n  ...\n  \u003cTargetName\u003emydistro\u003c/TargetName\u003e\n\u003c/PropertyGroup\u003e\n```\n\nSo, if I wanted to instead call my distro \"TheBestDistroEver\", I'd change this to:\n``` xml\n\u003cPropertyGroup Label=\"Globals\"\u003e\n  ...\n  \u003cTargetName\u003eTheBestDistroEver\u003c/TargetName\u003e\n\u003c/PropertyGroup\u003e\n```\n\n\u003e Note: **DO NOT** change the ProjectName of the `DistroLauncher/DistroLauncher.vcxproj` from the value `launcher`. Doing so will break the build, as the DistroLauncher-Appx project is looking for the output of this project as `launcher.exe`.\n\n6.  Update `MyDistro.appxmanifest`. There are several properties that are in the manifest that will need to be updated with your specific values:\n    1. Note the `Identity Publisher` value (by default, `\"CN=DistroOwner\"`). We'll need that for testing the application.\n    1. Ensure `\u003cdesktop:ExecutionAlias Alias=\"mydistro.exe\" /\u003e` ends in \".exe\". This is the command that will be used to launch your distro from the command line and should match the executable name we picked in step 4.\n    1. Make sure each of the `Executable` values matches the executable name we picked in step 4.\n\n7. Copy your tar.gz containing your distro into the root of the project and rename it to `install.tar.gz`.\n\n## Setting up your Windows Environment\nYou will need a Windows environment to test that your app installs and works as expected. To set up a Windows environment for testing you can follow the steps from the [Windows Dev Center](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines).\n\n\u003e Note: If you are using Hyper-V you can use the new VM gallery to easily spin up a Windows instance.\n\nAlso, to allow your locally built distro package to be manually side-loaded, ensure you've enabled Developer Mode in the Settings app (sideloading won't work without it). \n\n## Build and Test\n\nTo help building and testing the DistroLauncher project, we've included several scripts to automate some tasks. You can either choose to use these scripts from the command line, or work directly in Visual Studio, whatever your preference is. \n\n\u003e **Note**: some sideloading/deployment steps don't work if you mix and match Visual Studio and the command line for development. If you run into errors while trying to deploy your app after already deploying it once, the easiest step is usually just to uninstall the previously sideloaded version and try again. \n\n### Building the Project (Command line):\nTo compile the project, you can simply type `build` in the root of the project to use MSBuild to build the solution. This is useful for verifying that your application compiles. It will also build an appx for you to sideload on your dev machine for testing.\n\n\u003e Note: We recommend that you build your launcher from the \"Developer Command Prompt for Visual Studio\" which can be launched from the start menu. This command-prompt sets up several path and environment variables to make building easier and smoother.\n\n`build.bat` assumes that MSBuild is installed at one of the following paths:\n`%ProgramFiles*%\\MSBuild\\14.0\\bin\\msbuild.exe` or\n`%ProgramFiles*%\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe` or\n`%ProgramFiles*%\\Microsoft Visual Studio\\2017\\Community\\MSBuild\\15.0\\Bin\\msbuild.exe`.\n\nIf that's not the case, then you will need to modify that script.\n\nOnce you've completed the build, the packaged appx should be placed in a directory like `WSL-DistroLauncher\\x64\\Release\\DistroLauncher-Appx` and should be named something like `DistroLauncher-Appx_1.0.0.0_x64.appx`. Simply double click that appx file to open the sideloading dialog. \n\nYou can also use the PowerShell cmdlet `Add-AppxPackage` to register your appx:\n``` powershell\npowershell Add-AppxPackage x64\\Debug\\DistroLauncher-Appx\\DistroLauncher-Appx_1.0.0.0_x64_Debug.appx\n```\n\n### Building Project (Visual Studio):\n\nYou can also easily build and deploy the distro launcher from Visual Studio. To sideload your appx on your machine for testing, all you need to do is right-click on the \"Solution (DistroLauncher)\" in the Solution Explorer and click \"Deploy Solution\". This should build the project and sideload it automatically for testing.\n\nIn order run your solution under the Visual Studio debugger, you will need to copy your install.tar.gz file into your output folder, for example: `x64\\Debug`. **NOTE: If you have registered your distribution by this method, you will need to manually unregister it via wslconfig.exe /unregister**\n\n### Installing \u0026 Testing\nYou should now have a finished appx sideloaded on your machine for testing.\n\nTo install your distro package, double click on the signed appx and click \"Install\". Note that this only installs the appx on your system - it doesn't unzip the tar.gz or register the distro yet. \n\nYou should now find your distro in the Start menu, and you can launch your distro by clicking its Start menu tile or executing your distro from the command line by entering its name into a Cmd/PowerShell Console.\n\nWhen you first run your newly installed distro, it is unpacked and registered with WSL. This can take a couple of minutes while all your distro files are unpacked and copied to your drive. \n\nOnce complete, you should see a Console window with your distro running inside it.\n\n### Publishing\nIf you are a distro vendor and want to publish  your distro to the Windows store, you will need to complete some pre-requisite steps to ensure the quality and integrity of the WSL distro ecosystem, and to safeguard our users:\n\n#### Publishing Pre-Requisites\n1. Sign up for an \"Company\" Windows Developer Account https://developer.microsoft.com/en-us/store/register. \n    \u003e Note: This can take a week or more since you'll be required to confirm your organization's identity with an independent verification service via email and/or telephone.\n1. Follow the guides to publish your distro as a UWP app: https://docs.microsoft.com/en-us/windows/uwp/publish/\n1. [Optional] Reach out to the WSL team at wslpartners@microsoft.com to introduce us to your distro!\n\n#### Publishing Code changes\nYou'll also need to change a few small things in your project to prepare your distro for publishing to the Windows store\n\n1. In your appxmanifest, you will need to change the values of the Identity field to match your identity in your Windows Store account:\n\n``` xml\n\u003cIdentity Name=\"1234YourCompanyName.YourAppName\"\n          Version=\"1.0.1.0\"\n          Publisher=\"CN=12345678-045C-ABCD-1234-ABCDEF987654\"\n          ProcessorArchitecture=\"x64\" /\u003e\n```\n\n  \u003e **NOTE**: Visual Studio can update this for you! You can do that by right-clicking on \"DistroLauncher-Appx (Universal Windows)\" in the solution explorer and clicking on \"Store... Associate App with the Store...\" and following the wizard. \n\n2. You will either need to run `build rel` from the command line to generate the Release version of your appx or use Visual Studio directly to upload your package to the store. You can do this by right-clicking on \"DistroLauncher-Appx (Universal Windows)\" in the solution explorer and clicking on \"Store... Create App Packages...\" and following the wizard.\n\nAlso, make sure to check out the [Notes for uploading to the Store](https://github.com/Microsoft/WSL-DistroLauncher/wiki/Notes-for-uploading-to-the-Store) page on our wiki for more information.\n\n# Issues \u0026 Contact\nAny bugs or problems discovered with the Launcher should be filed in this project's Issues list. The team will be notified and will respond to the reported issue within 3 (US) working days.\n\nYou may also reach out to our team alias at wslpartners@microsoft.com for questions related to submitting your app to the Microsoft Store.\n\n# Contributing\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMicrosoft%2FWSL-DistroLauncher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMicrosoft%2FWSL-DistroLauncher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMicrosoft%2FWSL-DistroLauncher/lists"}