diff options
Diffstat (limited to 'documentation/dev-manual/start.rst')
-rw-r--r-- | documentation/dev-manual/start.rst | 70 |
1 files changed, 34 insertions, 36 deletions
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst index 6816ce5846..23d5643d12 100644 --- a/documentation/dev-manual/start.rst +++ b/documentation/dev-manual/start.rst | |||
@@ -267,16 +267,16 @@ development using the Yocto Project. Your build host can be a native | |||
267 | Linux machine (recommended), it can be a machine (Linux, Mac, or | 267 | Linux machine (recommended), it can be a machine (Linux, Mac, or |
268 | Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, | 268 | Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, |
269 | which leverages `Docker Containers <https://www.docker.com/>`__ or it | 269 | which leverages `Docker Containers <https://www.docker.com/>`__ or it |
270 | can be a Windows machine capable of running Windows Subsystem For Linux | 270 | can be a Windows machine capable of running version 2 of Windows Subsystem |
271 | v2 (WSL). | 271 | For Linux (WSL 2). |
272 | 272 | ||
273 | .. note:: | 273 | .. note:: |
274 | 274 | ||
275 | The Yocto Project is not compatible with | 275 | The Yocto Project is not compatible with version 1 of |
276 | `Windows Subsystem for Linux v1 <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__. | 276 | `Windows Subsystem for Linux <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__. |
277 | It is compatible but not officially supported nor validated with | 277 | It is compatible but neither officially supported nor validated with |
278 | WSLv2. If you still decide to use WSL please upgrade to | 278 | WSL 2. If you still decide to use WSL please upgrade to |
279 | `WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__. | 279 | `WSL 2 <https://learn.microsoft.com/en-us/windows/wsl/install>`__. |
280 | 280 | ||
281 | Once your build host is set up to use the Yocto Project, further steps | 281 | Once your build host is set up to use the Yocto Project, further steps |
282 | are necessary depending on what you want to accomplish. See the | 282 | are necessary depending on what you want to accomplish. See the |
@@ -441,35 +441,36 @@ Kit (eSDK) manual. If you are going to use the Toaster container, see | |||
441 | the ":doc:`/toaster-manual/setup-and-use`" | 441 | the ":doc:`/toaster-manual/setup-and-use`" |
442 | section in the Toaster User Manual. | 442 | section in the Toaster User Manual. |
443 | 443 | ||
444 | Setting Up to Use Windows Subsystem For Linux (WSLv2) | 444 | Setting Up to Use Windows Subsystem For Linux (WSL 2) |
445 | ----------------------------------------------------- | 445 | ----------------------------------------------------- |
446 | 446 | ||
447 | With `Windows Subsystem for Linux | 447 | With `Windows Subsystem for Linux (WSL 2) |
448 | (WSLv2) <https://docs.microsoft.com/en-us/windows/wsl/wsl2-about>`__, | 448 | <https://learn.microsoft.com/en-us/windows/wsl/>`__, |
449 | you can create a Yocto Project development environment that allows you | 449 | you can create a Yocto Project development environment that allows you |
450 | to build on Windows. You can set up a Linux distribution inside Windows | 450 | to build on Windows. You can set up a Linux distribution inside Windows |
451 | in which you can develop using the Yocto Project. | 451 | in which you can develop using the Yocto Project. |
452 | 452 | ||
453 | Follow these general steps to prepare a Windows machine using WSLv2 as | 453 | Follow these general steps to prepare a Windows machine using WSL 2 as |
454 | your Yocto Project build host: | 454 | your Yocto Project build host: |
455 | 455 | ||
456 | 1. *Make sure your Windows 10 machine is capable of running WSLv2:* | 456 | 1. *Make sure your Windows machine is capable of running WSL 2:* |
457 | WSLv2 is only available for Windows 10 builds > 18917. To check which | 457 | |
458 | build version you are running, you may open a command prompt on | 458 | While all Windows 11 and Windows Server 2022 builds support WSL 2, |
459 | Windows and execute the command "ver". | 459 | the first versions of Windows 10 and Windows Server 2019 didn't. |
460 | :: | 460 | Check the minimum build numbers for `Windows 10 |
461 | <https://learn.microsoft.com/en-us/windows/wsl/install-manual#step-2---check-requirements-for-running-wsl-2>`__ | ||
462 | and for `Windows Server 2019 | ||
463 | <https://learn.microsoft.com/en-us/windows/wsl/install-on-server>`__. | ||
464 | |||
465 | To check which build version you are running, you may open a command | ||
466 | prompt on Windows and execute the command "ver":: | ||
461 | 467 | ||
462 | C:\Users\myuser> ver | 468 | C:\Users\myuser> ver |
463 | 469 | ||
464 | Microsoft Windows [Version 10.0.19041.153] | 470 | Microsoft Windows [Version 10.0.19041.153] |
465 | 471 | ||
466 | If your build is capable of running | 472 | 2. *Install the Linux distribution of your choice inside WSL 2:* |
467 | WSLv2 you may continue, for more information on this subject or | 473 | Once you know your version of Windows supports WSL 2, you can |
468 | instructions on how to upgrade to WSLv2 visit `Windows 10 | ||
469 | WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__ | ||
470 | |||
471 | 2. *Install the Linux distribution of your choice inside Windows 10:* | ||
472 | Once you know your version of Windows 10 supports WSLv2, you can | ||
473 | install the distribution of your choice from the Microsoft Store. | 474 | install the distribution of your choice from the Microsoft Store. |
474 | Open the Microsoft Store and search for Linux. While there are | 475 | Open the Microsoft Store and search for Linux. While there are |
475 | several Linux distributions available, the assumption is that your | 476 | several Linux distributions available, the assumption is that your |
@@ -478,31 +479,28 @@ your Yocto Project build host: | |||
478 | making your selection, simply click "Get" to download and install the | 479 | making your selection, simply click "Get" to download and install the |
479 | distribution. | 480 | distribution. |
480 | 481 | ||
481 | 3. *Check your Linux distribution is using WSLv2:* Open a Windows | 482 | 3. *Check which Linux distribution WSL 2 is using:* Open a Windows |
482 | PowerShell and run:: | 483 | PowerShell and run:: |
483 | 484 | ||
484 | C:\WINDOWS\system32> wsl -l -v | 485 | C:\WINDOWS\system32> wsl -l -v |
485 | NAME STATE VERSION | 486 | NAME STATE VERSION |
486 | *Ubuntu Running 2 | 487 | *Ubuntu Running 2 |
487 | 488 | ||
488 | Note the version column which says the WSL version | 489 | Note that WSL 2 supports running as many different Linux distributions |
489 | being used by your distribution, on compatible systems, this can be | 490 | as you want to install. |
490 | changed back at any point in time. | ||
491 | 491 | ||
492 | 4. *Optionally Orient Yourself on WSL:* If you are unfamiliar with WSL, | 492 | 4. *Optionally Get Familiar with WSL:* You can learn more on |
493 | you can learn more here - | ||
494 | https://docs.microsoft.com/en-us/windows/wsl/wsl2-about. | 493 | https://docs.microsoft.com/en-us/windows/wsl/wsl2-about. |
495 | 494 | ||
496 | 5. *Launch your WSL Distibution:* From the Windows start menu simply | 495 | 5. *Launch your WSL Distibution:* From the Windows start menu simply |
497 | launch your WSL distribution just like any other application. | 496 | launch your WSL distribution just like any other application. |
498 | 497 | ||
499 | 6. *Optimize your WSLv2 storage often:* Due to the way storage is | 498 | 6. *Optimize your WSL 2 storage often:* Due to the way storage is |
500 | handled on WSLv2, the storage space used by the underlying Linux | 499 | handled on WSL 2, the storage space used by the underlying Linux |
501 | distribution is not reflected immediately, and since BitBake heavily | 500 | distribution is not reflected immediately, and since BitBake heavily |
502 | uses storage, after several builds, you may be unaware you are | 501 | uses storage, after several builds, you may be unaware you are |
503 | running out of space. WSLv2 uses a VHDX file for storage, this issue | 502 | running out of space. As WSL 2 uses a VHDX file for storage, this issue |
504 | can be easily avoided by manually optimizing this file often, this | 503 | can be easily avoided by regularly optimizing this file in a manual way: |
505 | can be done in the following way: | ||
506 | 504 | ||
507 | 1. *Find the location of your VHDX file:* | 505 | 1. *Find the location of your VHDX file:* |
508 | 506 | ||
@@ -556,14 +554,14 @@ your Yocto Project build host: | |||
556 | 554 | ||
557 | .. note:: | 555 | .. note:: |
558 | 556 | ||
559 | The current implementation of WSLv2 does not have out-of-the-box | 557 | The current implementation of WSL 2 does not have out-of-the-box |
560 | access to external devices such as those connected through a USB | 558 | access to external devices such as those connected through a USB |
561 | port, but it automatically mounts your ``C:`` drive on ``/mnt/c/`` | 559 | port, but it automatically mounts your ``C:`` drive on ``/mnt/c/`` |
562 | (and others), which you can use to share deploy artifacts to be later | 560 | (and others), which you can use to share deploy artifacts to be later |
563 | flashed on hardware through Windows, but your build directory should | 561 | flashed on hardware through Windows, but your build directory should |
564 | not reside inside this mountpoint. | 562 | not reside inside this mountpoint. |
565 | 563 | ||
566 | Once you have WSLv2 set up, everything is in place to develop just as if | 564 | Once you have WSL 2 set up, everything is in place to develop just as if |
567 | you were running on a native Linux machine. If you are going to use the | 565 | you were running on a native Linux machine. If you are going to use the |
568 | Extensible SDK container, see the ":doc:`/sdk-manual/extensible`" Chapter in the Yocto | 566 | Extensible SDK container, see the ":doc:`/sdk-manual/extensible`" Chapter in the Yocto |
569 | Project Application Development and the Extensible Software Development | 567 | Project Application Development and the Extensible Software Development |