# WSL-DistroLauncher

**Repository Path**: MegaWisdom/WSL-DistroLauncher

## Basic Information

- **Project Name**: WSL-DistroLauncher
- **Description**: WSL 由微软 Windows Kernel 团队开发，WSL-DistroLauncher 是 Linux 子系统（WSL）分发安装程序应用程序的参考实现
- **Primary Language**: C/C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://www.oschina.net/p/wsl-distrolauncher
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2021-11-28
- **Last Updated**: 2021-12-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WSL Distro Launcher 参考实现
## 介绍 

这是一个WSL发行版安装/加载APP的参考实现。每个发行包都必须包括一个加载app，他负责你的WSL发行版的完整安装与注册，加载一个基于WSL的新的发行版。

一旦你编译好了你的发行版加载器，和需要的艺术资源，配置，distro.tar.gz一起打包，然后进行数字签名，这样你就可以旁加载你的发行版在你的机器上。
  
## 重点! 
在你要发布你的发行版到微软商店之前，你必须和WSL团队取得联系：wslpartners@microsoft.com.

## 目标 
本工程的目标

* Linux发行版的所有者可以打包和提交一个APP到微软商店，运行在WSL上。
* 开发者可以创建一个定制的Linux发行版，旁加载在他们自己的机器上.

## 内容
这个参考加载器提供了以下功能：
(`launcher.exe` 可以替换为发行版名字)

* `launcher.exe`
  - 在用户家目录加载默认Shell.

* `launcher.exe install [--root]`
  - 安装发行版，安装完成后不加载shell.
    - `--root`: 不创建账号,默认账号为root.

* `launcher.exe run <command line>`
  - Run the provided command line in the current working directory. If no command line is provided, the default shell is launched.
  - Everything after `run` is passed to WslLaunchInteractive.

* `launcher.exe config [setting [value]]`
  - Configure settings for this distribution.
  - Settings:
    - `--default-user <username>`: Sets the default user to <username>. This must be an existing user.

* `launcher.exe help`
  - Print usage information.

## Launcher Outline
This is the basic flow of how the launcher code is set up.

1. 如果发行版在WSL中没有注册就注册好。注册的时候会解压tar.gz到appx.
2. 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.
    - 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.
3. 一旦distro成功注册，就可以解析其他命令行参数。参数细节在 [Introduction](#Introduction).

## 工程结构
distro 加载器由2个VS工程构成 - `launcher` 和 `DistroLauncher-Appx`.`launcher`工程会编译出一个可执行文件，在用户加载一个app时运行。`DistroLauncher-Appx`会编译出一个发行包，包含素材和依赖。

## 开始
1. 生成测试证书：
    1. 在Visual Studio打开`DistroLauncher-Appx/MyDistro.appxmanifest`
    1. 选 Packaging 标签页
    1. 选 "Choose Certificate"
    1. 点击Configure Certificate下拉菜单选择Create test certificate.

2. 编辑发行版定制信息在 `DistributionInfo.h` 和 `DistributionInfo.cpp`. 
	注意: `DistributionInfo::Name` 变量必须唯一并且版本迭代不可改变。

3.  添加 icon (.ico) 和 logo (.png) 到 `/images`. logo 将在开始菜单和任务栏使用, icon用在Console window.
    > 注意: icon 名字必须是 `icon.ico`.

4. 选一个发行版在命令行可以调用的名字。下面我将使用 `mydistro` or `mydistro.exe`. **这个可执行文件名** 必须唯一.

5. 确保`DistroLauncher-Appx/DistroLauncher-Appx.vcxproj`文件的名字修改为你第4步选的可执行文件的名字。 默认情况如下:

``` xml
<PropertyGroup Label="Globals">
  ...
  <TargetName>mydistro</TargetName>
</PropertyGroup>
```

所以, 如果你想叫你的distro "TheBestDistroEver", 修改如下:
``` xml
<PropertyGroup Label="Globals">
  ...
  <TargetName>TheBestDistroEver</TargetName>
</PropertyGroup>
```

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

6.  Update `MyDistro.appxmanifest`. There are several properties that are in the manifest that will need to be updated with your specific values:
    1. Note the `Identity Publisher` value (by default, `"CN=DistroOwner"`). We'll need that for testing the application.
    1. Ensure `<desktop:ExecutionAlias Alias="mydistro.exe" />` 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.
    1. Make sure each of the `Executable` values matches the executable name we picked in step 4.

7. 复制你发行版的tar.gz到工程根目录并重命名为`install.tar.gz`.

## 设置Windows Environment
You 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).

> Note: If you are using Hyper-V you can use the new VM gallery to easily spin up a Windows instance.

Also, 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). 

## Build and Test

To 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. 

> **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. 

### 编译工程 (Command line):
To 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.

> 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.

`build.bat` assumes that MSBuild is installed at one of the following paths:
`%ProgramFiles*%\MSBuild\14.0\bin\msbuild.exe` or
`%ProgramFiles*%\Microsoft Visual Studio\2017\Enterprise\MSBuild\15.0\Bin\msbuild.exe` or
`%ProgramFiles*%\Microsoft Visual Studio\2017\Community\MSBuild\15.0\Bin\msbuild.exe`.

If that's not the case, then you will need to modify that script.

Once 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. 

You can also use the PowerShell cmdlet `Add-AppxPackage` to register your appx:
``` powershell
powershell Add-AppxPackage x64\Debug\DistroLauncher-Appx\DistroLauncher-Appx_1.0.0.0_x64_Debug.appx
```

### 编译工程 (Visual Studio):

You 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.

In 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**

### Installing & Testing
You should now have a finished appx sideloaded on your machine for testing.

To 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. 

You 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.

When 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. 

Once complete, you should see a Console window with your distro running inside it.

### 出版
如果你是 distro vendor 并想出版你的distro到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:

#### 出版要求
1. Reach out to the WSL team to introduce your distro, yourself, and your team
1. Agree with the WSL team on a testing and publishing plan
1. Complete any required paperwork
1. Sign up for an "Company" Windows Developer Account https://developer.microsoft.com/en-us/store/register. 
    > 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.