summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorAlejandro Hernandez Samaniego <alhe@linux.microsoft.com>2020-03-30 23:25:23 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-04-06 14:25:52 +0100
commit57a3886757aa2870b6966542e7147c287b15f400 (patch)
tree047d07e041f7bd3badcee420e0dd018194cd7d72 /documentation/dev-manual
parent0894fd32bdcf224908fa9f26cf046e854831db87 (diff)
downloadpoky-57a3886757aa2870b6966542e7147c287b15f400.tar.gz
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>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-start.xml147
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 @@
394 This section provides procedures to set up a system to be used as your 394 This section provides procedures to set up a system to be used as your
395 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink> 395 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
396 for development using the Yocto Project. 396 for development using the Yocto Project.
397 Your build host can be a native Linux machine (recommended) or it can 397 Your build host can be a native Linux machine (recommended), it can
398 be a machine (Linux, Mac, or Windows) that uses 398 be a machine (Linux, Mac, or Windows) that uses
399 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>, 399 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
400 which leverages 400 which leverages
401 <ulink url='https://www.docker.com/'>Docker Containers</ulink>. 401 <ulink url='https://www.docker.com/'>Docker Containers</ulink> or it can
402 be a Windows machine capable of running Windows Subsystem For Linux v2 (WSL).
402 <note> 403 <note>
403 You cannot use a build host that is using the 404 The Yocto Project is not compatible with
404 <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux</ulink> 405 <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux v1</ulink>.
405 (WSL). 406 It is compatible but not officially supported nor validated with WSLv2.
406 The Yocto Project is not compatible with WSL. 407 If you still decide to use WSL please upgrade to
408 <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>WSLv2</ulink>.
407 </note> 409 </note>
408 </para> 410 </para>
409 411
@@ -654,6 +656,139 @@
654 section in the Toaster User Manual. 656 section in the Toaster User Manual.
655 </para> 657 </para>
656 </section> 658 </section>
659
660 <section id='setting-up-to-use-wsl'>
661 <title>Setting Up to Use Windows Subsystem For Linux (WSLv2)</title>
662
663 <para>
664 With <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'>
665 Windows Subsystem for Linux (WSLv2)</ulink>, you can create a
666 Yocto Project development environment that allows you to build
667 on Windows. You can set up a Linux distribution inside Windows
668 in which you can develop using the Yocto Project.
669 </para>
670
671 <para>
672 Follow these general steps to prepare a Windows machine using WSLv2
673 as your Yocto Project build host:
674 <orderedlist>
675 <listitem><para>
676 <emphasis>Make sure your Windows 10 machine is capable of running WSLv2:</emphasis>
677
678 WSLv2 is only available for Windows 10 builds > 18917. To
679 check which build version you are running, you may open a
680 command prompt on Windows and execute the command "ver".
681 <literallayout class='monospaced'>
682 C:\Users\myuser> ver
683
684 Microsoft Windows [Version 10.0.19041.153]
685 </literallayout>
686 If your build is capable of running WSLv2 you may continue,
687 for more information on this subject or instructions on how
688 to upgrade to WSLv2 visit <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>Windows 10 WSLv2</ulink>
689 </para></listitem>
690 <listitem><para>
691 <emphasis>Install the Linux distribution of your choice inside Windows 10:</emphasis>
692 Once you know your version of Windows 10 supports WSLv2,
693 you can install the distribution of your choice from the
694 Microsoft Store.
695 Open the Microsoft Store and search for Linux. While there
696 are several Linux distributions available, the assumption
697 is that your pick will be one of the distributions supported
698 by the Yocto Project as stated on the instructions for
699 using a native Linux host.
700 After making your selection, simply click "Get" to download
701 and install the distribution.
702 </para></listitem>
703 <listitem><para>
704 <emphasis>Check your Linux distribution is using WSLv2:</emphasis>
705 Open a Windows PowerShell and run:
706 <literallayout class='monospaced'>
707 C:\WINDOWS\system32> wsl -l -v
708 NAME STATE VERSION
709 *Ubuntu Running 2
710 </literallayout>
711 Note the version column which says the WSL version being used by
712 your distribution, on compatible systems, this can be changed back
713 at any point in time.
714 </para></listitem>
715 <listitem><para>
716 <emphasis>Optionally Orient Yourself on WSL:</emphasis>
717 If you are unfamiliar with WSL, you can learn more here -
718 <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'></ulink>.
719 </para></listitem>
720 <listitem><para>
721 <emphasis>Launch your WSL Distibution:</emphasis>
722 From the Windows start menu simply launch your WSL distribution
723 just like any other application.
724 </para></listitem>
725 <listitem><para>
726 <emphasis>Optimize your WSLv2 storage often:</emphasis>
727 Due to the way storage is handled on WSLv2, the storage
728 space used by the undelying Linux distribution is not
729 reflected immedately, and since bitbake heavily uses
730 storage, after several builds, you may be unaware you
731 are running out of space. WSLv2 uses a VHDX file for
732 storage, this issue can be easily avoided by manually
733 optimizing this file often, this can be done in the
734 following way:
735 <orderedlist>
736 <listitem><para>
737 <emphasis>Find the location of your VHDX file:</emphasis>
738 First you need to find the distro app package directory,
739 to achieve this open a Windows Powershell as Administrator
740 and run:
741 <literallayout class='monospaced'>
742 C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
743 PackageFamilyName
744 -----------------
745 CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
746 </literallayout>
747 You should now replace the <replaceable>PackageFamilyName</replaceable>
748 and your <replaceable>user</replaceable> on the following
749 path to find your VHDX file: <filename>C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\</filename>
750 For example:
751 <literallayout class='monospaced'>
752 ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
753 Mode LastWriteTime Length Name
754 -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx
755 </literallayout>
756 Your VHDX file path is: <filename>C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx</filename>
757 </para></listitem>
758 <listitem><para><emphasis>Optimize your VHDX file:</emphasis>
759 Open a Windows Powershell as Administrator to optimize
760 your VHDX file, shutting down WSL first:
761 <literallayout class='monospaced'>
762 C:\WINDOWS\system32> wsl --shutdown
763 C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full
764 </literallayout>
765 A progress bar should be shown while optimizing the VHDX file,
766 and storage should now be reflected correctly on the Windows
767 Explorer.
768 </para></listitem>
769 </orderedlist>
770 </para></listitem>
771 </orderedlist>
772 <note>
773 The current implementation of WSLv2 does not have out-of-the-box
774 access to external devices such as those connected through a
775 USB port, but it automatically mounts your <filename>C:</filename>
776 drive on <filename>/mnt/c/</filename> (and others), which
777 you can use to share deploy artifacts to be later flashed on
778 hardware through Windows, but your build directory should not
779 reside inside this mountpoint.
780 </note>
781 Once you have WSLv2 set up, everything is in place to
782 develop just as if you were running on a native Linux machine.
783 If you are going to use the Extensible SDK container, see the
784 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
785 Chapter in the Yocto Project Application Development and the
786 Extensible Software Development Kit (eSDK) manual.
787 If you are going to use the Toaster container, see the
788 "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
789 section in the Toaster User Manual.
790 </para>
791 </section>
657</section> 792</section>
658 793
659<section id='locating-yocto-project-source-files'> 794<section id='locating-yocto-project-source-files'>