blob: d7b7cec283459dd895704aea71ffbba003bb38f2 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3*******************
4System Requirements
5*******************
6
Andrew Geissler5199d832021-09-24 16:47:35 -05007Welcome to the Yocto Project Reference Manual. This manual provides
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008reference 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060018":ref:`overview-manual/development-environment:the yocto project development environment`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050019chapter 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060023: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`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050026
27.. note::
28
29 For more information about the Yocto Project Documentation set, see
Andrew Geissler4c19ea12020-10-27 13:52:24 -050030 the :ref:`ref-manual/resources:links and related documentation` section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050031
32.. _detailed-supported-distros:
33
34Supported Linux Distributions
35=============================
36
37Currently, the Yocto Project is supported on the following
38distributions:
39
Andrew Geisslerc9f78652020-09-18 14:11:35 -050040- Ubuntu 18.04 (LTS)
41
William A. Kennington IIIac69b482021-06-02 12:28:27 -070042- Ubuntu 20.04 (LTS)
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043
Andrew Geissler595f6302022-01-24 19:11:47 +000044- Fedora 33
Andrew Geisslerc9f78652020-09-18 14:11:35 -050045
Andrew Geissler595f6302022-01-24 19:11:47 +000046- Fedora 34
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047
48- CentOS 7.x
49
50- CentOS 8.x
51
52- Debian GNU/Linux 8.x (Jessie)
53
54- Debian GNU/Linux 9.x (Stretch)
55
56- Debian GNU/Linux 10.x (Buster)
57
Andrew Geissler595f6302022-01-24 19:11:47 +000058- Debian GNU/Linux 11.x (Bullseye)
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059
Andrew Geissler595f6302022-01-24 19:11:47 +000060- OpenSUSE Leap 15.1
61
62- OpenSUSE Leap 15.2
Andrew Geisslerc9f78652020-09-18 14:11:35 -050063
64.. note::
65
66 - While the Yocto Project Team attempts to ensure all Yocto Project
67 releases are one hundred percent compatible with each officially
William A. Kennington IIIac69b482021-06-02 12:28:27 -070068 supported Linux distribution, you may still encounter problems
69 that happen only with a specific distribution.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050070
71 - Yocto Project releases are tested against the stable Linux
72 distributions in the above list. The Yocto Project should work
73 on other distributions but validation is not performed against
74 them.
75
76 - In particular, the Yocto Project does not support and currently
77 has no plans to support rolling-releases or development
78 distributions due to their constantly changing nature. We welcome
79 patches and bug reports, but keep in mind that our priority is on
80 the supported platforms listed below.
81
82 - You may use Windows Subsystem For Linux v2 to set up a build host
83 using Windows 10, but validation is not performed against build
84 hosts using WSLv2.
85
86 - The Yocto Project is not compatible with WSLv1, it is
87 compatible but not officially supported nor validated with
88 WSLv2, if you still decide to use WSL please upgrade to WSLv2.
89
Andrew Geissler4c19ea12020-10-27 13:52:24 -050090 - If you encounter problems, please go to :yocto_bugs:`Yocto Project
91 Bugzilla <>` and submit a bug. We are
Andrew Geisslerc9f78652020-09-18 14:11:35 -050092 interested in hearing about your experience. For information on
93 how to submit a bug, see the Yocto Project
Andrew Geissler09209ee2020-12-13 08:44:15 -060094 :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>`
95 and the ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050096 section in the Yocto Project Development Tasks Manual.
97
98
99Required Packages for the Build Host
100====================================
101
102The list of packages you need on the host development system can be
103large when covering all build scenarios using the Yocto Project. This
104section describes required packages according to Linux distribution and
105function.
106
107.. _ubuntu-packages:
108
109Ubuntu and Debian
110-----------------
111
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700112Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113supported Ubuntu or Debian Linux distribution:
114
115.. note::
116
117 - If your build system has the ``oss4-dev`` package installed, you
118 might experience QEMU build failures due to the package installing
119 its own custom ``/usr/include/linux/soundcard.h`` on the Debian
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700120 system. If you run into this situation, try either of these solutions::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500121
Andrew Geisslereff27472021-10-29 15:35:00 -0500122 $ sudo apt build-dep qemu
123 $ sudo apt remove oss4-dev
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500124
125 - For Debian-8, ``python3-git`` and ``pylint3`` are no longer
Andrew Geisslereff27472021-10-29 15:35:00 -0500126 available via ``apt``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500127 ::
128
129 $ sudo pip3 install GitPython pylint==1.9.5
130
Andrew Geisslerc926e172021-05-07 16:11:35 -0500131- *Essentials:* Packages needed to build an image on a headless system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500132
Andrew Geisslereff27472021-10-29 15:35:00 -0500133 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500134
135- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500136 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500137
Andrew Geisslereff27472021-10-29 15:35:00 -0500138 $ sudo apt install make python3-pip
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500139 &PIP3_HOST_PACKAGES_DOC;
140
141 .. note::
142
143 It is currently not possible to build out documentation from Debian 8
144 (Jessie) because of outdated ``pip3`` and ``python3``. ``python3-sphinx``
145 is too outdated.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500146
147Fedora Packages
148---------------
149
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700150Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500151supported Fedora Linux distribution:
152
153- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500154 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500155
156 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
157
158- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500159 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500160
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500161 $ sudo dnf install make python3-pip which
162 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500163
164openSUSE Packages
165-----------------
166
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700167Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500168supported openSUSE Linux distribution:
169
170- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500171 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500172
173 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
174
175- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500176 Yocto Project documentation manuals::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500177
178 $ sudo zypper install make python3-pip which
179 &PIP3_HOST_PACKAGES_DOC;
180
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181
182CentOS-7 Packages
183-----------------
184
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700185Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500186supported CentOS-7 Linux distribution:
187
188- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500189 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500190
191 $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
192
193 .. note::
194
195 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
196 a collection of packages from Fedora built on RHEL/CentOS for
197 easy installation of packages not included in enterprise Linux
198 by default. You need to install these packages separately.
199
200 - The ``makecache`` command consumes additional Metadata from
201 ``epel-release``.
202
203- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500204 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500205
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500206 $ sudo yum install make python3-pip which
207 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500208
209CentOS-8 Packages
210-----------------
211
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700212Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500213supported CentOS-8 Linux distribution:
214
215- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500216 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500217
218 $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
219
220 .. note::
221
222 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
223 a collection of packages from Fedora built on RHEL/CentOS for
224 easy installation of packages not included in enterprise Linux
225 by default. You need to install these packages separately.
226
227 - The ``PowerTools`` repo provides additional packages such as
228 ``rpcgen`` and ``texinfo``.
229
230 - The ``makecache`` command consumes additional Metadata from
231 ``epel-release``.
232
233- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500234 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500235
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500236 $ sudo dnf install make python3-pip which
237 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500238
239Required Git, tar, Python and gcc Versions
240==========================================
241
242In order to use the build system, your host development system must meet
243the following version requirements for Git, tar, and Python:
244
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500245- Git &MIN_GIT_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500246
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500247- tar &MIN_TAR_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500248
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500249- Python &MIN_PYTHON_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500250
251If your host development system does not meet all these requirements,
252you can resolve this by installing a ``buildtools`` tarball that
253contains these tools. You can get the tarball one of two ways: download
254a pre-built tarball or use BitBake to build the tarball.
255
256In addition, your host development system must meet the following
257version requirement for gcc:
258
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500259- gcc &MIN_GCC_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260
261If your host development system does not meet this requirement, you can
262resolve this by installing a ``buildtools-extended`` tarball that
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500263contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
264package.
265
266In the sections that follow, three different methods will be described for
267installing the ``buildtools`` or ``buildtools-extended`` toolset.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500268
269Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
270--------------------------------------------------------------------------------
271
272The ``install-buildtools`` script is the easiest of the three methods by
273which you can get these tools. It downloads a pre-built buildtools
274installer and automatically installs the tools for you:
275
Andrew Geisslerc926e172021-05-07 16:11:35 -05002761. Execute the ``install-buildtools`` script. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500277
278 $ cd poky
Andrew Geissler5199d832021-09-24 16:47:35 -0500279 $ scripts/install-buildtools \
280 --without-extended-buildtools \
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500281 --base-url &YOCTO_DL_URL;/releases/yocto \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500282 --release yocto-&DISTRO; \
283 --installer-version &DISTRO;
284
285 During execution, the buildtools tarball will be downloaded, the
286 checksum of the download will be verified, the installer will be run
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500287 for you, and some basic checks will be run to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500288 installation is functional.
289
290 To avoid the need of ``sudo`` privileges, the ``install-buildtools``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500291 script will by default tell the installer to install in::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500292
293 /path/to/poky/buildtools
294
295 If your host development system needs the additional tools provided
296 in the ``buildtools-extended`` tarball, you can instead execute the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500297 ``install-buildtools`` script with the default parameters::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500298
299 $ cd poky
300 $ scripts/install-buildtools
301
3022. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500303 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500304
305 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
306
307 Of course, you need to supply your installation directory and be sure to
308 use the right file (i.e. i586 or x86_64).
309
310 After you have sourced the setup script, the tools are added to
311 ``PATH`` and any other environment variables required to run the
312 tools are initialized. The results are working versions versions of
313 Git, tar, Python and ``chrpath``. And in the case of the
314 ``buildtools-extended`` tarball, additional working versions of tools
315 including ``gcc``, ``make`` and the other tools included in
316 ``packagegroup-core-buildessential``.
317
318Downloading a Pre-Built ``buildtools`` Tarball
319----------------------------------------------
320
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500321If you would prefer not to use the ``install-buildtools`` script, you can instead
322download and run a pre-built buildtools installer yourself with the following
323steps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500324
3251. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
326
3272. Execute the installation script. Here is an example for the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500328 traditional installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500329
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600330 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500331
Andrew Geisslerc926e172021-05-07 16:11:35 -0500332 Here is an example for the extended installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500333
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600334 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500335
336 During execution, a prompt appears that allows you to choose the
337 installation directory. For example, you could choose the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500338 ``/home/your-username/buildtools``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500339
3403. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500341 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500342
343 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux
344
345 Of
346 course, you need to supply your installation directory and be sure to
347 use the right file (i.e. i585 or x86-64).
348
349 After you have sourced the setup script, the tools are added to
350 ``PATH`` and any other environment variables required to run the
351 tools are initialized. The results are working versions versions of
352 Git, tar, Python and ``chrpath``. And in the case of the
353 ``buildtools-extended`` tarball, additional working versions of tools
354 including ``gcc``, ``make`` and the other tools included in
355 ``packagegroup-core-buildessential``.
356
357Building Your Own ``buildtools`` Tarball
358----------------------------------------
359
360Building and running your own buildtools installer applies only when you
361have a build host that can already run BitBake. In this case, you use
362that machine to build the ``.sh`` file and then take steps to transfer
363and run it on a machine that does not meet the minimal Git, tar, and
364Python (or gcc) requirements.
365
366Here are the steps to take to build and run your own buildtools
367installer:
368
3691. On the machine that is able to run BitBake, be sure you have set up
370 your build environment with the setup script
371 (:ref:`structure-core-script`).
372
Andrew Geisslerc926e172021-05-07 16:11:35 -05003732. Run the BitBake command to build the tarball::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500374
375 $ bitbake buildtools-tarball
376
Andrew Geisslerc926e172021-05-07 16:11:35 -0500377 or run the BitBake command to build the extended tarball::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500378
379 $ bitbake buildtools-extended-tarball
380
381 .. note::
382
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500383 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines
384 whether you build tools for a 32-bit or 64-bit system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385
386 Once the build completes, you can find the ``.sh`` file that installs
387 the tools in the ``tmp/deploy/sdk`` subdirectory of the
388 :term:`Build Directory`. The installer file has the string
389 "buildtools" (or "buildtools-extended") in the name.
390
3913. Transfer the ``.sh`` file from the build host to the machine that
392 does not meet the Git, tar, or Python (or gcc) requirements.
393
3944. On the machine that does not meet the requirements, run the ``.sh``
395 file to install the tools. Here is an example for the traditional
Andrew Geisslerc926e172021-05-07 16:11:35 -0500396 installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500397
398 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
399
Andrew Geisslerc926e172021-05-07 16:11:35 -0500400 Here is an example for the extended installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500401
402 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
403
404 During execution, a prompt appears that allows you to choose the
405 installation directory. For example, you could choose the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500406 ``/home/your_username/buildtools``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500407
4085. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500409 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500410
411 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
412
413 Of course, you need to supply your installation directory and be sure to
414 use the right file (i.e. i586 or x86_64).
415
416 After you have sourced the setup script, the tools are added to
417 ``PATH`` and any other environment variables required to run the
418 tools are initialized. The results are working versions versions of
419 Git, tar, Python and ``chrpath``. And in the case of the
420 ``buildtools-extended`` tarball, additional working versions of tools
421 including ``gcc``, ``make`` and the other tools included in
422 ``packagegroup-core-buildessential``.