diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 59ffa49bb6..19c1068a70 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -394,16 +394,18 @@
This section provides procedures to set up a system to be used as your
build host
for development using the Yocto Project.
- Your build host can be a native Linux machine (recommended) or it can
+ Your build host can be a native Linux machine (recommended), it can
be a machine (Linux, Mac, or Windows) that uses
CROPS,
which leverages
- Docker Containers.
+ Docker Containers or it can
+ be a Windows machine capable of running Windows Subsystem For Linux v2 (WSL).
- You cannot use a build host that is using the
- Windows Subsystem for Linux
- (WSL).
- The Yocto Project is not compatible with WSL.
+ The Yocto Project is not compatible with
+ Windows Subsystem for Linux v1.
+ It is compatible but not officially supported nor validated with WSLv2.
+ If you still decide to use WSL please upgrade to
+ WSLv2.
@@ -654,6 +656,139 @@
section in the Toaster User Manual.
+
+
+ Setting Up to Use Windows Subsystem For Linux (WSLv2)
+
+
+ With
+ Windows Subsystem for Linux (WSLv2), you can create a
+ Yocto Project development environment that allows you to build
+ on Windows. You can set up a Linux distribution inside Windows
+ in which you can develop using the Yocto Project.
+
+
+
+ Follow these general steps to prepare a Windows machine using WSLv2
+ as your Yocto Project build host:
+
+
+ Make sure your Windows 10 machine is capable of running WSLv2:
+
+ WSLv2 is only available for Windows 10 builds > 18917. To
+ check which build version you are running, you may open a
+ command prompt on Windows and execute the command "ver".
+
+ C:\Users\myuser> ver
+
+ Microsoft Windows [Version 10.0.19041.153]
+
+ If your build is capable of running WSLv2 you may continue,
+ for more information on this subject or instructions on how
+ to upgrade to WSLv2 visit Windows 10 WSLv2
+
+
+ Install the Linux distribution of your choice inside Windows 10:
+ Once you know your version of Windows 10 supports WSLv2,
+ you can install the distribution of your choice from the
+ Microsoft Store.
+ Open the Microsoft Store and search for Linux. While there
+ are several Linux distributions available, the assumption
+ is that your pick will be one of the distributions supported
+ by the Yocto Project as stated on the instructions for
+ using a native Linux host.
+ After making your selection, simply click "Get" to download
+ and install the distribution.
+
+
+ Check your Linux distribution is using WSLv2:
+ Open a Windows PowerShell and run:
+
+ C:\WINDOWS\system32> wsl -l -v
+ NAME STATE VERSION
+ *Ubuntu Running 2
+
+ Note the version column which says the WSL version being used by
+ your distribution, on compatible systems, this can be changed back
+ at any point in time.
+
+
+ Optionally Orient Yourself on WSL:
+ If you are unfamiliar with WSL, you can learn more here -
+ .
+
+
+ Launch your WSL Distibution:
+ From the Windows start menu simply launch your WSL distribution
+ just like any other application.
+
+
+ Optimize your WSLv2 storage often:
+ Due to the way storage is handled on WSLv2, the storage
+ space used by the undelying Linux distribution is not
+ reflected immedately, and since bitbake heavily uses
+ storage, after several builds, you may be unaware you
+ are running out of space. WSLv2 uses a VHDX file for
+ storage, this issue can be easily avoided by manually
+ optimizing this file often, this can be done in the
+ following way:
+
+
+ Find the location of your VHDX file:
+ First you need to find the distro app package directory,
+ to achieve this open a Windows Powershell as Administrator
+ and run:
+
+ C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
+ PackageFamilyName
+ -----------------
+ CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
+
+ You should now replace the PackageFamilyName
+ and your user on the following
+ path to find your VHDX file: C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\
+ For example:
+
+ ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
+ Mode LastWriteTime Length Name
+ -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx
+
+ Your VHDX file path is: C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx
+
+ Optimize your VHDX file:
+ Open a Windows Powershell as Administrator to optimize
+ your VHDX file, shutting down WSL first:
+
+ C:\WINDOWS\system32> wsl --shutdown
+ C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full
+
+ A progress bar should be shown while optimizing the VHDX file,
+ and storage should now be reflected correctly on the Windows
+ Explorer.
+
+
+
+
+
+ The current implementation of WSLv2 does not have out-of-the-box
+ access to external devices such as those connected through a
+ USB port, but it automatically mounts your C:
+ drive on /mnt/c/ (and others), which
+ you can use to share deploy artifacts to be later flashed on
+ hardware through Windows, but your build directory should not
+ reside inside this mountpoint.
+
+ Once you have WSLv2 set up, everything is in place to
+ develop just as if you were running on a native Linux machine.
+ If you are going to use the Extensible SDK container, see the
+ "Using the Extensible SDK"
+ Chapter in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
+ If you are going to use the Toaster container, see the
+ "Setting Up and Using Toaster"
+ section in the Toaster User Manual.
+
+