blob: 1502633816f5f4c8578fa6c99411b3c6cd1c7b73 [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
Patrick Williams2194f502022-10-16 14:26:09 -050044- Ubuntu 22.04 (LTS)
45
Andrew Geissler595f6302022-01-24 19:11:47 +000046- Fedora 34
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047
Andrew Geissler9aee5002022-03-30 16:27:02 +000048- Fedora 35
49
Andrew Geissler9aee5002022-03-30 16:27:02 +000050- AlmaLinux 8.5
Andrew Geisslerc9f78652020-09-18 14:11:35 -050051
Andrew Geisslerc9f78652020-09-18 14:11:35 -050052- Debian GNU/Linux 10.x (Buster)
53
Andrew Geissler595f6302022-01-24 19:11:47 +000054- Debian GNU/Linux 11.x (Bullseye)
Andrew Geisslerc9f78652020-09-18 14:11:35 -050055
Andrew Geissler9aee5002022-03-30 16:27:02 +000056- OpenSUSE Leap 15.3
Andrew Geisslerc9f78652020-09-18 14:11:35 -050057
58.. note::
59
60 - While the Yocto Project Team attempts to ensure all Yocto Project
61 releases are one hundred percent compatible with each officially
William A. Kennington IIIac69b482021-06-02 12:28:27 -070062 supported Linux distribution, you may still encounter problems
63 that happen only with a specific distribution.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050064
65 - Yocto Project releases are tested against the stable Linux
66 distributions in the above list. The Yocto Project should work
67 on other distributions but validation is not performed against
68 them.
69
70 - In particular, the Yocto Project does not support and currently
71 has no plans to support rolling-releases or development
72 distributions due to their constantly changing nature. We welcome
73 patches and bug reports, but keep in mind that our priority is on
74 the supported platforms listed below.
75
76 - You may use Windows Subsystem For Linux v2 to set up a build host
Patrick Williams2390b1b2022-11-03 13:47:49 -050077 using Windows 10 or later, or Windows Server 2019 or later, but validation
78 is not performed against build hosts using WSL 2.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050079
Patrick Williams2390b1b2022-11-03 13:47:49 -050080 See the
81 :ref:`dev-manual/start:setting up to use windows subsystem for linux (wsl 2)`
82 section in the Yocto Project Development Tasks Manual for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050083
Andrew Geissler4c19ea12020-10-27 13:52:24 -050084 - If you encounter problems, please go to :yocto_bugs:`Yocto Project
85 Bugzilla <>` and submit a bug. We are
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086 interested in hearing about your experience. For information on
87 how to submit a bug, see the Yocto Project
Andrew Geissler09209ee2020-12-13 08:44:15 -060088 :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>`
89 and the ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090 section in the Yocto Project Development Tasks Manual.
91
92
93Required Packages for the Build Host
94====================================
95
96The list of packages you need on the host development system can be
97large when covering all build scenarios using the Yocto Project. This
98section describes required packages according to Linux distribution and
99function.
100
101.. _ubuntu-packages:
102
103Ubuntu and Debian
104-----------------
105
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700106Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500107supported Ubuntu or Debian Linux distribution:
108
109.. note::
110
111 - If your build system has the ``oss4-dev`` package installed, you
112 might experience QEMU build failures due to the package installing
113 its own custom ``/usr/include/linux/soundcard.h`` on the Debian
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700114 system. If you run into this situation, try either of these solutions::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115
Andrew Geisslereff27472021-10-29 15:35:00 -0500116 $ sudo apt build-dep qemu
117 $ sudo apt remove oss4-dev
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500118
Andrew Geisslerc926e172021-05-07 16:11:35 -0500119- *Essentials:* Packages needed to build an image on a headless system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500120
Andrew Geisslereff27472021-10-29 15:35:00 -0500121 $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500122
123- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500124 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500125
Patrick Williams92b42cb2022-09-03 06:53:57 -0500126 $ sudo apt install make python3-pip inkscape texlive-latex-extra
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500127 &PIP3_HOST_PACKAGES_DOC;
128
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500129Fedora Packages
130---------------
131
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700132Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500133supported Fedora Linux distribution:
134
135- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500136 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500137
138 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
139
140- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500141 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500142
Patrick Williams92b42cb2022-09-03 06:53:57 -0500143 $ sudo dnf install make python3-pip which inkscape texlive-fncychap
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500144 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145
146openSUSE Packages
147-----------------
148
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700149Here are the required packages by function given a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500150supported openSUSE Linux distribution:
151
152- *Essentials:* Packages needed to build an image for a headless
Andrew Geisslerc926e172021-05-07 16:11:35 -0500153 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500154
155 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
156
157- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500158 Yocto Project documentation manuals::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500159
Patrick Williams92b42cb2022-09-03 06:53:57 -0500160 $ sudo zypper install make python3-pip which inkscape texlive-fncychap
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500161 &PIP3_HOST_PACKAGES_DOC;
162
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500163
Patrick Williams92b42cb2022-09-03 06:53:57 -0500164AlmaLinux-8 Packages
165--------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500166
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700167Here are the required packages by function given a
Patrick Williams92b42cb2022-09-03 06:53:57 -0500168supported AlmaLinux-8 Linux distribution:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500169
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 dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
174
175 .. note::
176
177 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
178 a collection of packages from Fedora built on RHEL/CentOS for
179 easy installation of packages not included in enterprise Linux
180 by default. You need to install these packages separately.
181
182 - The ``PowerTools`` repo provides additional packages such as
183 ``rpcgen`` and ``texinfo``.
184
185 - The ``makecache`` command consumes additional Metadata from
186 ``epel-release``.
187
188- *Documentation:* Packages needed if you are going to build out the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500189 Yocto Project documentation manuals::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500190
Patrick Williams92b42cb2022-09-03 06:53:57 -0500191 $ sudo dnf install make python3-pip which inkscape texlive-fncychap
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500192 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500193
Andrew Geissler615f2f12022-07-15 14:00:58 -0500194Required Git, tar, Python, make and gcc Versions
195================================================
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500196
197In order to use the build system, your host development system must meet
198the following version requirements for Git, tar, and Python:
199
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500200- Git &MIN_GIT_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500201
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500202- tar &MIN_TAR_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500203
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500204- Python &MIN_PYTHON_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500205
Andrew Geissler615f2f12022-07-15 14:00:58 -0500206- GNU make &MIN_MAKE_VERSION; or greater
207
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500208If your host development system does not meet all these requirements,
209you can resolve this by installing a ``buildtools`` tarball that
210contains these tools. You can get the tarball one of two ways: download
211a pre-built tarball or use BitBake to build the tarball.
212
213In addition, your host development system must meet the following
214version requirement for gcc:
215
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500216- gcc &MIN_GCC_VERSION; or greater
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500217
218If your host development system does not meet this requirement, you can
219resolve this by installing a ``buildtools-extended`` tarball that
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500220contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
221package.
222
Patrick Williams2390b1b2022-11-03 13:47:49 -0500223For systems with a broken make version (e.g. make 4.2.1 without patches) but
224where the rest of the host tools are usable, you can use the ``buildtools-make``
225tarball instead.
226
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500227In the sections that follow, three different methods will be described for
Patrick Williams2390b1b2022-11-03 13:47:49 -0500228installing the ``buildtools``, ``buildtools-extended`` or ``buildtools-make``
229toolset.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500230
231Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
232--------------------------------------------------------------------------------
233
234The ``install-buildtools`` script is the easiest of the three methods by
235which you can get these tools. It downloads a pre-built buildtools
236installer and automatically installs the tools for you:
237
Andrew Geisslerc926e172021-05-07 16:11:35 -05002381. Execute the ``install-buildtools`` script. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500239
240 $ cd poky
Andrew Geissler5199d832021-09-24 16:47:35 -0500241 $ scripts/install-buildtools \
242 --without-extended-buildtools \
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500243 --base-url &YOCTO_DL_URL;/releases/yocto \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500244 --release yocto-&DISTRO; \
245 --installer-version &DISTRO;
246
247 During execution, the buildtools tarball will be downloaded, the
248 checksum of the download will be verified, the installer will be run
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500249 for you, and some basic checks will be run to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500250 installation is functional.
251
252 To avoid the need of ``sudo`` privileges, the ``install-buildtools``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500253 script will by default tell the installer to install in::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254
255 /path/to/poky/buildtools
256
257 If your host development system needs the additional tools provided
258 in the ``buildtools-extended`` tarball, you can instead execute the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500259 ``install-buildtools`` script with the default parameters::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260
261 $ cd poky
262 $ scripts/install-buildtools
263
Patrick Williams2390b1b2022-11-03 13:47:49 -0500264 Alternatively if your host development system has a broken ``make``
265 version such that you only need a known good version of ``make``,
266 you can use the ``--make-only`` option:
267
268 $ cd poky
269 $ scripts/install-buildtools --make-only
270
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002712. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500272 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500273
274 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
275
276 Of course, you need to supply your installation directory and be sure to
277 use the right file (i.e. i586 or x86_64).
278
279 After you have sourced the setup script, the tools are added to
280 ``PATH`` and any other environment variables required to run the
281 tools are initialized. The results are working versions versions of
282 Git, tar, Python and ``chrpath``. And in the case of the
283 ``buildtools-extended`` tarball, additional working versions of tools
284 including ``gcc``, ``make`` and the other tools included in
285 ``packagegroup-core-buildessential``.
286
287Downloading a Pre-Built ``buildtools`` Tarball
288----------------------------------------------
289
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500290If you would prefer not to use the ``install-buildtools`` script, you can instead
291download and run a pre-built buildtools installer yourself with the following
292steps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500293
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00002941. Locate and download the ``*.sh`` at :yocto_dl:`/releases/yocto/yocto-&DISTRO;/buildtools/`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500295
2962. Execute the installation script. Here is an example for the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500297 traditional installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500298
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600299 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500300
Andrew Geisslerc926e172021-05-07 16:11:35 -0500301 Here is an example for the extended installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500302
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600303 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500304
Patrick Williams2390b1b2022-11-03 13:47:49 -0500305 An example for the make-only installer::
306
307 $ sh ~/Downloads/x86_64-buildtools-make-nativesdk-standalone-&DISTRO;.sh
308
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500309 During execution, a prompt appears that allows you to choose the
310 installation directory. For example, you could choose the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500311 ``/home/your-username/buildtools``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500312
3133. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500314 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500315
316 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux
317
318 Of
319 course, you need to supply your installation directory and be sure to
320 use the right file (i.e. i585 or x86-64).
321
322 After you have sourced the setup script, the tools are added to
323 ``PATH`` and any other environment variables required to run the
324 tools are initialized. The results are working versions versions of
325 Git, tar, Python and ``chrpath``. And in the case of the
326 ``buildtools-extended`` tarball, additional working versions of tools
327 including ``gcc``, ``make`` and the other tools included in
328 ``packagegroup-core-buildessential``.
329
330Building Your Own ``buildtools`` Tarball
331----------------------------------------
332
333Building and running your own buildtools installer applies only when you
334have a build host that can already run BitBake. In this case, you use
335that machine to build the ``.sh`` file and then take steps to transfer
336and run it on a machine that does not meet the minimal Git, tar, and
337Python (or gcc) requirements.
338
339Here are the steps to take to build and run your own buildtools
340installer:
341
3421. On the machine that is able to run BitBake, be sure you have set up
343 your build environment with the setup script
344 (:ref:`structure-core-script`).
345
Andrew Geisslerc926e172021-05-07 16:11:35 -05003462. Run the BitBake command to build the tarball::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500347
348 $ bitbake buildtools-tarball
349
Andrew Geisslerc926e172021-05-07 16:11:35 -0500350 or run the BitBake command to build the extended tarball::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500351
352 $ bitbake buildtools-extended-tarball
353
Patrick Williams2390b1b2022-11-03 13:47:49 -0500354 or to build the make-only tarball::
355
356 $ bitbake buildtools-make-tarball
357
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500358 .. note::
359
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500360 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines
361 whether you build tools for a 32-bit or 64-bit system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500362
363 Once the build completes, you can find the ``.sh`` file that installs
364 the tools in the ``tmp/deploy/sdk`` subdirectory of the
365 :term:`Build Directory`. The installer file has the string
366 "buildtools" (or "buildtools-extended") in the name.
367
3683. Transfer the ``.sh`` file from the build host to the machine that
369 does not meet the Git, tar, or Python (or gcc) requirements.
370
3714. On the machine that does not meet the requirements, run the ``.sh``
372 file to install the tools. Here is an example for the traditional
Andrew Geisslerc926e172021-05-07 16:11:35 -0500373 installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500374
375 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
376
Andrew Geisslerc926e172021-05-07 16:11:35 -0500377 Here is an example for the extended installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500378
379 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
380
Patrick Williams2390b1b2022-11-03 13:47:49 -0500381 or for the make-only installer::
382
383 $ sh ~/Downloads/x86_64-buildtools-make-nativesdk-standalone-&DISTRO;.sh
384
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385 During execution, a prompt appears that allows you to choose the
386 installation directory. For example, you could choose the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500387 ``/home/your_username/buildtools``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500388
3895. Source the tools environment setup script by using a command like the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500390 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500391
392 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
393
394 Of course, you need to supply your installation directory and be sure to
395 use the right file (i.e. i586 or x86_64).
396
397 After you have sourced the setup script, the tools are added to
398 ``PATH`` and any other environment variables required to run the
399 tools are initialized. The results are working versions versions of
400 Git, tar, Python and ``chrpath``. And in the case of the
401 ``buildtools-extended`` tarball, additional working versions of tools
402 including ``gcc``, ``make`` and the other tools included in
403 ``packagegroup-core-buildessential``.