dev-manual: Document the WSLv2 install process

(From yocto-docs rev: 65e3a1b3c82475f706418b8ec7d0e6bed34b382b)

Signed-off-by: Alejandro Hernandez Samaniego <alejandro@enedino.org>
Signed-off-by: Alejandro Hernandez Samaniego <alhe@linux.microsoft.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 141 insertions, 6 deletions

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
         <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
         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
         <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
         which leverages
-        <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
+        <ulink url='https://www.docker.com/'>Docker Containers</ulink> or it can
+        be a Windows machine capable of running Windows Subsystem For Linux v2 (WSL).
         <note>
-            You cannot use a build host that is using the
-            <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux</ulink>
-            (WSL).
-            The Yocto Project is not compatible with WSL.
+          The Yocto Project is not compatible with
+          <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux v1</ulink>.
+          It is compatible but not officially supported nor validated with WSLv2.
+          If you still decide to use WSL please upgrade to
+          <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>WSLv2</ulink>.
         </note>
     </para>
 
@@ -654,6 +656,139 @@
             section in the Toaster User Manual.
         </para>
     </section>
+
+    <section id='setting-up-to-use-wsl'>
+        <title>Setting Up to Use Windows Subsystem For Linux (WSLv2)</title>
+
+        <para>
+            With <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'>
+            Windows Subsystem for Linux (WSLv2)</ulink>, 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.
+        </para>
+
+        <para>
+            Follow these general steps to prepare a Windows machine using WSLv2
+            as your Yocto Project build host:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Make sure your Windows 10 machine is capable of running WSLv2:</emphasis>
+                  
+                    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".
+                    <literallayout class='monospaced'>
+    C:\Users\myuser> ver
+
+    Microsoft Windows [Version 10.0.19041.153]
+                    </literallayout>
+                    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 <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>Windows 10 WSLv2</ulink>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Install the Linux distribution of your choice inside Windows 10:</emphasis>
+                    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.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Check your Linux distribution is using WSLv2:</emphasis>
+                    Open a Windows PowerShell and run:
+                    <literallayout class='monospaced'>
+    C:\WINDOWS\system32> wsl -l -v
+    NAME      STATE           VERSION
+    *Ubuntu    Running         2
+                    </literallayout>
+                    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.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Optionally Orient Yourself on WSL:</emphasis>
+                    If you are unfamiliar with WSL, you can learn more here -
+                    <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'></ulink>.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Launch your WSL Distibution:</emphasis>
+                    From the Windows start menu simply launch your WSL distribution
+                    just like any other application.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Optimize your WSLv2 storage often:</emphasis>
+                    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:
+                    <orderedlist>
+                        <listitem><para>
+                            <emphasis>Find the location of your VHDX file:</emphasis>
+                            First you need to find the distro app package directory,
+                            to achieve this open a Windows Powershell as Administrator
+                            and run:
+                            <literallayout class='monospaced'>
+    C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
+    PackageFamilyName
+    -----------------
+    CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
+                            </literallayout>
+                            You should now replace the <replaceable>PackageFamilyName</replaceable>
+                            and your <replaceable>user</replaceable> on the following
+                            path to find your VHDX file: <filename>C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\</filename>
+                            For example:
+                            <literallayout class='monospaced'>
+    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                      
+                            </literallayout>
+                            Your VHDX file path is: <filename>C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx</filename>
+                            </para></listitem>
+                        <listitem><para><emphasis>Optimize your VHDX file:</emphasis>
+                            Open a Windows Powershell as Administrator to optimize
+                            your VHDX file, shutting down WSL first:
+                            <literallayout class='monospaced'>
+    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
+                            </literallayout>
+                            A progress bar should be shown while optimizing the VHDX file,
+                            and storage should now be reflected correctly on the Windows
+                            Explorer.
+                            </para></listitem>
+                    </orderedlist>
+                </para></listitem>
+            </orderedlist>
+            <note>
+              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 <filename>C:</filename>
+              drive on <filename>/mnt/c/</filename> (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.
+            </note>
+            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
+            "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
+            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
+            "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
+            section in the Toaster User Manual.
+        </para>
+    </section>
 </section>
 
 <section id='locating-yocto-project-source-files'>