[v2,2/4] dev-manual: Document the WSLv2 install process
Details
Commit Message
@@ -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://github.com/crops/poky-container'>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'>