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 32.. _detailed-supported-distros: 33 34Supported Linux Distributions 35============================= 36 37Currently, the Yocto Project is supported on the following 38distributions: 39 40- Ubuntu 18.04 (LTS) 41 42- Ubuntu 20.04 (LTS) 43 44- Ubuntu 22.04 (LTS) 45 46- Fedora 34 47 48- Fedora 35 49 50- Fedora 36 51 52- CentOS 7.x 53 54- CentOS 8.x 55 56- AlmaLinux 8.5 57 58- AlmaLinux 8.7 59 60- Debian GNU/Linux 9.x (Stretch) 61 62- Debian GNU/Linux 10.x (Buster) 63 64- Debian GNU/Linux 11.x (Bullseye) 65 66- OpenSUSE Leap 15.3 67 68.. note:: 69 70 - While the Yocto Project Team attempts to ensure all Yocto Project 71 releases are one hundred percent compatible with each officially 72 supported Linux distribution, you may still encounter problems 73 that happen only with a specific distribution. 74 75 - Yocto Project releases are tested against the stable Linux 76 distributions in the above list. The Yocto Project should work 77 on other distributions but validation is not performed against 78 them. 79 80 - In particular, the Yocto Project does not support and currently 81 has no plans to support rolling-releases or development 82 distributions due to their constantly changing nature. We welcome 83 patches and bug reports, but keep in mind that our priority is on 84 the supported platforms listed below. 85 86 - You may use Windows Subsystem For Linux v2 to set up a build host 87 using Windows 10, but validation is not performed against build 88 hosts using WSLv2. 89 90 - The Yocto Project is not compatible with WSLv1, it is 91 compatible but not officially supported nor validated with 92 WSLv2, if you still decide to use WSL please upgrade to WSLv2. 93 94 - If you encounter problems, please go to :yocto_bugs:`Yocto Project 95 Bugzilla <>` and submit a bug. We are 96 interested in hearing about your experience. For information on 97 how to submit a bug, see the Yocto Project 98 :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>` 99 and the ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`" 100 section in the Yocto Project Development Tasks Manual. 101 102 103Required Packages for the Build Host 104==================================== 105 106The list of packages you need on the host development system can be 107large when covering all build scenarios using the Yocto Project. This 108section describes required packages according to Linux distribution and 109function. 110 111.. _ubuntu-packages: 112 113Ubuntu and Debian 114----------------- 115 116Here are the required packages by function given a 117supported Ubuntu or Debian Linux distribution: 118 119.. note:: 120 121 - If your build system has the ``oss4-dev`` package installed, you 122 might experience QEMU build failures due to the package installing 123 its own custom ``/usr/include/linux/soundcard.h`` on the Debian 124 system. If you run into this situation, try either of these solutions:: 125 126 $ sudo apt build-dep qemu 127 $ sudo apt remove oss4-dev 128 129 - For Debian-8, ``python3-git`` and ``pylint3`` are no longer 130 available via ``apt``. 131 :: 132 133 $ sudo pip3 install GitPython pylint==1.9.5 134 135- *Essentials:* Packages needed to build an image on a headless system:: 136 137 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL; 138 139- *Documentation:* Packages needed if you are going to build out the 140 Yocto Project documentation manuals:: 141 142 $ sudo apt install make python3-pip 143 &PIP3_HOST_PACKAGES_DOC; 144 145 .. note:: 146 147 It is currently not possible to build out documentation from Debian 8 148 (Jessie) because of outdated ``pip3`` and ``python3``. ``python3-sphinx`` 149 is too outdated. 150 151Fedora Packages 152--------------- 153 154Here are the required packages by function given a 155supported Fedora Linux distribution: 156 157- *Essentials:* Packages needed to build an image for a headless 158 system:: 159 160 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; 161 162- *Documentation:* Packages needed if you are going to build out the 163 Yocto Project documentation manuals:: 164 165 $ sudo dnf install make python3-pip which 166 &PIP3_HOST_PACKAGES_DOC; 167 168openSUSE Packages 169----------------- 170 171Here are the required packages by function given a 172supported openSUSE Linux distribution: 173 174- *Essentials:* Packages needed to build an image for a headless 175 system:: 176 177 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; 178 179- *Documentation:* Packages needed if you are going to build out the 180 Yocto Project documentation manuals:: 181 182 $ sudo zypper install make python3-pip which 183 &PIP3_HOST_PACKAGES_DOC; 184 185 186CentOS-7 Packages 187----------------- 188 189Here are the required packages by function given a 190supported CentOS-7 Linux distribution: 191 192- *Essentials:* Packages needed to build an image for a headless 193 system:: 194 195 $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL; 196 197 .. note:: 198 199 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is 200 a collection of packages from Fedora built on RHEL/CentOS for 201 easy installation of packages not included in enterprise Linux 202 by default. You need to install these packages separately. 203 204 - The ``makecache`` command consumes additional Metadata from 205 ``epel-release``. 206 207- *Documentation:* Packages needed if you are going to build out the 208 Yocto Project documentation manuals:: 209 210 $ sudo yum install make python3-pip which 211 &PIP3_HOST_PACKAGES_DOC; 212 213CentOS-8 Packages 214----------------- 215 216Here are the required packages by function given a 217supported CentOS-8 Linux distribution: 218 219- *Essentials:* Packages needed to build an image for a headless 220 system:: 221 222 $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL; 223 224 .. note:: 225 226 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is 227 a collection of packages from Fedora built on RHEL/CentOS for 228 easy installation of packages not included in enterprise Linux 229 by default. You need to install these packages separately. 230 231 - The ``PowerTools`` repo provides additional packages such as 232 ``rpcgen`` and ``texinfo``. 233 234 - The ``makecache`` command consumes additional Metadata from 235 ``epel-release``. 236 237- *Documentation:* Packages needed if you are going to build out the 238 Yocto Project documentation manuals:: 239 240 $ sudo dnf install make python3-pip which 241 &PIP3_HOST_PACKAGES_DOC; 242 243Required Git, tar, Python and gcc Versions 244========================================== 245 246In order to use the build system, your host development system must meet 247the following version requirements for Git, tar, and Python: 248 249- Git &MIN_GIT_VERSION; or greater 250 251- tar &MIN_TAR_VERSION; or greater 252 253- Python &MIN_PYTHON_VERSION; or greater 254 255If your host development system does not meet all these requirements, 256you can resolve this by installing a ``buildtools`` tarball that 257contains these tools. You can get the tarball one of two ways: download 258a pre-built tarball or use BitBake to build the tarball. 259 260In addition, your host development system must meet the following 261version requirement for gcc: 262 263- gcc &MIN_GCC_VERSION; or greater 264 265If your host development system does not meet this requirement, you can 266resolve this by installing a ``buildtools-extended`` tarball that 267contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential`` 268package. 269 270In the sections that follow, three different methods will be described for 271installing the ``buildtools`` or ``buildtools-extended`` toolset. 272 273Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script 274-------------------------------------------------------------------------------- 275 276The ``install-buildtools`` script is the easiest of the three methods by 277which you can get these tools. It downloads a pre-built buildtools 278installer and automatically installs the tools for you: 279 2801. Execute the ``install-buildtools`` script. Here is an example:: 281 282 $ cd poky 283 $ scripts/install-buildtools \ 284 --without-extended-buildtools \ 285 --base-url &YOCTO_DL_URL;/releases/yocto \ 286 --release yocto-&DISTRO; \ 287 --installer-version &DISTRO; 288 289 During execution, the buildtools tarball will be downloaded, the 290 checksum of the download will be verified, the installer will be run 291 for you, and some basic checks will be run to make sure the 292 installation is functional. 293 294 To avoid the need of ``sudo`` privileges, the ``install-buildtools`` 295 script will by default tell the installer to install in:: 296 297 /path/to/poky/buildtools 298 299 If your host development system needs the additional tools provided 300 in the ``buildtools-extended`` tarball, you can instead execute the 301 ``install-buildtools`` script with the default parameters:: 302 303 $ cd poky 304 $ scripts/install-buildtools 305 3062. Source the tools environment setup script by using a command like the 307 following:: 308 309 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux 310 311 Of course, you need to supply your installation directory and be sure to 312 use the right file (i.e. i586 or x86_64). 313 314 After you have sourced the setup script, the tools are added to 315 ``PATH`` and any other environment variables required to run the 316 tools are initialized. The results are working versions versions of 317 Git, tar, Python and ``chrpath``. And in the case of the 318 ``buildtools-extended`` tarball, additional working versions of tools 319 including ``gcc``, ``make`` and the other tools included in 320 ``packagegroup-core-buildessential``. 321 322Downloading a Pre-Built ``buildtools`` Tarball 323---------------------------------------------- 324 325If you would prefer not to use the ``install-buildtools`` script, you can instead 326download and run a pre-built buildtools installer yourself with the following 327steps: 328 3291. Locate and download the ``*.sh`` at :yocto_dl:`/releases/yocto/yocto-&DISTRO;/buildtools/` 330 3312. Execute the installation script. Here is an example for the 332 traditional installer:: 333 334 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh 335 336 Here is an example for the extended installer:: 337 338 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh 339 340 During execution, a prompt appears that allows you to choose the 341 installation directory. For example, you could choose the following: 342 ``/home/your-username/buildtools`` 343 3443. Source the tools environment setup script by using a command like the 345 following:: 346 347 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux 348 349 Of 350 course, you need to supply your installation directory and be sure to 351 use the right file (i.e. i585 or x86-64). 352 353 After you have sourced the setup script, the tools are added to 354 ``PATH`` and any other environment variables required to run the 355 tools are initialized. The results are working versions versions of 356 Git, tar, Python and ``chrpath``. And in the case of the 357 ``buildtools-extended`` tarball, additional working versions of tools 358 including ``gcc``, ``make`` and the other tools included in 359 ``packagegroup-core-buildessential``. 360 361Building Your Own ``buildtools`` Tarball 362---------------------------------------- 363 364Building and running your own buildtools installer applies only when you 365have a build host that can already run BitBake. In this case, you use 366that machine to build the ``.sh`` file and then take steps to transfer 367and run it on a machine that does not meet the minimal Git, tar, and 368Python (or gcc) requirements. 369 370Here are the steps to take to build and run your own buildtools 371installer: 372 3731. On the machine that is able to run BitBake, be sure you have set up 374 your build environment with the setup script 375 (:ref:`structure-core-script`). 376 3772. Run the BitBake command to build the tarball:: 378 379 $ bitbake buildtools-tarball 380 381 or run the BitBake command to build the extended tarball:: 382 383 $ bitbake buildtools-extended-tarball 384 385 .. note:: 386 387 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines 388 whether you build tools for a 32-bit or 64-bit system. 389 390 Once the build completes, you can find the ``.sh`` file that installs 391 the tools in the ``tmp/deploy/sdk`` subdirectory of the 392 :term:`Build Directory`. The installer file has the string 393 "buildtools" (or "buildtools-extended") in the name. 394 3953. Transfer the ``.sh`` file from the build host to the machine that 396 does not meet the Git, tar, or Python (or gcc) requirements. 397 3984. On the machine that does not meet the requirements, run the ``.sh`` 399 file to install the tools. Here is an example for the traditional 400 installer:: 401 402 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh 403 404 Here is an example for the extended installer:: 405 406 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh 407 408 During execution, a prompt appears that allows you to choose the 409 installation directory. For example, you could choose the following: 410 ``/home/your_username/buildtools`` 411 4125. Source the tools environment setup script by using a command like the 413 following:: 414 415 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux 416 417 Of course, you need to supply your installation directory and be sure to 418 use the right file (i.e. i586 or x86_64). 419 420 After you have sourced the setup script, the tools are added to 421 ``PATH`` and any other environment variables required to run the 422 tools are initialized. The results are working versions versions of 423 Git, tar, Python and ``chrpath``. And in the case of the 424 ``buildtools-extended`` tarball, additional working versions of tools 425 including ``gcc``, ``make`` and the other tools included in 426 ``packagegroup-core-buildessential``. 427