[2/4] dev-manual: Document the WSLv2 install process

Submitted by Alejandro Hernandez Samaniego on March 30, 2020, 5:42 a.m. | Patch ID: 171418

Details

Message ID 20200330054251.11134-2-alhe@linux.microsoft.com
State New
Headers show

Commit Message

Alejandro Hernandez Samaniego March 30, 2020, 5:42 a.m.
Signed-off-by: Alejandro Hernandez Samaniego <alejandro@enedino.org>
Signed-off-by: Alejandro Hernandez Samaniego <alhe@linux.microsoft.com>
---
 documentation/dev-manual/dev-manual-start.xml | 145 +++++++++++++++++-
 1 file changed, 139 insertions(+), 6 deletions(-)

Patch hide | download patch | download mbox

diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 8d2f316f52..a588a37f06 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -394,16 +394,16 @@ 
         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 +654,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'>

Comments

Peter Kjellerstedt March 30, 2020, 10:07 a.m.
> -----Original Message-----
> From: docs@lists.yoctoproject.org <docs@lists.yoctoproject.org> On Behalf
> Of alhe@linux.microsoft.com
> Sent: den 30 mars 2020 07:43
> To: docs@lists.yoctoproject.org
> Cc: richard.purdie@linuxfoundation.org
> Subject: [docs] [PATCH 2/4] dev-manual: Document the WSLv2 install process
> 
> Signed-off-by: Alejandro Hernandez Samaniego <alejandro@enedino.org>
> Signed-off-by: Alejandro Hernandez Samaniego <alhe@linux.microsoft.com>
> ---
>  documentation/dev-manual/dev-manual-start.xml | 145 +++++++++++++++++-
>  1 file changed, 139 insertions(+), 6 deletions(-)
> 
> diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
> index 8d2f316f52..a588a37f06 100644
> --- a/documentation/dev-manual/dev-manual-start.xml
> +++ b/documentation/dev-manual/dev-manual-start.xml
> @@ -394,16 +394,16 @@
>          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

Please restore the above as it was.

>          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>.

Change to:

            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>.

//Peter

>          </note>
>      </para>
> 
> @@ -654,6 +654,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'>
> --
> 2.17.1
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.

View/Reply Online (#121): https://lists.yoctoproject.org/g/docs/message/121
Mute This Topic: https://lists.yoctoproject.org/mt/72646541/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/leave/7795330/49612075/xyzzy  [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Alejandro Hernandez Samaniego March 31, 2020, 12:35 a.m.
Hey Peter,

Yeah that seems reasonable, will sent a v2 in a bit.

Alejandro

On 3/30/2020 3:07 AM, Peter Kjellerstedt wrote:
>> -----Original Message-----
>> From: docs@lists.yoctoproject.org <docs@lists.yoctoproject.org> On Behalf
>> Of alhe@linux.microsoft.com
>> Sent: den 30 mars 2020 07:43
>> To: docs@lists.yoctoproject.org
>> Cc: richard.purdie@linuxfoundation.org
>> Subject: [docs] [PATCH 2/4] dev-manual: Document the WSLv2 install process
>>
>> Signed-off-by: Alejandro Hernandez Samaniego <alejandro@enedino.org>
>> Signed-off-by: Alejandro Hernandez Samaniego <alhe@linux.microsoft.com>
>> ---
>>   documentation/dev-manual/dev-manual-start.xml | 145 +++++++++++++++++-
>>   1 file changed, 139 insertions(+), 6 deletions(-)
>>
>> diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
>> index 8d2f316f52..a588a37f06 100644
>> --- a/documentation/dev-manual/dev-manual-start.xml
>> +++ b/documentation/dev-manual/dev-manual-start.xml
>> @@ -394,16 +394,16 @@
>>           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
> Please restore the above as it was.
>
>>           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>.
> Change to:
>
>              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>.
>
> //Peter
>
>>           </note>
>>       </para>
>>
>> @@ -654,6 +654,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'>
>> --
>> 2.17.1
>
>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.

View/Reply Online (#122): https://lists.yoctoproject.org/g/docs/message/122
Mute This Topic: https://lists.yoctoproject.org/mt/72646541/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/leave/7795330/49612075/xyzzy  [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Alejandro Hernandez Samaniego March 31, 2020, 12:55 a.m.
Hey Peter,

On 3/30/2020 5:35 PM, Alejandro Hernandez Samaniego wrote:
>
> Hey Peter,
>
> Yeah that seems reasonable, will sent a v2 in a bit.
>
> Alejandro
>
> On 3/30/2020 3:07 AM, Peter Kjellerstedt wrote:
>>> -----Original Message-----
>>> From:docs@lists.yoctoproject.org  <docs@lists.yoctoproject.org>  On Behalf
>>> Ofalhe@linux.microsoft.com
>>> Sent: den 30 mars 2020 07:43
>>> To:docs@lists.yoctoproject.org
>>> Cc:richard.purdie@linuxfoundation.org
>>> Subject: [docs] [PATCH 2/4] dev-manual: Document the WSLv2 install process
>>>
>>> Signed-off-by: Alejandro Hernandez Samaniego<alejandro@enedino.org>
>>> Signed-off-by: Alejandro Hernandez Samaniego<alhe@linux.microsoft.com>
>>> ---
>>>   documentation/dev-manual/dev-manual-start.xml | 145 +++++++++++++++++-
>>>   1 file changed, 139 insertions(+), 6 deletions(-)
>>>
>>> diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
>>> index 8d2f316f52..a588a37f06 100644
>>> --- a/documentation/dev-manual/dev-manual-start.xml
>>> +++ b/documentation/dev-manual/dev-manual-start.xml
>>> @@ -394,16 +394,16 @@
>>>           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
>> Please restore the above as it was.
>>
>>>           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

Actually restoring te above does not make sense, its missing a ",", but 
I dont think it should say "or it can" several times.


Cheers,

Alejandro

>>> +        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>.
>> Change to:
>>
>>              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>.
>>
>> //Peter
>>
>>>           </note>
>>>       </para>
>>>
>>> @@ -654,6 +654,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'>
>>> --
>>> 2.17.1
>>
>>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.

View/Reply Online (#123): https://lists.yoctoproject.org/g/docs/message/123
Mute This Topic: https://lists.yoctoproject.org/mt/72646541/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/leave/7795330/49612075/xyzzy  [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-