blob: 66afb08102280322c3b855db868e7483d1d1765c [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
44- Ubuntu 20.04
45
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
62- OpenSUSE Leap 15.1
63
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
69 supported Linux distribution, instances might exist where you
70 encounter a problem while using the Yocto Project on a specific
71 distribution.
72
73 - Yocto Project releases are tested against the stable Linux
74 distributions in the above list. The Yocto Project should work
75 on other distributions but validation is not performed against
76 them.
77
78 - In particular, the Yocto Project does not support and currently
79 has no plans to support rolling-releases or development
80 distributions due to their constantly changing nature. We welcome
81 patches and bug reports, but keep in mind that our priority is on
82 the supported platforms listed below.
83
84 - You may use Windows Subsystem For Linux v2 to set up a build host
85 using Windows 10, but validation is not performed against build
86 hosts using WSLv2.
87
88 - The Yocto Project is not compatible with WSLv1, it is
89 compatible but not officially supported nor validated with
90 WSLv2, if you still decide to use WSL please upgrade to WSLv2.
91
Andrew Geissler4c19ea12020-10-27 13:52:24 -050092 - If you encounter problems, please go to :yocto_bugs:`Yocto Project
93 Bugzilla <>` and submit a bug. We are
Andrew Geisslerc9f78652020-09-18 14:11:35 -050094 interested in hearing about your experience. For information on
95 how to submit a bug, see the Yocto Project
Andrew Geissler09209ee2020-12-13 08:44:15 -060096 :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>`
97 and the ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050098 section in the Yocto Project Development Tasks Manual.
99
100
101Required Packages for the Build Host
102====================================
103
104The list of packages you need on the host development system can be
105large when covering all build scenarios using the Yocto Project. This
106section describes required packages according to Linux distribution and
107function.
108
109.. _ubuntu-packages:
110
111Ubuntu and Debian
112-----------------
113
114The following list shows the required packages by function given a
115supported Ubuntu or Debian Linux distribution:
116
117.. note::
118
119 - If your build system has the ``oss4-dev`` package installed, you
120 might experience QEMU build failures due to the package installing
121 its own custom ``/usr/include/linux/soundcard.h`` on the Debian
122 system. If you run into this situation, either of the following
123 solutions exist:
124 ::
125
126 $ sudo apt-get build-dep qemu
127 $ sudo apt-get remove oss4-dev
128
129 - For Debian-8, ``python3-git`` and ``pylint3`` are no longer
130 available via ``apt-get``.
131 ::
132
133 $ sudo pip3 install GitPython pylint==1.9.5
134
135- *Essentials:* Packages needed to build an image on a headless system:
136 ::
137
138 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
139
140- *Documentation:* Packages needed if you are going to build out the
141 Yocto Project documentation manuals:
142 ::
143
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500144 $ sudo apt-get install make python3-pip
145 &PIP3_HOST_PACKAGES_DOC;
146
147 .. note::
148
149 It is currently not possible to build out documentation from Debian 8
150 (Jessie) because of outdated ``pip3`` and ``python3``. ``python3-sphinx``
151 is too outdated.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500152
153Fedora Packages
154---------------
155
156The following list shows the required packages by function given a
157supported Fedora Linux distribution:
158
159- *Essentials:* Packages needed to build an image for a headless
160 system:
161 ::
162
163 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
164
165- *Documentation:* Packages needed if you are going to build out the
166 Yocto Project documentation manuals:
167 ::
168
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500169 $ sudo dnf install make python3-pip which
170 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500171
172openSUSE Packages
173-----------------
174
175The following list shows the required packages by function given a
176supported openSUSE Linux distribution:
177
178- *Essentials:* Packages needed to build an image for a headless
179 system:
180 ::
181
182 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
183
184- *Documentation:* Packages needed if you are going to build out the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500185 Yocto Project documentation manuals:
186 ::
187
188 $ sudo zypper install make python3-pip which
189 &PIP3_HOST_PACKAGES_DOC;
190
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500191
192CentOS-7 Packages
193-----------------
194
195The following list shows the required packages by function given a
196supported CentOS-7 Linux distribution:
197
198- *Essentials:* Packages needed to build an image for a headless
199 system:
200 ::
201
202 $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
203
204 .. note::
205
206 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
207 a collection of packages from Fedora built on RHEL/CentOS for
208 easy installation of packages not included in enterprise Linux
209 by default. You need to install these packages separately.
210
211 - The ``makecache`` command consumes additional Metadata from
212 ``epel-release``.
213
214- *Documentation:* Packages needed if you are going to build out the
215 Yocto Project documentation manuals:
216 ::
217
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500218 $ sudo yum install make python3-pip which
219 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220
221CentOS-8 Packages
222-----------------
223
224The following list shows the required packages by function given a
225supported CentOS-8 Linux distribution:
226
227- *Essentials:* Packages needed to build an image for a headless
228 system:
229 ::
230
231 $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
232
233 .. note::
234
235 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
236 a collection of packages from Fedora built on RHEL/CentOS for
237 easy installation of packages not included in enterprise Linux
238 by default. You need to install these packages separately.
239
240 - The ``PowerTools`` repo provides additional packages such as
241 ``rpcgen`` and ``texinfo``.
242
243 - The ``makecache`` command consumes additional Metadata from
244 ``epel-release``.
245
246- *Documentation:* Packages needed if you are going to build out the
247 Yocto Project documentation manuals:
248 ::
249
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500250 $ sudo dnf install make python3-pip which
251 &PIP3_HOST_PACKAGES_DOC;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500252
253Required Git, tar, Python and gcc Versions
254==========================================
255
256In order to use the build system, your host development system must meet
257the following version requirements for Git, tar, and Python:
258
259- Git 1.8.3.1 or greater
260
261- tar 1.28 or greater
262
263- Python 3.5.0 or greater
264
265If your host development system does not meet all these requirements,
266you can resolve this by installing a ``buildtools`` tarball that
267contains these tools. You can get the tarball one of two ways: download
268a pre-built tarball or use BitBake to build the tarball.
269
270In addition, your host development system must meet the following
271version requirement for gcc:
272
273- gcc 5.0 or greater
274
275If your host development system does not meet this requirement, you can
276resolve this by installing a ``buildtools-extended`` tarball that
277contains additional tools, the equivalent of ``buildtools-essential``.
278
279Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
280--------------------------------------------------------------------------------
281
282The ``install-buildtools`` script is the easiest of the three methods by
283which you can get these tools. It downloads a pre-built buildtools
284installer and automatically installs the tools for you:
285
2861. Execute the ``install-buildtools`` script. Here is an example:
287 ::
288
289 $ cd poky
290 $ scripts/install-buildtools --without-extended-buildtools \
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500291 --base-url &YOCTO_DL_URL;/releases/yocto \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500292 --release yocto-&DISTRO; \
293 --installer-version &DISTRO;
294
295 During execution, the buildtools tarball will be downloaded, the
296 checksum of the download will be verified, the installer will be run
297 for you, and some basic checks will be run to to make sure the
298 installation is functional.
299
300 To avoid the need of ``sudo`` privileges, the ``install-buildtools``
301 script will by default tell the installer to install in:
302 ::
303
304 /path/to/poky/buildtools
305
306 If your host development system needs the additional tools provided
307 in the ``buildtools-extended`` tarball, you can instead execute the
308 ``install-buildtools`` script with the default parameters:
309 ::
310
311 $ cd poky
312 $ scripts/install-buildtools
313
3142. Source the tools environment setup script by using a command like the
315 following:
316 ::
317
318 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
319
320 Of course, you need to supply your installation directory and be sure to
321 use the right file (i.e. i586 or x86_64).
322
323 After you have sourced the setup script, the tools are added to
324 ``PATH`` and any other environment variables required to run the
325 tools are initialized. The results are working versions versions of
326 Git, tar, Python and ``chrpath``. And in the case of the
327 ``buildtools-extended`` tarball, additional working versions of tools
328 including ``gcc``, ``make`` and the other tools included in
329 ``packagegroup-core-buildessential``.
330
331Downloading a Pre-Built ``buildtools`` Tarball
332----------------------------------------------
333
334Downloading and running a pre-built buildtools installer is the easiest
335of the two methods by which you can get these tools:
336
3371. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
338
3392. Execute the installation script. Here is an example for the
340 traditional installer:
341 ::
342
343 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh
344
345 Here is an example for the extended installer:
346 ::
347
348 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh
349
350 During execution, a prompt appears that allows you to choose the
351 installation directory. For example, you could choose the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500352 ``/home/your-username/buildtools``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500353
3543. Source the tools environment setup script by using a command like the
355 following:
356 ::
357
358 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux
359
360 Of
361 course, you need to supply your installation directory and be sure to
362 use the right file (i.e. i585 or x86-64).
363
364 After you have sourced the setup script, the tools are added to
365 ``PATH`` and any other environment variables required to run the
366 tools are initialized. The results are working versions versions of
367 Git, tar, Python and ``chrpath``. And in the case of the
368 ``buildtools-extended`` tarball, additional working versions of tools
369 including ``gcc``, ``make`` and the other tools included in
370 ``packagegroup-core-buildessential``.
371
372Building Your Own ``buildtools`` Tarball
373----------------------------------------
374
375Building and running your own buildtools installer applies only when you
376have a build host that can already run BitBake. In this case, you use
377that machine to build the ``.sh`` file and then take steps to transfer
378and run it on a machine that does not meet the minimal Git, tar, and
379Python (or gcc) requirements.
380
381Here are the steps to take to build and run your own buildtools
382installer:
383
3841. On the machine that is able to run BitBake, be sure you have set up
385 your build environment with the setup script
386 (:ref:`structure-core-script`).
387
3882. Run the BitBake command to build the tarball:
389 ::
390
391 $ bitbake buildtools-tarball
392
393 or run the BitBake command to build the extended tarball:
394 ::
395
396 $ bitbake buildtools-extended-tarball
397
398 .. note::
399
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500400 The :term:`SDKMACHINE` variable in your ``local.conf`` file determines
401 whether you build tools for a 32-bit or 64-bit system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500402
403 Once the build completes, you can find the ``.sh`` file that installs
404 the tools in the ``tmp/deploy/sdk`` subdirectory of the
405 :term:`Build Directory`. The installer file has the string
406 "buildtools" (or "buildtools-extended") in the name.
407
4083. Transfer the ``.sh`` file from the build host to the machine that
409 does not meet the Git, tar, or Python (or gcc) requirements.
410
4114. On the machine that does not meet the requirements, run the ``.sh``
412 file to install the tools. Here is an example for the traditional
413 installer:
414 ::
415
416 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
417
418 Here is an example for the extended installer:
419 ::
420
421 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
422
423 During execution, a prompt appears that allows you to choose the
424 installation directory. For example, you could choose the following:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500425 ``/home/your_username/buildtools``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500426
4275. Source the tools environment setup script by using a command like the
428 following:
429 ::
430
431 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
432
433 Of course, you need to supply your installation directory and be sure to
434 use the right file (i.e. i586 or x86_64).
435
436 After you have sourced the setup script, the tools are added to
437 ``PATH`` and any other environment variables required to run the
438 tools are initialized. The results are working versions versions of
439 Git, tar, Python and ``chrpath``. And in the case of the
440 ``buildtools-extended`` tarball, additional working versions of tools
441 including ``gcc``, ``make`` and the other tools included in
442 ``packagegroup-core-buildessential``.