blob: 56218e4ebb634389ecfced166b7ec2ddfe0a1fb3 [file] [log] [blame]
Andrew Geissler4873add2020-11-02 18:44:49 -06001.. SPDX-License-Identifier: CC-BY-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
18":ref:`overview-manual/overview-manual-development-environment:the yocto project development environment`"
19chapter 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
23:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. You can find "how-to"
24information in the :doc:`../dev-manual/dev-manual`. You can find Yocto Project overview
25and conceptual information in the :doc:`../overview-manual/overview-manual`.
26
27.. note::
28
29 For more information about the Yocto Project Documentation set, see
30 the "
31 Links and Related Documentation
32 " section.
33
34.. _detailed-supported-distros:
35
36Supported Linux Distributions
37=============================
38
39Currently, the Yocto Project is supported on the following
40distributions:
41
42- Ubuntu 16.04 (LTS)
43
44- Ubuntu 18.04 (LTS)
45
46- Ubuntu 20.04
47
48- Fedora 30
49
50- Fedora 31
51
52- Fedora 32
53
54- CentOS 7.x
55
56- CentOS 8.x
57
58- Debian GNU/Linux 8.x (Jessie)
59
60- Debian GNU/Linux 9.x (Stretch)
61
62- Debian GNU/Linux 10.x (Buster)
63
64- OpenSUSE Leap 15.1
65
66
67.. note::
68
69 - While the Yocto Project Team attempts to ensure all Yocto Project
70 releases are one hundred percent compatible with each officially
71 supported Linux distribution, instances might exist where you
72 encounter a problem while using the Yocto Project on a specific
73 distribution.
74
75 - Yocto Project releases are tested against the stable Linux
76 distributions in the above list. The Yocto Project should work
77 on other distributions but validation is not performed against
78 them.
79
80 - In particular, the Yocto Project does not support and currently
81 has no plans to support rolling-releases or development
82 distributions due to their constantly changing nature. We welcome
83 patches and bug reports, but keep in mind that our priority is on
84 the supported platforms listed below.
85
86 - You may use Windows Subsystem For Linux v2 to set up a build host
87 using Windows 10, but validation is not performed against build
88 hosts using WSLv2.
89
90 - The Yocto Project is not compatible with WSLv1, it is
91 compatible but not officially supported nor validated with
92 WSLv2, if you still decide to use WSL please upgrade to WSLv2.
93
94 - If you encounter problems, please go to `Yocto Project
95 Bugzilla <http://bugzilla.yoctoproject.org>`__ and submit a bug. We are
96 interested in hearing about your experience. For information on
97 how to submit a bug, see the Yocto Project
98 :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`
99 and the ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`"
100 section in the Yocto Project Development Tasks Manual.
101
102
103Required Packages for the Build Host
104====================================
105
106The list of packages you need on the host development system can be
107large when covering all build scenarios using the Yocto Project. This
108section describes required packages according to Linux distribution and
109function.
110
111.. _ubuntu-packages:
112
113Ubuntu and Debian
114-----------------
115
116The following list shows the required packages by function given a
117supported Ubuntu or Debian Linux distribution:
118
119.. note::
120
121 - If your build system has the ``oss4-dev`` package installed, you
122 might experience QEMU build failures due to the package installing
123 its own custom ``/usr/include/linux/soundcard.h`` on the Debian
124 system. If you run into this situation, either of the following
125 solutions exist:
126 ::
127
128 $ sudo apt-get build-dep qemu
129 $ sudo apt-get remove oss4-dev
130
131 - For Debian-8, ``python3-git`` and ``pylint3`` are no longer
132 available via ``apt-get``.
133 ::
134
135 $ sudo pip3 install GitPython pylint==1.9.5
136
137- *Essentials:* Packages needed to build an image on a headless system:
138 ::
139
140 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
141
142- *Documentation:* Packages needed if you are going to build out the
143 Yocto Project documentation manuals:
144 ::
145
146 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
147
148Fedora Packages
149---------------
150
151The following list shows the required packages by function given a
152supported Fedora Linux distribution:
153
154- *Essentials:* Packages needed to build an image for a headless
155 system:
156 ::
157
158 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
159
160- *Documentation:* Packages needed if you are going to build out the
161 Yocto Project documentation manuals:
162 ::
163
164 $ sudo dnf install docbook-style-dsssl docbook-style-xsl \
165 docbook-dtds docbook-utils fop libxslt dblatex xmlto
166
167openSUSE Packages
168-----------------
169
170The following list shows the required packages by function given a
171supported openSUSE Linux distribution:
172
173- *Essentials:* Packages needed to build an image for a headless
174 system:
175 ::
176
177 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
178
179- *Documentation:* Packages needed if you are going to build out the
180 Yocto Project documentation manuals: $ sudo zypper install dblatex
181 xmlto
182
183CentOS-7 Packages
184-----------------
185
186The following list shows the required packages by function given a
187supported CentOS-7 Linux distribution:
188
189- *Essentials:* Packages needed to build an image for a headless
190 system:
191 ::
192
193 $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
194
195 .. note::
196
197 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
198 a collection of packages from Fedora built on RHEL/CentOS for
199 easy installation of packages not included in enterprise Linux
200 by default. You need to install these packages separately.
201
202 - The ``makecache`` command consumes additional Metadata from
203 ``epel-release``.
204
205- *Documentation:* Packages needed if you are going to build out the
206 Yocto Project documentation manuals:
207 ::
208
209 $ sudo yum install docbook-style-dsssl docbook-style-xsl \
210 docbook-dtds docbook-utils fop libxslt dblatex xmlto
211
212CentOS-8 Packages
213-----------------
214
215The following list shows the required packages by function given a
216supported CentOS-8 Linux distribution:
217
218- *Essentials:* Packages needed to build an image for a headless
219 system:
220 ::
221
222 $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
223
224 .. note::
225
226 - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is
227 a collection of packages from Fedora built on RHEL/CentOS for
228 easy installation of packages not included in enterprise Linux
229 by default. You need to install these packages separately.
230
231 - The ``PowerTools`` repo provides additional packages such as
232 ``rpcgen`` and ``texinfo``.
233
234 - The ``makecache`` command consumes additional Metadata from
235 ``epel-release``.
236
237- *Documentation:* Packages needed if you are going to build out the
238 Yocto Project documentation manuals:
239 ::
240
241 $ sudo dnf install docbook-style-dsssl docbook-style-xsl \\
242 docbook-dtds docbook-utils fop libxslt dblatex xmlto
243
244Required Git, tar, Python and gcc Versions
245==========================================
246
247In order to use the build system, your host development system must meet
248the following version requirements for Git, tar, and Python:
249
250- Git 1.8.3.1 or greater
251
252- tar 1.28 or greater
253
254- Python 3.5.0 or greater
255
256If your host development system does not meet all these requirements,
257you can resolve this by installing a ``buildtools`` tarball that
258contains these tools. You can get the tarball one of two ways: download
259a pre-built tarball or use BitBake to build the tarball.
260
261In addition, your host development system must meet the following
262version requirement for gcc:
263
264- gcc 5.0 or greater
265
266If your host development system does not meet this requirement, you can
267resolve this by installing a ``buildtools-extended`` tarball that
268contains additional tools, the equivalent of ``buildtools-essential``.
269
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
2771. Execute the ``install-buildtools`` script. Here is an example:
278 ::
279
280 $ cd poky
281 $ scripts/install-buildtools --without-extended-buildtools \
282 --base-url https://downloads.yoctoproject.org/releases/yocto \
283 --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
288 for you, and some basic checks will be run to to make sure the
289 installation is functional.
290
291 To avoid the need of ``sudo`` privileges, the ``install-buildtools``
292 script will by default tell the installer to install in:
293 ::
294
295 /path/to/poky/buildtools
296
297 If your host development system needs the additional tools provided
298 in the ``buildtools-extended`` tarball, you can instead execute the
299 ``install-buildtools`` script with the default parameters:
300 ::
301
302 $ cd poky
303 $ scripts/install-buildtools
304
3052. Source the tools environment setup script by using a command like the
306 following:
307 ::
308
309 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
310
311 Of course, you need to supply your installation directory and be sure to
312 use the right file (i.e. i586 or x86_64).
313
314 After you have sourced the setup script, the tools are added to
315 ``PATH`` and any other environment variables required to run the
316 tools are initialized. The results are working versions versions of
317 Git, tar, Python and ``chrpath``. And in the case of the
318 ``buildtools-extended`` tarball, additional working versions of tools
319 including ``gcc``, ``make`` and the other tools included in
320 ``packagegroup-core-buildessential``.
321
322Downloading a Pre-Built ``buildtools`` Tarball
323----------------------------------------------
324
325Downloading and running a pre-built buildtools installer is the easiest
326of the two methods by which you can get these tools:
327
3281. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
329
3302. Execute the installation script. Here is an example for the
331 traditional installer:
332 ::
333
334 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh
335
336 Here is an example for the extended installer:
337 ::
338
339 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh
340
341 During execution, a prompt appears that allows you to choose the
342 installation directory. For example, you could choose the following:
343 /home/your-username/buildtools
344
3453. Source the tools environment setup script by using a command like the
346 following:
347 ::
348
349 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux
350
351 Of
352 course, you need to supply your installation directory and be sure to
353 use the right file (i.e. i585 or x86-64).
354
355 After you have sourced the setup script, the tools are added to
356 ``PATH`` and any other environment variables required to run the
357 tools are initialized. The results are working versions versions of
358 Git, tar, Python and ``chrpath``. And in the case of the
359 ``buildtools-extended`` tarball, additional working versions of tools
360 including ``gcc``, ``make`` and the other tools included in
361 ``packagegroup-core-buildessential``.
362
363Building Your Own ``buildtools`` Tarball
364----------------------------------------
365
366Building and running your own buildtools installer applies only when you
367have a build host that can already run BitBake. In this case, you use
368that machine to build the ``.sh`` file and then take steps to transfer
369and run it on a machine that does not meet the minimal Git, tar, and
370Python (or gcc) requirements.
371
372Here are the steps to take to build and run your own buildtools
373installer:
374
3751. On the machine that is able to run BitBake, be sure you have set up
376 your build environment with the setup script
377 (:ref:`structure-core-script`).
378
3792. Run the BitBake command to build the tarball:
380 ::
381
382 $ bitbake buildtools-tarball
383
384 or run the BitBake command to build the extended tarball:
385 ::
386
387 $ bitbake buildtools-extended-tarball
388
389 .. note::
390
391 The
392 SDKMACHINE
393 variable in your
394 local.conf
395 file determines whether you build tools for a 32-bit or 64-bit
396 system.
397
398 Once the build completes, you can find the ``.sh`` file that installs
399 the tools in the ``tmp/deploy/sdk`` subdirectory of the
400 :term:`Build Directory`. The installer file has the string
401 "buildtools" (or "buildtools-extended") in the name.
402
4033. Transfer the ``.sh`` file from the build host to the machine that
404 does not meet the Git, tar, or Python (or gcc) requirements.
405
4064. On the machine that does not meet the requirements, run the ``.sh``
407 file to install the tools. Here is an example for the traditional
408 installer:
409 ::
410
411 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
412
413 Here is an example for the extended installer:
414 ::
415
416 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
417
418 During execution, a prompt appears that allows you to choose the
419 installation directory. For example, you could choose the following:
420 /home/your_username/buildtools
421
4225. Source the tools environment setup script by using a command like the
423 following:
424 ::
425
426 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
427
428 Of course, you need to supply your installation directory and be sure to
429 use the right file (i.e. i586 or x86_64).
430
431 After you have sourced the setup script, the tools are added to
432 ``PATH`` and any other environment variables required to run the
433 tools are initialized. The results are working versions versions of
434 Git, tar, Python and ``chrpath``. And in the case of the
435 ``buildtools-extended`` tarball, additional working versions of tools
436 including ``gcc``, ``make`` and the other tools included in
437 ``packagegroup-core-buildessential``.