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