mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-06-01 13:09:50 +00:00
Code Issues Projects Releases Wiki Activity

manuals: updates for building on Windows (WSL 2)

Browse Source 
- Use the Wikipedia naming scheme: WSL 2 instead of WSLv2
- Take into account Windows Server 2019 and 2022 which are
  supported too.
- Improve some explanations

(From yocto-docs rev: e64c1154c358128d76b1b8e3a5809dbaa8dc6881)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reviewed-by: Quentin Schulz <foss@0leil.net>
Signed-off-by: Steve Sakoman <steve@sakoman.com>
This commit is contained in:
Michael Opdenacker
2022-10-14 13:50:51 +02:00
committed by Steve Sakoman
parent 2fb92fb14f
commit 54321fcec4
4 changed files with 51 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/brief-yoctoprojectqs/index.rst
+5 -12
View File
@@ -25,18 +25,11 @@ build a reference embedded OS called Poky.
in the Yocto Project Development Tasks Manual for more in the Yocto Project Development Tasks Manual for more
information. information.
- You may use Windows Subsystem For Linux v2 to set up a build host - You may use version 2 of Windows Subsystem For Linux (WSL 2) to set
using Windows 10. up a build host using Windows 10 or later, Windows Server 2019 or later.
See the :ref:`dev-manual/start:setting up to use windows subsystem for
.. note:: linux (wsl 2)` section in the Yocto Project Development Tasks Manual
for more information.
The Yocto Project is not compatible with WSLv1, it is
compatible but not officially supported nor validated with
WSLv2, if you still decide to use WSL please upgrade to WSLv2.
See the :ref:`dev-manual/start:setting up to use windows
subsystem for linux (wslv2)` section in the Yocto Project Development
Tasks Manual for more information.
If you want more conceptual or background information on the Yocto If you want more conceptual or background information on the Yocto
Project, see the :doc:`/overview-manual/index`. Project, see the :doc:`/overview-manual/index`.
documentation/dev-manual/start.rst
+35 -37
View File
@@ -254,16 +254,16 @@ development using the Yocto Project. Your build host can be a native
Linux machine (recommended), it can be a machine (Linux, Mac, or Linux machine (recommended), it can be a machine (Linux, Mac, or
Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, Windows) that uses `CROPS <https://github.com/crops/poky-container>`__,
which leverages `Docker Containers <https://www.docker.com/>`__ or it which leverages `Docker Containers <https://www.docker.com/>`__ or it
can be a Windows machine capable of running Windows Subsystem For Linux can be a Windows machine capable of running version 2 of Windows Subsystem
v2 (WSL). For Linux (WSL 2).
.. note:: .. note::
The Yocto Project is not compatible with The Yocto Project is not compatible with version 1 of
`Windows Subsystem for Linux v1 <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__. `Windows Subsystem for Linux <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__.
It is compatible but not officially supported nor validated with It is compatible but neither officially supported nor validated with
WSLv2. If you still decide to use WSL please upgrade to WSL 2. If you still decide to use WSL please upgrade to
`WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__. `WSL 2 <https://learn.microsoft.com/en-us/windows/wsl/install>`__.
Once your build host is set up to use the Yocto Project, further steps Once your build host is set up to use the Yocto Project, further steps
are necessary depending on what you want to accomplish. See the are necessary depending on what you want to accomplish. See the
@@ -434,35 +434,36 @@ the `Yocto Project BitBake
<https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
extension accordingly. extension accordingly.
Setting Up to Use Windows Subsystem For Linux (WSLv2) Setting Up to Use Windows Subsystem For Linux (WSL 2)
----------------------------------------------------- -----------------------------------------------------
With `Windows Subsystem for Linux With `Windows Subsystem for Linux (WSL 2)
(WSLv2) <https://docs.microsoft.com/en-us/windows/wsl/wsl2-about>`__, <https://learn.microsoft.com/en-us/windows/wsl/>`__,
you can create a Yocto Project development environment that allows you you can create a Yocto Project development environment that allows you
to build on Windows. You can set up a Linux distribution inside Windows to build on Windows. You can set up a Linux distribution inside Windows
in which you can develop using the Yocto Project. in which you can develop using the Yocto Project.
Follow these general steps to prepare a Windows machine using WSLv2 as Follow these general steps to prepare a Windows machine using WSL 2 as
your Yocto Project build host: your Yocto Project build host:
1. *Make sure your Windows 10 machine is capable of running WSLv2:* 1. *Make sure your Windows machine is capable of running WSL 2:*
WSLv2 is only available for Windows 10 builds > 18917. To check which
build version you are running, you may open a command prompt on While all Windows 11 and Windows Server 2022 builds support WSL 2,
Windows and execute the command "ver". the first versions of Windows 10 and Windows Server 2019 didn't.
:: Check the minimum build numbers for `Windows 10
<https://learn.microsoft.com/en-us/windows/wsl/install-manual#step-2---check-requirements-for-running-wsl-2>`__
and for `Windows Server 2019
<https://learn.microsoft.com/en-us/windows/wsl/install-on-server>`__.
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 C:\Users\myuser> ver
Microsoft Windows [Version 10.0.19041.153] Microsoft Windows [Version 10.0.19041.153]
If your build is capable of running 2. *Install the Linux distribution of your choice inside WSL 2:*
WSLv2 you may continue, for more information on this subject or Once you know your version of Windows supports WSL 2, you can
instructions on how to upgrade to WSLv2 visit `Windows 10
WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__
2. *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. install the distribution of your choice from the Microsoft Store.
Open the Microsoft Store and search for Linux. While there are Open the Microsoft Store and search for Linux. While there are
several Linux distributions available, the assumption is that your several Linux distributions available, the assumption is that your
@@ -471,31 +472,28 @@ your Yocto Project build host:
making your selection, simply click "Get" to download and install the making your selection, simply click "Get" to download and install the
distribution. distribution.
3. *Check your Linux distribution is using WSLv2:* Open a Windows 3. *Check which Linux distribution WSL 2 is using:* Open a Windows
PowerShell and run:: PowerShell and run::
C:\WINDOWS\system32> wsl -l -v C:\WINDOWS\system32> wsl -l -v
NAME STATE VERSION NAME STATE VERSION
*Ubuntu Running 2 *Ubuntu Running 2
Note the version column which says the WSL version Note that WSL 2 supports running as many different Linux distributions
being used by your distribution, on compatible systems, this can be as you want to install.
changed back at any point in time.
4. *Optionally Orient Yourself on WSL:* If you are unfamiliar with WSL, 4. *Optionally Get Familiar with WSL:* You can learn more on
you can learn more here -
https://docs.microsoft.com/en-us/windows/wsl/wsl2-about. https://docs.microsoft.com/en-us/windows/wsl/wsl2-about.
5. *Launch your WSL Distibution:* From the Windows start menu simply 5. *Launch your WSL Distibution:* From the Windows start menu simply
launch your WSL distribution just like any other application. launch your WSL distribution just like any other application.
6. *Optimize your WSLv2 storage often:* Due to the way storage is 6. *Optimize your WSL 2 storage often:* Due to the way storage is
handled on WSLv2, the storage space used by the undelying Linux handled on WSL 2, the storage space used by the underlying Linux
distribution is not reflected immedately, and since bitbake heavily distribution is not reflected immediately, and since BitBake heavily
uses storage, after several builds, you may be unaware you are uses storage, after several builds, you may be unaware you are
running out of space. WSLv2 uses a VHDX file for storage, this issue running out of space. As WSL 2 uses a VHDX file for storage, this issue
can be easily avoided by manually optimizing this file often, this can be easily avoided by regularly optimizing this file in a manual way:
can be done in the following way:
1. *Find the location of your VHDX file:* 1. *Find the location of your VHDX file:*
@@ -549,14 +547,14 @@ your Yocto Project build host:
.. note:: .. note::
The current implementation of WSLv2 does not have out-of-the-box The current implementation of WSL 2 does not have out-of-the-box
access to external devices such as those connected through a USB access to external devices such as those connected through a USB
port, but it automatically mounts your ``C:`` drive on ``/mnt/c/`` port, but it automatically mounts your ``C:`` drive on ``/mnt/c/``
(and others), which you can use to share deploy artifacts to be later (and others), which you can use to share deploy artifacts to be later
flashed on hardware through Windows, but your build directory should flashed on hardware through Windows, but your build directory should
not reside inside this mountpoint. not reside inside this mountpoint.
Once you have WSLv2 set up, everything is in place to develop just as if Once you have WSL 2 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 you were running on a native Linux machine. If you are going to use the
Extensible SDK container, see the ":doc:`/sdk-manual/extensible`" Chapter in the Yocto Extensible SDK container, see the ":doc:`/sdk-manual/extensible`" Chapter in the Yocto
Project Application Development and the Extensible Software Development Project Application Development and the Extensible Software Development
documentation/overview-manual/yp-intro.rst
+6 -11
View File
@@ -596,20 +596,15 @@ Build Host runs, you have several choices.
":ref:`dev-manual/start:setting up to use cross platforms (crops)`" ":ref:`dev-manual/start:setting up to use cross platforms (crops)`"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
- *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem - *Windows Subsystem For Linux (WSL 2):* You may use Windows Subsystem
For Linux v2 to set up a Build Host using Windows 10. For Linux version 2 to set up a Build Host using Windows 10 or later,
or Windows Server 2019 or later.
.. note:: The Windows Subsystem For Linux allows Windows to run a real Linux
The Yocto Project is not compatible with WSLv1, it is compatible
but not officially supported nor validated with WSLv2, if you
still decide to use WSL please upgrade to WSLv2.
The Windows Subsystem For Linux allows Windows 10 to run a real Linux
kernel inside of a lightweight virtual machine (VM). kernel inside of a lightweight virtual machine (VM).
For information on how to set up a Build Host with WSLv2, see the For information on how to set up a Build Host with WSL 2, see the
":ref:`dev-manual/start:setting up to use windows subsystem for linux (wslv2)`" ":ref:`dev-manual/start:setting up to use windows subsystem for linux (wsl 2)`"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
- *Toaster:* Regardless of what your Build Host is running, you can use - *Toaster:* Regardless of what your Build Host is running, you can use
documentation/ref-manual/system-requirements.rst
+5 -5
View File
@@ -127,12 +127,12 @@ tested on former revisions of "&DISTRO_NAME;", but no longer are:
the ":ref:`system-requirements-buildtools`" section. the ":ref:`system-requirements-buildtools`" section.
- You may use Windows Subsystem For Linux v2 to set up a build host - You may use Windows Subsystem For Linux v2 to set up a build host
using Windows 10, but validation is not performed against build using Windows 10 or later, or Windows Server 2019 or later, but validation
hosts using WSLv2. is not performed against build hosts using WSL 2.
- The Yocto Project is not compatible with WSLv1, it is See the
compatible but not officially supported nor validated with :ref:`dev-manual/start:setting up to use windows subsystem for linux (wsl 2)`
WSLv2, if you still decide to use WSL please upgrade to WSLv2. section in the Yocto Project Development Tasks Manual for more information.
- If you encounter problems, please go to :yocto_bugs:`Yocto Project - If you encounter problems, please go to :yocto_bugs:`Yocto Project
Bugzilla <>` and submit a bug. We are Bugzilla <>` and submit a bug. We are