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