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