diff options
Diffstat (limited to 'documentation/ref-manual/ref-system-requirements.rst')
-rw-r--r-- | documentation/ref-manual/ref-system-requirements.rst | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-system-requirements.rst b/documentation/ref-manual/ref-system-requirements.rst new file mode 100644 index 0000000000..56218e4ebb --- /dev/null +++ b/documentation/ref-manual/ref-system-requirements.rst | |||
@@ -0,0 +1,437 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******************* | ||
4 | System Requirements | ||
5 | ******************* | ||
6 | |||
7 | Welcome to the Yocto Project Reference Manual! This manual provides | ||
8 | reference information for the current release of the Yocto Project, and | ||
9 | is most effectively used after you have an understanding of the basics | ||
10 | of the Yocto Project. The manual is neither meant to be read as a | ||
11 | starting point to the Yocto Project, nor read from start to finish. | ||
12 | Rather, use this manual to find variable definitions, class | ||
13 | descriptions, and so forth as needed during the course of using the | ||
14 | Yocto Project. | ||
15 | |||
16 | For 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`" | ||
19 | chapter in the Yocto Project Overview and Concepts Manual. | ||
20 | |||
21 | If you want to use the Yocto Project to quickly build an image without | ||
22 | having to understand concepts, work through the | ||
23 | :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. You can find "how-to" | ||
24 | information in the :doc:`../dev-manual/dev-manual`. You can find Yocto Project overview | ||
25 | and 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 | |||
36 | Supported Linux Distributions | ||
37 | ============================= | ||
38 | |||
39 | Currently, the Yocto Project is supported on the following | ||
40 | distributions: | ||
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 | |||
103 | Required Packages for the Build Host | ||
104 | ==================================== | ||
105 | |||
106 | The list of packages you need on the host development system can be | ||
107 | large when covering all build scenarios using the Yocto Project. This | ||
108 | section describes required packages according to Linux distribution and | ||
109 | function. | ||
110 | |||
111 | .. _ubuntu-packages: | ||
112 | |||
113 | Ubuntu and Debian | ||
114 | ----------------- | ||
115 | |||
116 | The following list shows the required packages by function given a | ||
117 | supported 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 | |||
148 | Fedora Packages | ||
149 | --------------- | ||
150 | |||
151 | The following list shows the required packages by function given a | ||
152 | supported 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 | |||
167 | openSUSE Packages | ||
168 | ----------------- | ||
169 | |||
170 | The following list shows the required packages by function given a | ||
171 | supported 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 | |||
183 | CentOS-7 Packages | ||
184 | ----------------- | ||
185 | |||
186 | The following list shows the required packages by function given a | ||
187 | supported 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 | |||
212 | CentOS-8 Packages | ||
213 | ----------------- | ||
214 | |||
215 | The following list shows the required packages by function given a | ||
216 | supported 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 | |||
244 | Required Git, tar, Python and gcc Versions | ||
245 | ========================================== | ||
246 | |||
247 | In order to use the build system, your host development system must meet | ||
248 | the 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 | |||
256 | If your host development system does not meet all these requirements, | ||
257 | you can resolve this by installing a ``buildtools`` tarball that | ||
258 | contains these tools. You can get the tarball one of two ways: download | ||
259 | a pre-built tarball or use BitBake to build the tarball. | ||
260 | |||
261 | In addition, your host development system must meet the following | ||
262 | version requirement for gcc: | ||
263 | |||
264 | - gcc 5.0 or greater | ||
265 | |||
266 | If your host development system does not meet this requirement, you can | ||
267 | resolve this by installing a ``buildtools-extended`` tarball that | ||
268 | contains additional tools, the equivalent of ``buildtools-essential``. | ||
269 | |||
270 | Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script | ||
271 | -------------------------------------------------------------------------------- | ||
272 | |||
273 | The ``install-buildtools`` script is the easiest of the three methods by | ||
274 | which you can get these tools. It downloads a pre-built buildtools | ||
275 | installer and automatically installs the tools for you: | ||
276 | |||
277 | 1. 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 | |||
305 | 2. 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 | |||
322 | Downloading a Pre-Built ``buildtools`` Tarball | ||
323 | ---------------------------------------------- | ||
324 | |||
325 | Downloading and running a pre-built buildtools installer is the easiest | ||
326 | of the two methods by which you can get these tools: | ||
327 | |||
328 | 1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/ | ||
329 | |||
330 | 2. 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 | |||
345 | 3. 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 | |||
363 | Building Your Own ``buildtools`` Tarball | ||
364 | ---------------------------------------- | ||
365 | |||
366 | Building and running your own buildtools installer applies only when you | ||
367 | have a build host that can already run BitBake. In this case, you use | ||
368 | that machine to build the ``.sh`` file and then take steps to transfer | ||
369 | and run it on a machine that does not meet the minimal Git, tar, and | ||
370 | Python (or gcc) requirements. | ||
371 | |||
372 | Here are the steps to take to build and run your own buildtools | ||
373 | installer: | ||
374 | |||
375 | 1. 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 | |||
379 | 2. 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 | |||
403 | 3. 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 | |||
406 | 4. 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 | |||
422 | 5. 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``. | ||