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