1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3******************* 4System Requirements 5******************* 6 7Welcome to the Yocto Project Reference Manual. This manual provides 8reference information for the current release of the Yocto Project, and 9is most effectively used after you have an understanding of the basics 10of the Yocto Project. The manual is neither meant to be read as a 11starting point to the Yocto Project, nor read from start to finish. 12Rather, use this manual to find variable definitions, class 13descriptions, and so forth as needed during the course of using the 14Yocto Project. 15 16For introductory information on the Yocto Project, see the 17:yocto_home:`Yocto Project Website <>` and the 18":ref:`overview-manual/development-environment:the yocto project development environment`" 19chapter in the Yocto Project Overview and Concepts Manual. 20 21If you want to use the Yocto Project to quickly build an image without 22having to understand concepts, work through the 23:doc:`/brief-yoctoprojectqs/index` document. You can find "how-to" 24information in the :doc:`/dev-manual/index`. You can find Yocto Project overview 25and conceptual information in the :doc:`/overview-manual/index`. 26 27.. note:: 28 29 For more information about the Yocto Project Documentation set, see 30 the :ref:`ref-manual/resources:links and related documentation` section. 31 32Minimum Free Disk Space 33======================= 34 35To build an image such as ``core-image-sato`` for the ``qemux86-64`` machine, 36you need a system with at least &MIN_DISK_SPACE; Gbytes of free disk space. 37However, much more disk space will be necessary to build more complex images, 38to run multiple builds and to cache build artifacts, improving build efficiency. 39 40If you have a shortage of disk space, see the ":doc:`/dev-manual/disk-space`" 41section of the Development Tasks Manual. 42 43.. _system-requirements-minimum-ram: 44 45Minimum System RAM 46================== 47 48You will manage to build an image such as ``core-image-sato`` for the 49``qemux86-64`` machine with as little as &MIN_RAM; Gbytes of RAM on an old 50system with 4 CPU cores, but your builds will be much faster on a system with 51as much RAM and as many CPU cores as possible. 52 53.. _system-requirements-supported-distros: 54 55Supported Linux Distributions 56============================= 57 58Currently, the &DISTRO; release ("&DISTRO_NAME;") of the Yocto Project is 59supported on the following distributions: 60 61- Ubuntu 22.04 (LTS) 62 63- Ubuntu 24.04 (LTS) 64 65- Ubuntu 24.10 66 67- Fedora 39 68 69- Fedora 40 70 71- Fedora 41 72 73- CentOS Stream 9 74 75- Debian GNU/Linux 11 (Bullseye) 76 77- Debian GNU/Linux 12 (Bookworm) 78 79- OpenSUSE Leap 15.5 80 81- OpenSUSE Leap 15.6 82 83- AlmaLinux 8 84 85- AlmaLinux 9 86 87- Rocky 8 88 89- Rocky 9 90 91The following distribution versions are still tested, even though the 92organizations publishing them no longer make updates publicly available: 93 94- Ubuntu 18.04 (LTS) 95 96- Ubuntu 20.04 (LTS) 97 98- Ubuntu 23.04 99 100Note that the Yocto Project doesn't have access to private updates 101that some of these versions may have. Therefore, our testing has 102limited value if you have access to such updates. Also, :term:`buildtools` 103may have to be used on older releases in order to get current enough 104tools, such as python. 105 106Finally, here are the distribution versions which were previously 107tested on former revisions of "&DISTRO_NAME;", but no longer are: 108 109*This list is currently empty* 110 111.. note:: 112 113 - While the Yocto Project Team attempts to ensure all Yocto Project 114 releases are one hundred percent compatible with each officially 115 supported Linux distribution, you may still encounter problems 116 that happen only with a specific distribution. 117 118 - Yocto Project releases are tested against the stable Linux 119 distributions in the above list. The Yocto Project should work 120 on other distributions but validation is not performed against 121 them. 122 123 - In particular, the Yocto Project does not support and currently 124 has no plans to support rolling-releases or development 125 distributions due to their constantly changing nature. We welcome 126 patches and bug reports, but keep in mind that our priority is on 127 the supported platforms listed above. 128 129 - If your Linux distribution is not in the above list, we recommend to 130 get the :term:`buildtools` or :term:`buildtools-extended` tarballs 131 containing the host tools required by your Yocto Project release, 132 typically by running ``scripts/install-buildtools`` as explained in 133 the ":ref:`system-requirements-buildtools`" section. 134 135 - You may use Windows Subsystem For Linux v2 to set up a build host 136 using Windows 10 or later, or Windows Server 2019 or later, but validation 137 is not performed against build hosts using WSL 2. 138 139 See the 140 :ref:`dev-manual/start:setting up to use windows subsystem for linux (wsl 2)` 141 section in the Yocto Project Development Tasks Manual for more information. 142 143 - If you encounter problems, please go to :yocto_bugs:`Yocto Project 144 Bugzilla <>` and submit a bug. We are 145 interested in hearing about your experience. For information on 146 how to submit a bug, see the Yocto Project 147 :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>` 148 and the ":doc:`../contributor-guide/report-defect`" 149 section in the Yocto Project and OpenEmbedded Contributor Guide. 150 151Required Packages for the Build Host 152==================================== 153 154The list of packages you need on the host development system can be 155large when covering all build scenarios using the Yocto Project. This 156section describes required packages according to Linux distribution and 157function. 158 159.. _ubuntu-packages: 160 161Ubuntu and Debian 162----------------- 163 164Here are the packages needed to build an image on a headless system 165with a supported Ubuntu or Debian Linux distribution: 166 167.. literalinclude:: ../tools/host_packages_scripts/ubuntu_essential.sh 168 :language: shell 169 170You also need to ensure you have the ``en_US.UTF-8`` locale enabled:: 171 172 $ locale --all-locales | grep en_US.utf8 173 174If this is not the case, you can reconfigure the ``locales`` package to add it 175(requires an interactive shell):: 176 177 $ sudo dpkg-reconfigure locales 178 179.. note:: 180 181 - If you are not in an interactive shell, ``dpkg-reconfigure`` will 182 not work as expected. To add the locale you will need to edit 183 ``/etc/locale.gen`` file to add/uncomment the ``en_US.UTF-8`` locale. 184 A naive way to do this as root is:: 185 186 $ echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen 187 $ locale-gen 188 189 - If your build system has the ``oss4-dev`` package installed, you 190 might experience QEMU build failures due to the package installing 191 its own custom ``/usr/include/linux/soundcard.h`` on the Debian 192 system. If you run into this situation, try either of these solutions:: 193 194 $ sudo apt build-dep qemu 195 $ sudo apt remove oss4-dev 196 197Here are the packages needed to build Project documentation manuals: 198 199.. literalinclude:: ../tools/host_packages_scripts/ubuntu_docs.sh 200 :language: shell 201 202In addition to the previous packages, here are the packages needed to build the 203documentation in PDF format: 204 205.. literalinclude:: ../tools/host_packages_scripts/ubuntu_docs_pdf.sh 206 :language: shell 207 208Fedora Packages 209--------------- 210 211Here are the packages needed to build an image on a headless system 212with a supported Fedora Linux distribution: 213 214.. literalinclude:: ../tools/host_packages_scripts/fedora_essential.sh 215 :language: shell 216 217Here are the packages needed to build Project documentation manuals: 218 219.. literalinclude:: ../tools/host_packages_scripts/fedora_docs.sh 220 :language: shell 221 222.. literalinclude:: ../tools/host_packages_scripts/pip3_docs.sh 223 :language: shell 224 225In addition to the previous packages, here are the packages needed to build the 226documentation in PDF format: 227 228.. literalinclude:: ../tools/host_packages_scripts/fedora_docs_pdf.sh 229 :language: shell 230 231openSUSE Packages 232----------------- 233 234Here are the packages needed to build an image on a headless system 235with a supported openSUSE distribution: 236 237.. literalinclude:: ../tools/host_packages_scripts/opensuse_essential.sh 238 :language: shell 239 240Here are the packages needed to build Project documentation manuals: 241 242.. literalinclude:: ../tools/host_packages_scripts/opensuse_docs.sh 243 :language: shell 244 245.. literalinclude:: ../tools/host_packages_scripts/pip3_docs.sh 246 :language: shell 247 248In addition to the previous packages, here are the packages needed to build the 249documentation in PDF format: 250 251.. literalinclude:: ../tools/host_packages_scripts/opensuse_docs_pdf.sh 252 :language: shell 253 254AlmaLinux Packages 255------------------ 256 257Here are the packages needed to build an image on a headless system 258with a supported AlmaLinux distribution: 259 260.. literalinclude:: ../tools/host_packages_scripts/almalinux_essential.sh 261 :language: shell 262 263.. note:: 264 265 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is 266 a collection of packages from Fedora built on RHEL/CentOS for 267 easy installation of packages not included in enterprise Linux 268 by default. You need to install these packages separately. 269 270 - The ``PowerTools/CRB`` repo provides additional packages such as 271 ``rpcgen`` and ``texinfo``. 272 273 - The ``makecache`` command consumes additional Metadata from 274 ``epel-release``. 275 276Here are the packages needed to build Project documentation manuals: 277 278.. literalinclude:: ../tools/host_packages_scripts/almalinux_docs.sh 279 :language: shell 280 281.. literalinclude:: ../tools/host_packages_scripts/pip3_docs.sh 282 :language: shell 283 284.. warning:: 285 286 Unlike Fedora or OpenSUSE, AlmaLinux does not provide the packages 287 ``texlive-collection-fontsextra``, ``texlive-collection-lang*`` and 288 ``texlive-collection-latexextra``, so you may run into issues. These may be 289 installed using `tlmgr <https://tug.org/texlive/tlmgr.html>`_. 290 291In addition to the previous packages, here are the packages needed to build the 292documentation in PDF format: 293 294.. literalinclude:: ../tools/host_packages_scripts/almalinux_docs_pdf.sh 295 :language: shell 296 297.. _system-requirements-buildtools: 298 299Required Git, tar, Python, make and gcc Versions 300================================================ 301 302In order to use the build system, your host development system must meet 303the following version requirements for Git, tar, and Python: 304 305- Git &MIN_GIT_VERSION; or greater 306 307- tar &MIN_TAR_VERSION; or greater 308 309- Python &MIN_PYTHON_VERSION; or greater 310 311- GNU make &MIN_MAKE_VERSION; or greater 312 313If your host development system does not meet all these requirements, 314you can resolve this by installing a :term:`buildtools` tarball that 315contains these tools. You can either download a pre-built tarball or 316use BitBake to build one. 317 318In addition, your host development system must meet the following 319version requirement for gcc: 320 321- gcc &MIN_GCC_VERSION; or greater 322 323If your host development system does not meet this requirement, you can 324resolve this by installing a :term:`buildtools-extended` tarball that 325contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential`` 326package. 327 328For systems with a broken make version (e.g. make 4.2.1 without patches) but 329where the rest of the host tools are usable, you can use the :term:`buildtools-make` 330tarball instead. 331 332In the sections that follow, three different methods will be described for 333installing the :term:`buildtools`, :term:`buildtools-extended` or :term:`buildtools-make` 334toolset. 335 336Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script 337-------------------------------------------------------------------------------- 338 339The ``install-buildtools`` script is the easiest of the three methods by 340which you can get these tools. It downloads a pre-built :term:`buildtools` 341installer and automatically installs the tools for you: 342 343#. Execute the ``install-buildtools`` script. Here is an example:: 344 345 $ cd poky 346 $ scripts/install-buildtools \ 347 --without-extended-buildtools \ 348 --base-url &YOCTO_DL_URL;/releases/yocto \ 349 --release yocto-&DISTRO; \ 350 --installer-version &DISTRO; 351 352 During execution, the :term:`buildtools` tarball will be downloaded, the 353 checksum of the download will be verified, the installer will be run 354 for you, and some basic checks will be run to make sure the 355 installation is functional. 356 357 To avoid the need of ``sudo`` privileges, the ``install-buildtools`` 358 script will by default tell the installer to install in:: 359 360 /path/to/poky/buildtools 361 362 If your host development system needs the additional tools provided 363 in the :term:`buildtools-extended` tarball, you can instead execute the 364 ``install-buildtools`` script with the default parameters:: 365 366 $ cd poky 367 $ scripts/install-buildtools 368 369 Alternatively if your host development system has a broken ``make`` 370 version such that you only need a known good version of ``make``, 371 you can use the ``--make-only`` option:: 372 373 $ cd poky 374 $ scripts/install-buildtools --make-only 375 376#. Source the tools environment setup script by using a command like the 377 following:: 378 379 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux 380 381 After you have sourced the setup script, the tools are added to 382 ``PATH`` and any other environment variables required to run the 383 tools are initialized. The results are working versions versions of 384 Git, tar, Python and ``chrpath``. And in the case of the 385 :term:`buildtools-extended` tarball, additional working versions of tools 386 including ``gcc``, ``make`` and the other tools included in 387 ``packagegroup-core-buildessential``. 388 389Downloading a Pre-Built ``buildtools`` Tarball 390---------------------------------------------- 391 392If you would prefer not to use the ``install-buildtools`` script, you can instead 393download and run a pre-built :term:`buildtools` installer yourself with the following 394steps: 395 396#. Go to :yocto_dl:`/releases/yocto/&DISTRO_REL_LATEST_TAG;/buildtools/`, locate and 397 download the ``.sh`` file corresponding to your host architecture 398 and to :term:`buildtools`, :term:`buildtools-extended` or :term:`buildtools-make`. 399 400#. Execute the installation script. Here is an example for the 401 traditional installer:: 402 403 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh 404 405 Here is an example for the extended installer:: 406 407 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh 408 409 An example for the make-only installer:: 410 411 $ sh ~/Downloads/x86_64-buildtools-make-nativesdk-standalone-&DISTRO;.sh 412 413 During execution, a prompt appears that allows you to choose the 414 installation directory. For example, you could choose the following: 415 ``/home/your-username/buildtools`` 416 417#. As instructed by the installer script, you will have to source the tools 418 environment setup script:: 419 420 $ source /home/your_username/buildtools/environment-setup-x86_64-pokysdk-linux 421 422 After you have sourced the setup script, the tools are added to 423 ``PATH`` and any other environment variables required to run the 424 tools are initialized. The results are working versions versions of 425 Git, tar, Python and ``chrpath``. And in the case of the 426 :term:`buildtools-extended` tarball, additional working versions of tools 427 including ``gcc``, ``make`` and the other tools included in 428 ``packagegroup-core-buildessential``. 429 430Building Your Own ``buildtools`` Tarball 431---------------------------------------- 432 433Building and running your own :term:`buildtools` installer applies only when you 434have a build host that can already run BitBake. In this case, you use 435that machine to build the ``.sh`` file and then take steps to transfer 436and run it on a machine that does not meet the minimal Git, tar, and 437Python (or gcc) requirements. 438 439Here are the steps to take to build and run your own :term:`buildtools` 440installer: 441 442#. On the machine that is able to run BitBake, be sure you have set up 443 your build environment with the setup script 444 (:ref:`structure-core-script`). 445 446#. Run the BitBake command to build the tarball:: 447 448 $ bitbake buildtools-tarball 449 450 or to build the extended tarball:: 451 452 $ bitbake buildtools-extended-tarball 453 454 or to build the make-only tarball:: 455 456 $ bitbake buildtools-make-tarball 457 458 .. note:: 459 460 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines 461 whether you build tools for a 32-bit or 64-bit system. 462 463 Once the build completes, you can find the ``.sh`` file that installs 464 the tools in the ``tmp/deploy/sdk`` subdirectory of the 465 :term:`Build Directory`. The installer file has the string 466 "buildtools" or "buildtools-extended" in the name. 467 468#. Transfer the ``.sh`` file from the build host to the machine that 469 does not meet the Git, tar, or Python (or gcc) requirements. 470 471#. On this machine, run the ``.sh`` file to install the tools. Here is an 472 example for the traditional installer:: 473 474 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh 475 476 For the extended installer:: 477 478 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh 479 480 And for the make-only installer:: 481 482 $ sh ~/Downloads/x86_64-buildtools-make-nativesdk-standalone-&DISTRO;.sh 483 484 During execution, a prompt appears that allows you to choose the 485 installation directory. For example, you could choose the following: 486 ``/home/your_username/buildtools`` 487 488#. Source the tools environment setup script by using a command like the 489 following:: 490 491 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux 492 493 After you have sourced the setup script, the tools are added to 494 ``PATH`` and any other environment variables required to run the 495 tools are initialized. The results are working versions versions of 496 Git, tar, Python and ``chrpath``. And in the case of the 497 :term:`buildtools-extended` tarball, additional working versions of tools 498 including ``gcc``, ``make`` and the other tools included in 499 ``packagegroup-core-buildessential``. 500