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