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