Gitiles
Code Review Sign In
gerrit.openbmc.org / stefanberger / openbmc / 3c1837c6b94f5951b59af63a0eaec797f929153e / . / poky / documentation / ref-manual / ref-system-requirements.xml
blob: 239dd84bbddfe5ef448f96dc2198d18e6a47c1b0 [file] [log] [blame]
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]1<!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 -0800[diff] [blame]69 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 -0400[diff] [blame]77 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 -0500[diff] [blame]91 <listitem><para>Ubuntu 16.04 (LTS)</para></listitem>
92 <listitem><para>Ubuntu 18.04</para></listitem>
93 <listitem><para>Fedora 28</para></listitem>
Brad Bishopc342db32019-05-15 21:57:59 -0400[diff] [blame]94 <listitem><para>Fedora 29</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]95 <listitem><para>CentOS 7.x</para></listitem>
96 <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
97 <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
98 <listitem><para>OpenSUSE 42.3</para></listitem>
99 </itemizedlist>
100 </para>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]101
102
Brad Bishop19323692019-04-05 15:28:33 -0400[diff] [blame]103<!-- <listitem><para>Ubuntu 10.04</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]104 <listitem><para>Ubuntu 11.10</para></listitem>
105 <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
106 <listitem><para>Ubuntu 13.10</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800[diff] [blame]107 <listitem><para>Ubuntu 14.04 (LTS)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]108 <listitem><para>Ubuntu 14.10</para></listitem>
109 <listitem><para>Ubuntu 15.04</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]110 <listitem><para>Ubuntu 15.10</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]111 <listitem><para>Ubuntu 16.04 (LTS)</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800[diff] [blame]112 <listitem><para>Ubuntu 16.10 (LTS)</para></listitem>
113 <listitem><para>Ubuntu 17.04</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]114 <listitem><para>Fedora 16 (Verne)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]115 <listitem><para>Fedora 17 (Spherical)</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800[diff] [blame]116 <listitem><para>Fedora 19 (Schrödinger's Cat)</para></listitem>
117 <listitem><para>Fedora release 20 (Heisenbug)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]118 <listitem><para>Fedora release 22</para></listitem>
119 <listitem><para>Fedora release 23</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]120 <listitem><para>Fedora release 24</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800[diff] [blame]121 <listitem><para>Fedora release 26</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]122 <listitem><para>CentOS release 5.6 (Final)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]123 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
124 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
125 <listitem><para>CentOS release 6.3 (Final)</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]126 <listitem><para>CentOS release 6.x</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]127 <listitem><para>CentOS release 7.x</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]128 <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem>
129 <listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]130 <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
131 <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]132 <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]133 <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
134 <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
135 <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
136 <listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800[diff] [blame]137 <listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem>
138 <listitem><para>openSUSE 11.4</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]139 <listitem><para>openSUSE 12.1</para></listitem>
140 <listitem><para>openSUSE 12.2</para></listitem>
141 <listitem><para>openSUSE 12.3</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800[diff] [blame]142 <listitem><para>openSUSE 13.1</para></listitem>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]143 <listitem><para>openSUSE 13.2</para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]144 <listitem><para>openSUSE 42.1</para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800[diff] [blame]145 <listitem><para>openSUSE 42.2</para></listitem>
Brad Bishop19323692019-04-05 15:28:33 -0400[diff] [blame]146 </itemizedlist>
Brad Bishopb1114e52019-02-13 07:56:10 -0500[diff] [blame]147-->
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]148
Brad Bishop19323692019-04-05 15:28:33 -0400[diff] [blame]149
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]150 <note>
151 While the Yocto Project Team attempts to ensure all Yocto Project
152 releases are one hundred percent compatible with each officially
153 supported Linux distribution, instances might exist where you
154 encounter a problem while using the Yocto Project on a specific
155 distribution.
156 </note>
157 </section>
158
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800[diff] [blame]159 <section id='required-packages-for-the-build-host'>
160 <title>Required Packages for the Build Host</title>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]161
162 <para>
163 The list of packages you need on the host development system can
164 be large when covering all build scenarios using the Yocto Project.
165 This section provides required packages according to
166 Linux distribution and function.
167 </para>
168
169 <section id='ubuntu-packages'>
170 <title>Ubuntu and Debian</title>
171
172 <para>
173 The following list shows the required packages by function
174 given a supported Ubuntu or Debian Linux distribution:
175 <note>
176 If your build system has the
177 <filename>oss4-dev</filename> package installed, you
178 might experience QEMU build failures due to the package
179 installing its own custom
180 <filename>/usr/include/linux/soundcard.h</filename> on
181 the Debian system.
182 If you run into this situation, either of the following
183 solutions exist:
184 <literallayout class='monospaced'>
185 $ sudo apt-get build-dep qemu
186 $ sudo apt-get remove oss4-dev
187 </literallayout>
188 </note>
189 <itemizedlist>
190 <listitem><para><emphasis>Essentials:</emphasis>
191 Packages needed to build an image on a headless
192 system:
193 <literallayout class='monospaced'>
194 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
195 </literallayout></para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]196 <listitem><para><emphasis>Documentation:</emphasis>
197 Packages needed if you are going to build out the
198 Yocto Project documentation manuals:
199 <literallayout class='monospaced'>
200 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
201 </literallayout></para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]202 </itemizedlist>
203 </para>
204 </section>
205
206 <section id='fedora-packages'>
207 <title>Fedora Packages</title>
208
209 <para>
210 The following list shows the required packages by function
211 given a supported Fedora Linux distribution:
212 <itemizedlist>
213 <listitem><para><emphasis>Essentials:</emphasis>
214 Packages needed to build an image for a headless
215 system:
216 <literallayout class='monospaced'>
217 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
218 </literallayout></para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]219 <listitem><para><emphasis>Documentation:</emphasis>
220 Packages needed if you are going to build out the
221 Yocto Project documentation manuals:
222 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -0400[diff] [blame]223 $ sudo dnf install docbook-style-dsssl docbook-style-xsl \
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]224 docbook-dtds docbook-utils fop libxslt dblatex xmlto
225 </literallayout></para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]226 </itemizedlist>
227 </para>
228 </section>
229
230 <section id='opensuse-packages'>
231 <title>openSUSE Packages</title>
232
233 <para>
234 The following list shows the required packages by function
235 given a supported openSUSE Linux distribution:
236 <itemizedlist>
237 <listitem><para><emphasis>Essentials:</emphasis>
238 Packages needed to build an image for a headless
239 system:
240 <literallayout class='monospaced'>
241 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
242 </literallayout></para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]243 <listitem><para><emphasis>Documentation:</emphasis>
244 Packages needed if you are going to build out the
245 Yocto Project documentation manuals:
246 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -0400[diff] [blame]247 $ sudo zypper install dblatex xmlto
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]248 </literallayout></para></listitem>
249 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]250 </para>
251 </section>
252
253 <section id='centos-packages'>
254 <title>CentOS Packages</title>
255
256 <para>
257 The following list shows the required packages by function
258 given a supported CentOS Linux distribution:
259 <itemizedlist>
260 <listitem><para><emphasis>Essentials:</emphasis>
261 Packages needed to build an image for a headless
262 system:
263 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -0400[diff] [blame]264 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]265 </literallayout>
266 <note><title>Notes</title>
267 <itemizedlist>
268 <listitem><para>
269 Extra Packages for Enterprise Linux
270 (i.e. <filename>epel-release</filename>)
271 is a collection of packages from Fedora
272 built on RHEL/CentOS for easy installation
273 of packages not included in enterprise
274 Linux by default.
275 You need to install these packages
276 separately.
277 </para></listitem>
278 <listitem><para>
279 The <filename>makecache</filename> command
280 consumes additional Metadata from
281 <filename>epel-release</filename>.
282 </para></listitem>
283 </itemizedlist>
284 </note>
285 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]286 <listitem><para><emphasis>Documentation:</emphasis>
287 Packages needed if you are going to build out the
288 Yocto Project documentation manuals:
289 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -0400[diff] [blame]290 $ sudo yum install docbook-style-dsssl docbook-style-xsl \
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]291 docbook-dtds docbook-utils fop libxslt dblatex xmlto
292 </literallayout></para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400[diff] [blame]293 </itemizedlist>
294 </para>
295 </section>
296 </section>
297
298 <section id='required-git-tar-and-python-versions'>
299 <title>Required Git, tar, and Python Versions</title>
300
301 <para>
302 In order to use the build system, your host development system
303 must meet the following version requirements for Git, tar, and
304 Python:
305 <itemizedlist>
306 <listitem><para>Git 1.8.3.1 or greater</para></listitem>
307 <listitem><para>tar 1.27 or greater</para></listitem>
308 <listitem><para>Python 3.4.0 or greater</para></listitem>
309 </itemizedlist>
310 </para>
311
312 <para>
313 If your host development system does not meet all these requirements,
314 you can resolve this by installing a <filename>buildtools</filename>
315 tarball that contains these tools.
316 You can get the tarball one of two ways: download a pre-built
317 tarball or use BitBake to build the tarball.
318 </para>
319
320 <section id='downloading-a-pre-built-buildtools-tarball'>
321 <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
322
323 <para>
324 Downloading and running a pre-built buildtools installer is
325 the easiest of the two methods by which you can get these tools:
326 <orderedlist>
327 <listitem><para>
328 Locate and download the <filename>*.sh</filename> at
329 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
330 </para></listitem>
331 <listitem><para>
332 Execute the installation script.
333 Here is an example:
334 <literallayout class='monospaced'>
335 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
336 </literallayout>
337 During execution, a prompt appears that allows you to
338 choose the installation directory.
339 For example, you could choose the following:
340 <literallayout class='monospaced'>
341 /home/<replaceable>your-username</replaceable>/buildtools
342 </literallayout>
343 </para></listitem>
344 <listitem><para>
345 Source the tools environment setup script by using a
346 command like the following:
347 <literallayout class='monospaced'>
348 $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
349 </literallayout>
350 Of course, you need to supply your installation directory and be
351 sure to use the right file (i.e. i585 or x86-64).
352 </para>
353 <para>
354 After you have sourced the setup script,
355 the tools are added to <filename>PATH</filename>
356 and any other environment variables required to run the
357 tools are initialized.
358 The results are working versions versions of Git, tar,
359 Python and <filename>chrpath</filename>.
360 </para></listitem>
361 </orderedlist>
362 </para>
363 </section>
364
365 <section id='building-your-own-buildtools-tarball'>
366 <title>Building Your Own <filename>buildtools</filename> Tarball</title>
367
368 <para>
369 Building and running your own buildtools installer applies
370 only when you have a build host that can already run BitBake.
371 In this case, you use that machine to build the
372 <filename>.sh</filename> file and then
373 take steps to transfer and run it on a
374 machine that does not meet the minimal Git, tar, and Python
375 requirements.
376 </para>
377
378 <para>
379 Here are the steps to take to build and run your own
380 buildtools installer:
381 <orderedlist>
382 <listitem><para>
383 On the machine that is able to run BitBake,
384 be sure you have set up your build environment with
385 the setup script
386 (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
387 </para></listitem>
388 <listitem><para>
389 Run the BitBake command to build the tarball:
390 <literallayout class='monospaced'>
391 $ bitbake buildtools-tarball
392 </literallayout>
393 <note>
394 The
395 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
396 variable in your <filename>local.conf</filename> file
397 determines whether you build tools for a 32-bit
398 or 64-bit system.
399 </note>
400 Once the build completes, you can find the
401 <filename>.sh</filename> file that installs
402 the tools in the <filename>tmp/deploy/sdk</filename>
403 subdirectory of the
404 <link linkend='build-directory'>Build Directory</link>.
405 The installer file has the string "buildtools"
406 in the name.
407 </para></listitem>
408 <listitem><para>
409 Transfer the <filename>.sh</filename> file from the
410 build host to the machine that does not meet the
411 Git, tar, or Python requirements.
412 </para></listitem>
413 <listitem><para>
414 On the machine that does not meet the requirements,
415 run the <filename>.sh</filename> file
416 to install the tools.
417 Here is an example:
418 <literallayout class='monospaced'>
419 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
420 </literallayout>
421 During execution, a prompt appears that allows you to
422 choose the installation directory.
423 For example, you could choose the following:
424 <literallayout class='monospaced'>
425 /home/<replaceable>your_username</replaceable>/buildtools
426 </literallayout>
427 </para></listitem>
428 <listitem><para>
429 Source the tools environment setup script by using a
430 command like the following:
431 <literallayout class='monospaced'>
432 $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
433 </literallayout>
434 Of course, you need to supply your installation directory and be
435 sure to use the right file (i.e. i585 or x86-64).
436 </para>
437 <para>
438 After you have sourced the setup script,
439 the tools are added to <filename>PATH</filename>
440 and any other environment variables required to run the
441 tools are initialized.
442 The results are working versions versions of Git, tar,
443 Python and <filename>chrpath</filename>.
444 </para></listitem>
445 </orderedlist>
446 </para>
447 </section>
448 </section>
449</chapter>
450<!--
451vim: expandtab tw=80 ts=4
452-->