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