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 &MIN_GIT_VERSION; or greater 260 261- tar &MIN_TAR_VERSION; or greater 262 263- Python &MIN_PYTHON_VERSION; 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 &MIN_GCC_VERSION; 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 the Debian/Ubuntu ``build-essential`` 278package. 279 280In the sections that follow, three different methods will be described for 281installing the ``buildtools`` or ``buildtools-extended`` toolset. 282 283Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script 284-------------------------------------------------------------------------------- 285 286The ``install-buildtools`` script is the easiest of the three methods by 287which you can get these tools. It downloads a pre-built buildtools 288installer and automatically installs the tools for you: 289 2901. Execute the ``install-buildtools`` script. Here is an example: 291 :: 292 293 $ cd poky 294 $ scripts/install-buildtools --without-extended-buildtools \ 295 --base-url &YOCTO_DL_URL;/releases/yocto \ 296 --release yocto-&DISTRO; \ 297 --installer-version &DISTRO; 298 299 During execution, the buildtools tarball will be downloaded, the 300 checksum of the download will be verified, the installer will be run 301 for you, and some basic checks will be run to make sure the 302 installation is functional. 303 304 To avoid the need of ``sudo`` privileges, the ``install-buildtools`` 305 script will by default tell the installer to install in: 306 :: 307 308 /path/to/poky/buildtools 309 310 If your host development system needs the additional tools provided 311 in the ``buildtools-extended`` tarball, you can instead execute the 312 ``install-buildtools`` script with the default parameters: 313 :: 314 315 $ cd poky 316 $ scripts/install-buildtools 317 3182. Source the tools environment setup script by using a command like the 319 following: 320 :: 321 322 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux 323 324 Of course, you need to supply your installation directory and be sure to 325 use the right file (i.e. i586 or x86_64). 326 327 After you have sourced the setup script, the tools are added to 328 ``PATH`` and any other environment variables required to run the 329 tools are initialized. The results are working versions versions of 330 Git, tar, Python and ``chrpath``. And in the case of the 331 ``buildtools-extended`` tarball, additional working versions of tools 332 including ``gcc``, ``make`` and the other tools included in 333 ``packagegroup-core-buildessential``. 334 335Downloading a Pre-Built ``buildtools`` Tarball 336---------------------------------------------- 337 338If you would prefer not to use the ``install-buildtools`` script, you can instead 339download and run a pre-built buildtools installer yourself with the following 340steps: 341 3421. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/ 343 3442. Execute the installation script. Here is an example for the 345 traditional installer: 346 :: 347 348 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh 349 350 Here is an example for the extended installer: 351 :: 352 353 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh 354 355 During execution, a prompt appears that allows you to choose the 356 installation directory. For example, you could choose the following: 357 ``/home/your-username/buildtools`` 358 3593. Source the tools environment setup script by using a command like the 360 following: 361 :: 362 363 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux 364 365 Of 366 course, you need to supply your installation directory and be sure to 367 use the right file (i.e. i585 or x86-64). 368 369 After you have sourced the setup script, the tools are added to 370 ``PATH`` and any other environment variables required to run the 371 tools are initialized. The results are working versions versions of 372 Git, tar, Python and ``chrpath``. And in the case of the 373 ``buildtools-extended`` tarball, additional working versions of tools 374 including ``gcc``, ``make`` and the other tools included in 375 ``packagegroup-core-buildessential``. 376 377Building Your Own ``buildtools`` Tarball 378---------------------------------------- 379 380Building and running your own buildtools installer applies only when you 381have a build host that can already run BitBake. In this case, you use 382that machine to build the ``.sh`` file and then take steps to transfer 383and run it on a machine that does not meet the minimal Git, tar, and 384Python (or gcc) requirements. 385 386Here are the steps to take to build and run your own buildtools 387installer: 388 3891. On the machine that is able to run BitBake, be sure you have set up 390 your build environment with the setup script 391 (:ref:`structure-core-script`). 392 3932. Run the BitBake command to build the tarball: 394 :: 395 396 $ bitbake buildtools-tarball 397 398 or run the BitBake command to build the extended tarball: 399 :: 400 401 $ bitbake buildtools-extended-tarball 402 403 .. note:: 404 405 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines 406 whether you build tools for a 32-bit or 64-bit system. 407 408 Once the build completes, you can find the ``.sh`` file that installs 409 the tools in the ``tmp/deploy/sdk`` subdirectory of the 410 :term:`Build Directory`. The installer file has the string 411 "buildtools" (or "buildtools-extended") in the name. 412 4133. Transfer the ``.sh`` file from the build host to the machine that 414 does not meet the Git, tar, or Python (or gcc) requirements. 415 4164. On the machine that does not meet the requirements, run the ``.sh`` 417 file to install the tools. Here is an example for the traditional 418 installer: 419 :: 420 421 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh 422 423 Here is an example for the extended installer: 424 :: 425 426 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh 427 428 During execution, a prompt appears that allows you to choose the 429 installation directory. For example, you could choose the following: 430 ``/home/your_username/buildtools`` 431 4325. Source the tools environment setup script by using a command like the 433 following: 434 :: 435 436 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux 437 438 Of course, you need to supply your installation directory and be sure to 439 use the right file (i.e. i586 or x86_64). 440 441 After you have sourced the setup script, the tools are added to 442 ``PATH`` and any other environment variables required to run the 443 tools are initialized. The results are working versions versions of 444 Git, tar, Python and ``chrpath``. And in the case of the 445 ``buildtools-extended`` tarball, additional working versions of tools 446 including ``gcc``, ``make`` and the other tools included in 447 ``packagegroup-core-buildessential``. 448