blob: 0db84e31fae42c5cd40d4d8b5a6b8de4687eb61e [file] [log] [blame]
Brad Bishop316dfdd2018-06-25 12:45:53 -04001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-manual-system-requirements'>
6<title>System Requirements</title>
7
8 <para>
9 Welcome to the Yocto Project Reference Manual!
10 This manual provides reference information for the current release
11 of the Yocto Project.
12 The manual is best used after you have an understanding
13 of the basics of the Yocto Project.
14 The manual is neither meant to be read as a starting point to the
15 Yocto Project nor read from start to finish.
16 Use this manual to find variable definitions, class
17 descriptions, and so forth as needed during the course of using
18 the Yocto Project.
19 </para>
20
21 <para>
22 For introductory information on the Yocto Project, see the
23 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the
24 "<ulink url='&YOCTO_DOCS_OM_URL;#overview-development-environment'>Yocto Project Development Environment</ulink>"
25 chapter in the Yocto Project Overview and Concepts Manual.
26 </para>
27
28 <para>
29 If you want to use the Yocto Project to quickly build an image
30 without having to understand concepts, work through the
31 <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
32 document.
33 You can find "how-to" information in the
34 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>.
35 You can find Yocto Project overview and conceptual information in the
36 <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
37 <note><title>Tip</title>
38 For more information about the Yocto Project Documentation set,
39 see the
40 "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>"
41 section.
42 </note>
43 </para>
44
45 <section id='detailed-supported-distros'>
46 <title>Supported Linux Distributions</title>
47
48 <para>
49 Currently, the Yocto Project is supported on the following
50 distributions:
51 <note><title>Notes</title>
52 <itemizedlist>
53 <listitem><para>
54 Yocto Project releases are tested against the stable
55 Linux distributions in the following list.
56 The Yocto Project should work on other distributions but
57 validation is not performed against them.
58 </para></listitem>
59 <listitem><para>
60 In particular, the Yocto Project does not support
61 and currently has no plans to support
62 rolling-releases or development distributions due to
63 their constantly changing nature.
64 We welcome patches and bug reports, but keep in mind
65 that our priority is on the supported platforms listed
66 below.
67 </para></listitem>
68 <listitem><para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080069 The Yocto Project is not compatible with the
70 <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux</ulink>
71 (WSL).
72 You cannot use a
73 <link linkend='hardware-build-system-term'>build host</link>
74 that is running WSL.
75 </para></listitem>
76 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040077 If you encounter problems, please go to
78 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
79 and submit a bug.
80 We are interested in hearing about your experience.
81 For information on how to submit a bug, see the
82 Yocto Project
83 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>
84 and the
85 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
86 section in the Yocto Project Development Tasks Manual.
87 </para></listitem>
88 </itemizedlist>
89 </note>
90 <itemizedlist>
Brad Bishopb1114e52019-02-13 07:56:10 -050091 <listitem><para>Ubuntu 16.04 (LTS)</para></listitem>
92 <listitem><para>Ubuntu 18.04</para></listitem>
93 <listitem><para>Fedora 28</para></listitem>
94 <listitem><para>CentOS 7.x</para></listitem>
95 <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
96 <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
97 <listitem><para>OpenSUSE 42.3</para></listitem>
98 </itemizedlist>
99 </para>
100<!--
101Checkout the poky distro you are interested in (by branch or tag).
102From the poky directory, run the script:
103
104bitbake -e | grep ^SANITY_TESTED_DISTROS | sed -e 's/.*"\(.*\)".*/\1/g' -e 's!\\n!\n!g' | sed 's/^[\t]*//;s/[ \t]*$//' | grep -v Poky
105
106This returns a list of the supported distros for the release.
107
108Here is some old list items to show the form:
109
110
111 <listitem><para>Ubuntu 10.04</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400112 <listitem><para>Ubuntu 11.10</para></listitem>
113 <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
114 <listitem><para>Ubuntu 13.10</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800115 <listitem><para>Ubuntu 14.04 (LTS)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400116 <listitem><para>Ubuntu 14.10</para></listitem>
117 <listitem><para>Ubuntu 15.04</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500118 <listitem><para>Ubuntu 15.10</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400119 <listitem><para>Ubuntu 16.04 (LTS)</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800120 <listitem><para>Ubuntu 16.10 (LTS)</para></listitem>
121 <listitem><para>Ubuntu 17.04</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500122 <listitem><para>Fedora 16 (Verne)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400123 <listitem><para>Fedora 17 (Spherical)</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800124 <listitem><para>Fedora 19 (Schrödinger's Cat)</para></listitem>
125 <listitem><para>Fedora release 20 (Heisenbug)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400126 <listitem><para>Fedora release 22</para></listitem>
127 <listitem><para>Fedora release 23</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500128 <listitem><para>Fedora release 24</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800129 <listitem><para>Fedora release 26</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500130 <listitem><para>CentOS release 5.6 (Final)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400131 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
132 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
133 <listitem><para>CentOS release 6.3 (Final)</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500134 <listitem><para>CentOS release 6.x</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400135 <listitem><para>CentOS release 7.x</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500136 <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem>
137 <listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400138 <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
139 <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500140 <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400141 <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
142 <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
143 <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
144 <listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800145 <listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem>
146 <listitem><para>openSUSE 11.4</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400147 <listitem><para>openSUSE 12.1</para></listitem>
148 <listitem><para>openSUSE 12.2</para></listitem>
149 <listitem><para>openSUSE 12.3</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800150 <listitem><para>openSUSE 13.1</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500151 <listitem><para>openSUSE 13.2</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400152 <listitem><para>openSUSE 42.1</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800153 <listitem><para>openSUSE 42.2</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500154-->
Brad Bishop316dfdd2018-06-25 12:45:53 -0400155
156 <note>
157 While the Yocto Project Team attempts to ensure all Yocto Project
158 releases are one hundred percent compatible with each officially
159 supported Linux distribution, instances might exist where you
160 encounter a problem while using the Yocto Project on a specific
161 distribution.
162 </note>
163 </section>
164
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800165 <section id='required-packages-for-the-build-host'>
166 <title>Required Packages for the Build Host</title>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400167
168 <para>
169 The list of packages you need on the host development system can
170 be large when covering all build scenarios using the Yocto Project.
171 This section provides required packages according to
172 Linux distribution and function.
173 </para>
174
175 <section id='ubuntu-packages'>
176 <title>Ubuntu and Debian</title>
177
178 <para>
179 The following list shows the required packages by function
180 given a supported Ubuntu or Debian Linux distribution:
181 <note>
182 If your build system has the
183 <filename>oss4-dev</filename> package installed, you
184 might experience QEMU build failures due to the package
185 installing its own custom
186 <filename>/usr/include/linux/soundcard.h</filename> on
187 the Debian system.
188 If you run into this situation, either of the following
189 solutions exist:
190 <literallayout class='monospaced'>
191 $ sudo apt-get build-dep qemu
192 $ sudo apt-get remove oss4-dev
193 </literallayout>
194 </note>
195 <itemizedlist>
196 <listitem><para><emphasis>Essentials:</emphasis>
197 Packages needed to build an image on a headless
198 system:
199 <literallayout class='monospaced'>
200 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
201 </literallayout></para></listitem>
202 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
203 Packages recommended if the host system has graphics
204 support or if you are going to use the Eclipse
205 IDE:
206 <literallayout class='monospaced'>
207 $ sudo apt-get install libsdl1.2-dev xterm
208 </literallayout></para></listitem>
209 <listitem><para><emphasis>Documentation:</emphasis>
210 Packages needed if you are going to build out the
211 Yocto Project documentation manuals:
212 <literallayout class='monospaced'>
213 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
214 </literallayout></para></listitem>
215 <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
216 Packages needed if you are going to run
217 <filename>oe-selftest</filename>:
218 <literallayout class='monospaced'>
219 $ sudo apt-get install python-git
220 </literallayout>
221 </para></listitem>
222 </itemizedlist>
223 </para>
224 </section>
225
226 <section id='fedora-packages'>
227 <title>Fedora Packages</title>
228
229 <para>
230 The following list shows the required packages by function
231 given a supported Fedora Linux distribution:
232 <itemizedlist>
233 <listitem><para><emphasis>Essentials:</emphasis>
234 Packages needed to build an image for a headless
235 system:
236 <literallayout class='monospaced'>
237 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
238 </literallayout></para></listitem>
239 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
240 Packages recommended if the host system has graphics
241 support or if you are going to use the Eclipse
242 IDE:
243 <literallayout class='monospaced'>
244 $ sudo dnf install SDL-devel xterm
245 </literallayout></para></listitem>
246 <listitem><para><emphasis>Documentation:</emphasis>
247 Packages needed if you are going to build out the
248 Yocto Project documentation manuals:
249 <literallayout class='monospaced'>
250 $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \
251 docbook-dtds docbook-utils fop libxslt dblatex xmlto
252 </literallayout></para></listitem>
253 <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
254 Packages needed if you are going to run
255 <filename>oe-selftest</filename>:
256 <literallayout class='monospaced'>
257 $ sudo dnf install python3-GitPython
258 </literallayout>
259 </para></listitem>
260 </itemizedlist>
261 </para>
262 </section>
263
264 <section id='opensuse-packages'>
265 <title>openSUSE Packages</title>
266
267 <para>
268 The following list shows the required packages by function
269 given a supported openSUSE Linux distribution:
270 <itemizedlist>
271 <listitem><para><emphasis>Essentials:</emphasis>
272 Packages needed to build an image for a headless
273 system:
274 <literallayout class='monospaced'>
275 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
276 </literallayout></para></listitem>
277 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
278 Packages recommended if the host system has graphics
279 support or if you are going to use the Eclipse
280 IDE:
281 <literallayout class='monospaced'>
282 $ sudo zypper install libSDL-devel xterm
283 </literallayout></para></listitem>
284 <listitem><para><emphasis>Documentation:</emphasis>
285 Packages needed if you are going to build out the
286 Yocto Project documentation manuals:
287 <literallayout class='monospaced'>
288 $ sudo zypper install make dblatex xmlto
289 </literallayout></para></listitem>
290 <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
291 Packages needed if you are going to run
292 <filename>oe-selftest</filename>:
293 <literallayout class='monospaced'>
294 $ sudo zypper install python-GitPython
295 </literallayout></para></listitem>
296 </itemizedlist>
297 <note>
298 Sanity testing, through the
299 <link linkend='ref-classes-testimage*'>testimage</link>
300 classes, does not work on systems using the
301 <ulink url='https://en.opensuse.org/Portal:Wicked'>Wicked</ulink>
302 network manager.
303 </note>
304 </para>
305 </section>
306
307 <section id='centos-packages'>
308 <title>CentOS Packages</title>
309
310 <para>
311 The following list shows the required packages by function
312 given a supported CentOS Linux distribution:
313 <itemizedlist>
314 <listitem><para><emphasis>Essentials:</emphasis>
315 Packages needed to build an image for a headless
316 system:
317 <literallayout class='monospaced'>
318 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
319 </literallayout>
320 <note><title>Notes</title>
321 <itemizedlist>
322 <listitem><para>
323 Extra Packages for Enterprise Linux
324 (i.e. <filename>epel-release</filename>)
325 is a collection of packages from Fedora
326 built on RHEL/CentOS for easy installation
327 of packages not included in enterprise
328 Linux by default.
329 You need to install these packages
330 separately.
331 </para></listitem>
332 <listitem><para>
333 The <filename>makecache</filename> command
334 consumes additional Metadata from
335 <filename>epel-release</filename>.
336 </para></listitem>
337 </itemizedlist>
338 </note>
339 </para></listitem>
340 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
341 Packages recommended if the host system has graphics
342 support or if you are going to use the Eclipse
343 IDE:
344 <literallayout class='monospaced'>
345 $ sudo yum install SDL-devel xterm
346 </literallayout></para></listitem>
347 <listitem><para><emphasis>Documentation:</emphasis>
348 Packages needed if you are going to build out the
349 Yocto Project documentation manuals:
350 <literallayout class='monospaced'>
351 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
352 docbook-dtds docbook-utils fop libxslt dblatex xmlto
353 </literallayout></para></listitem>
354 <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
355 Packages needed if you are going to run
356 <filename>oe-selftest</filename>:
357 <literallayout class='monospaced'>
358 $ sudo yum install GitPython
359 </literallayout>
360 </para></listitem>
361 </itemizedlist>
362 </para>
363 </section>
364 </section>
365
366 <section id='required-git-tar-and-python-versions'>
367 <title>Required Git, tar, and Python Versions</title>
368
369 <para>
370 In order to use the build system, your host development system
371 must meet the following version requirements for Git, tar, and
372 Python:
373 <itemizedlist>
374 <listitem><para>Git 1.8.3.1 or greater</para></listitem>
375 <listitem><para>tar 1.27 or greater</para></listitem>
376 <listitem><para>Python 3.4.0 or greater</para></listitem>
377 </itemizedlist>
378 </para>
379
380 <para>
381 If your host development system does not meet all these requirements,
382 you can resolve this by installing a <filename>buildtools</filename>
383 tarball that contains these tools.
384 You can get the tarball one of two ways: download a pre-built
385 tarball or use BitBake to build the tarball.
386 </para>
387
388 <section id='downloading-a-pre-built-buildtools-tarball'>
389 <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
390
391 <para>
392 Downloading and running a pre-built buildtools installer is
393 the easiest of the two methods by which you can get these tools:
394 <orderedlist>
395 <listitem><para>
396 Locate and download the <filename>*.sh</filename> at
397 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
398 </para></listitem>
399 <listitem><para>
400 Execute the installation script.
401 Here is an example:
402 <literallayout class='monospaced'>
403 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
404 </literallayout>
405 During execution, a prompt appears that allows you to
406 choose the installation directory.
407 For example, you could choose the following:
408 <literallayout class='monospaced'>
409 /home/<replaceable>your-username</replaceable>/buildtools
410 </literallayout>
411 </para></listitem>
412 <listitem><para>
413 Source the tools environment setup script by using a
414 command like the following:
415 <literallayout class='monospaced'>
416 $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
417 </literallayout>
418 Of course, you need to supply your installation directory and be
419 sure to use the right file (i.e. i585 or x86-64).
420 </para>
421 <para>
422 After you have sourced the setup script,
423 the tools are added to <filename>PATH</filename>
424 and any other environment variables required to run the
425 tools are initialized.
426 The results are working versions versions of Git, tar,
427 Python and <filename>chrpath</filename>.
428 </para></listitem>
429 </orderedlist>
430 </para>
431 </section>
432
433 <section id='building-your-own-buildtools-tarball'>
434 <title>Building Your Own <filename>buildtools</filename> Tarball</title>
435
436 <para>
437 Building and running your own buildtools installer applies
438 only when you have a build host that can already run BitBake.
439 In this case, you use that machine to build the
440 <filename>.sh</filename> file and then
441 take steps to transfer and run it on a
442 machine that does not meet the minimal Git, tar, and Python
443 requirements.
444 </para>
445
446 <para>
447 Here are the steps to take to build and run your own
448 buildtools installer:
449 <orderedlist>
450 <listitem><para>
451 On the machine that is able to run BitBake,
452 be sure you have set up your build environment with
453 the setup script
454 (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
455 </para></listitem>
456 <listitem><para>
457 Run the BitBake command to build the tarball:
458 <literallayout class='monospaced'>
459 $ bitbake buildtools-tarball
460 </literallayout>
461 <note>
462 The
463 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
464 variable in your <filename>local.conf</filename> file
465 determines whether you build tools for a 32-bit
466 or 64-bit system.
467 </note>
468 Once the build completes, you can find the
469 <filename>.sh</filename> file that installs
470 the tools in the <filename>tmp/deploy/sdk</filename>
471 subdirectory of the
472 <link linkend='build-directory'>Build Directory</link>.
473 The installer file has the string "buildtools"
474 in the name.
475 </para></listitem>
476 <listitem><para>
477 Transfer the <filename>.sh</filename> file from the
478 build host to the machine that does not meet the
479 Git, tar, or Python requirements.
480 </para></listitem>
481 <listitem><para>
482 On the machine that does not meet the requirements,
483 run the <filename>.sh</filename> file
484 to install the tools.
485 Here is an example:
486 <literallayout class='monospaced'>
487 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
488 </literallayout>
489 During execution, a prompt appears that allows you to
490 choose the installation directory.
491 For example, you could choose the following:
492 <literallayout class='monospaced'>
493 /home/<replaceable>your_username</replaceable>/buildtools
494 </literallayout>
495 </para></listitem>
496 <listitem><para>
497 Source the tools environment setup script by using a
498 command like the following:
499 <literallayout class='monospaced'>
500 $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
501 </literallayout>
502 Of course, you need to supply your installation directory and be
503 sure to use the right file (i.e. i585 or x86-64).
504 </para>
505 <para>
506 After you have sourced the setup script,
507 the tools are added to <filename>PATH</filename>
508 and any other environment variables required to run the
509 tools are initialized.
510 The results are working versions versions of Git, tar,
511 Python and <filename>chrpath</filename>.
512 </para></listitem>
513 </orderedlist>
514 </para>
515 </section>
516 </section>
517</chapter>
518<!--
519vim: expandtab tw=80 ts=4
520-->