blob: e9d995c61b5560f5c922f9c577fefe8ff1891160 [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
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
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
40- Ubuntu 16.04 (LTS)
41
42- Ubuntu 18.04 (LTS)
43
William A. Kennington IIIac69b482021-06-02 12:28:27 -070044- Ubuntu 20.04 (LTS)
Andrew Geisslerc9f78652020-09-18 14:11:35 -050045
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
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050062- openSUSE Leap 15.1
Andrew Geisslerc9f78652020-09-18 14:11:35 -050063
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
William A. Kennington IIIac69b482021-06-02 12:28:27 -070069 supported Linux distribution, you may still encounter problems
70 that happen only with a specific distribution.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050071
72 - Yocto Project releases are tested against the stable Linux
73 distributions in the above list. The Yocto Project should work
74 on other distributions but validation is not performed against
75 them.
76
77 - In particular, the Yocto Project does not support and currently
78 has no plans to support rolling-releases or development
79 distributions due to their constantly changing nature. We welcome
80 patches and bug reports, but keep in mind that our priority is on
81 the supported platforms listed below.
82
83 - You may use Windows Subsystem For Linux v2 to set up a build host
84 using Windows 10, but validation is not performed against build
85 hosts using WSLv2.
86
87 - The Yocto Project is not compatible with WSLv1, it is
88 compatible but not officially supported nor validated with
89 WSLv2, if you still decide to use WSL please upgrade to WSLv2.
90
Andrew Geissler4c19ea12020-10-27 13:52:24 -050091 - If you encounter problems, please go to :yocto_bugs:`Yocto Project
92 Bugzilla <>` and submit a bug. We are
Andrew Geisslerc9f78652020-09-18 14:11:35 -050093 interested in hearing about your experience. For information on
94 how to submit a bug, see the Yocto Project
Andrew Geissler09209ee2020-12-13 08:44:15 -060095 :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>`
96 and the ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050097 section in the Yocto Project Development Tasks Manual.
98
99
100Required Packages for the Build Host
101====================================
102
103The list of packages you need on the host development system can be
104large when covering all build scenarios using the Yocto Project. This
105section describes required packages according to Linux distribution and
106function.
107
108.. _ubuntu-packages:
109
110Ubuntu and Debian
111-----------------
112
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700113Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114supported Ubuntu or Debian Linux distribution:
115
116.. note::
117
118 - If your build system has the ``oss4-dev`` package installed, you
119 might experience QEMU build failures due to the package installing
120 its own custom ``/usr/include/linux/soundcard.h`` on the Debian
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700121 system. If you run into this situation, try either of these solutions::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500122
123 $ sudo apt-get build-dep qemu
124 $ sudo apt-get remove oss4-dev
125
126 - For Debian-8, ``python3-git`` and ``pylint3`` are no longer
127 available via ``apt-get``.
128 ::
129
130 $ sudo pip3 install GitPython pylint==1.9.5
131
Andrew Geisslerc926e172021-05-07 16:11:35 -0500132- *Essentials:* Packages needed to build an image on a headless system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500133
134 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
135
136- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500137 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500138
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500139 $ sudo apt-get install make python3-pip
140 &PIP3_HOST_PACKAGES_DOC;
141
142 .. note::
143
144 It is currently not possible to build out documentation from Debian 8
145 (Jessie) because of outdated ``pip3`` and ``python3``. ``python3-sphinx``
146 is too outdated.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500147
148Fedora Packages
149---------------
150
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700151Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500152supported Fedora Linux distribution:
153
154- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500155 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500156
157 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
158
159- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500160 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500161
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500162 $ sudo dnf install make python3-pip which
163 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500164
165openSUSE Packages
166-----------------
167
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700168Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500169supported openSUSE Linux distribution:
170
171- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500172 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173
174 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
175
176- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500177 Yocto Project documentation manuals::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500178
179 $ sudo zypper install make python3-pip which
180 &PIP3_HOST_PACKAGES_DOC;
181
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500182
183CentOS-7 Packages
184-----------------
185
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700186Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187supported CentOS-7 Linux distribution:
188
189- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500190 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500191
192 $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
193
194 .. note::
195
196 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
197 a collection of packages from Fedora built on RHEL/CentOS for
198 easy installation of packages not included in enterprise Linux
199 by default. You need to install these packages separately.
200
201 - The ``makecache`` command consumes additional Metadata from
202 ``epel-release``.
203
204- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500205 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500206
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500207 $ sudo yum install make python3-pip which
208 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500209
210CentOS-8 Packages
211-----------------
212
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700213Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500214supported CentOS-8 Linux distribution:
215
216- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500217 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500218
219 $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
220
221 .. note::
222
223 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
224 a collection of packages from Fedora built on RHEL/CentOS for
225 easy installation of packages not included in enterprise Linux
226 by default. You need to install these packages separately.
227
228 - The ``PowerTools`` repo provides additional packages such as
229 ``rpcgen`` and ``texinfo``.
230
231 - The ``makecache`` command consumes additional Metadata from
232 ``epel-release``.
233
234- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500235 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500236
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500237 $ sudo dnf install make python3-pip which
238 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500239
240Required Git, tar, Python and gcc Versions
241==========================================
242
243In order to use the build system, your host development system must meet
244the following version requirements for Git, tar, and Python:
245
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500246- Git &MIN_GIT_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500247
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500248- tar &MIN_TAR_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500249
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500250- Python &MIN_PYTHON_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500251
252If your host development system does not meet all these requirements,
253you can resolve this by installing a ``buildtools`` tarball that
254contains these tools. You can get the tarball one of two ways: download
255a pre-built tarball or use BitBake to build the tarball.
256
257In addition, your host development system must meet the following
258version requirement for gcc:
259
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500260- gcc &MIN_GCC_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261
262If your host development system does not meet this requirement, you can
263resolve this by installing a ``buildtools-extended`` tarball that
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500264contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
265package.
266
267In the sections that follow, three different methods will be described for
268installing the ``buildtools`` or ``buildtools-extended`` toolset.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500269
270Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
271--------------------------------------------------------------------------------
272
273The ``install-buildtools`` script is the easiest of the three methods by
274which you can get these tools. It downloads a pre-built buildtools
275installer and automatically installs the tools for you:
276
Andrew Geisslerc926e172021-05-07 16:11:35 -05002771. Execute the ``install-buildtools`` script. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500278
279 $ cd poky
280 $ scripts/install-buildtools --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``.