blob: 5e5c105d6285999aa6668fe97a850ad9e17c7e0d [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
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
Andrew Geissler5199d832021-09-24 16:47:35 -0500280 $ scripts/install-buildtools \
281 --without-extended-buildtools \
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500282 --base-url &YOCTO_DL_URL;/releases/yocto \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500283 --release yocto-&DISTRO; \
284 --installer-version &DISTRO;
285
286 During execution, the buildtools tarball will be downloaded, the
287 checksum of the download will be verified, the installer will be run
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500288 for you, and some basic checks will be run to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500289 installation is functional.
290
291 To avoid the need of ``sudo`` privileges, the ``install-buildtools``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500292 script will by default tell the installer to install in::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500293
294 /path/to/poky/buildtools
295
296 If your host development system needs the additional tools provided
297 in the ``buildtools-extended`` tarball, you can instead execute the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500298 ``install-buildtools`` script with the default parameters::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500299
300 $ cd poky
301 $ scripts/install-buildtools
302
3032. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500304 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500305
306 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
307
308 Of course, you need to supply your installation directory and be sure to
309 use the right file (i.e. i586 or x86_64).
310
311 After you have sourced the setup script, the tools are added to
312 ``PATH`` and any other environment variables required to run the
313 tools are initialized. The results are working versions versions of
314 Git, tar, Python and ``chrpath``. And in the case of the
315 ``buildtools-extended`` tarball, additional working versions of tools
316 including ``gcc``, ``make`` and the other tools included in
317 ``packagegroup-core-buildessential``.
318
319Downloading a Pre-Built ``buildtools`` Tarball
320----------------------------------------------
321
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500322If you would prefer not to use the ``install-buildtools`` script, you can instead
323download and run a pre-built buildtools installer yourself with the following
324steps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500325
3261. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
327
3282. Execute the installation script. Here is an example for the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500329 traditional installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500330
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600331 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500332
Andrew Geisslerc926e172021-05-07 16:11:35 -0500333 Here is an example for the extended installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500334
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600335 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500336
337 During execution, a prompt appears that allows you to choose the
338 installation directory. For example, you could choose the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500339 ``/home/your-username/buildtools``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500340
3413. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500342 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500343
344 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux
345
346 Of
347 course, you need to supply your installation directory and be sure to
348 use the right file (i.e. i585 or x86-64).
349
350 After you have sourced the setup script, the tools are added to
351 ``PATH`` and any other environment variables required to run the
352 tools are initialized. The results are working versions versions of
353 Git, tar, Python and ``chrpath``. And in the case of the
354 ``buildtools-extended`` tarball, additional working versions of tools
355 including ``gcc``, ``make`` and the other tools included in
356 ``packagegroup-core-buildessential``.
357
358Building Your Own ``buildtools`` Tarball
359----------------------------------------
360
361Building and running your own buildtools installer applies only when you
362have a build host that can already run BitBake. In this case, you use
363that machine to build the ``.sh`` file and then take steps to transfer
364and run it on a machine that does not meet the minimal Git, tar, and
365Python (or gcc) requirements.
366
367Here are the steps to take to build and run your own buildtools
368installer:
369
3701. On the machine that is able to run BitBake, be sure you have set up
371 your build environment with the setup script
372 (:ref:`structure-core-script`).
373
Andrew Geisslerc926e172021-05-07 16:11:35 -05003742. Run the BitBake command to build the tarball::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500375
376 $ bitbake buildtools-tarball
377
Andrew Geisslerc926e172021-05-07 16:11:35 -0500378 or run the BitBake command to build the extended tarball::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500379
380 $ bitbake buildtools-extended-tarball
381
382 .. note::
383
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500384 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines
385 whether you build tools for a 32-bit or 64-bit system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500386
387 Once the build completes, you can find the ``.sh`` file that installs
388 the tools in the ``tmp/deploy/sdk`` subdirectory of the
389 :term:`Build Directory`. The installer file has the string
390 "buildtools" (or "buildtools-extended") in the name.
391
3923. Transfer the ``.sh`` file from the build host to the machine that
393 does not meet the Git, tar, or Python (or gcc) requirements.
394
3954. On the machine that does not meet the requirements, run the ``.sh``
396 file to install the tools. Here is an example for the traditional
Andrew Geisslerc926e172021-05-07 16:11:35 -0500397 installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500398
399 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
400
Andrew Geisslerc926e172021-05-07 16:11:35 -0500401 Here is an example for the extended installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500402
403 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
404
405 During execution, a prompt appears that allows you to choose the
406 installation directory. For example, you could choose the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500407 ``/home/your_username/buildtools``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500408
4095. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500410 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500411
412 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
413
414 Of course, you need to supply your installation directory and be sure to
415 use the right file (i.e. i586 or x86_64).
416
417 After you have sourced the setup script, the tools are added to
418 ``PATH`` and any other environment variables required to run the
419 tools are initialized. The results are working versions versions of
420 Git, tar, Python and ``chrpath``. And in the case of the
421 ``buildtools-extended`` tarball, additional working versions of tools
422 including ``gcc``, ``make`` and the other tools included in
423 ``packagegroup-core-buildessential``.