From 57a3886757aa2870b6966542e7147c287b15f400 Mon Sep 17 00:00:00 2001 From: Alejandro Hernandez Samaniego Date: Mon, 30 Mar 2020 23:25:23 -0700 Subject: dev-manual: Document the WSLv2 install process (From yocto-docs rev: 65e3a1b3c82475f706418b8ec7d0e6bed34b382b) Signed-off-by: Alejandro Hernandez Samaniego Signed-off-by: Alejandro Hernandez Samaniego Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-start.xml | 147 ++++++++++++++++++++++++-- 1 file changed, 141 insertions(+), 6 deletions(-) (limited to 'documentation') 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. + +
-- cgit v1.2.3-54-g00ecf