summaryrefslogtreecommitdiffstats
path: root/documentation/yocto-project-qs/yocto-project-qs.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/yocto-project-qs/yocto-project-qs.xml')
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml1163
1 files changed, 139 insertions, 1024 deletions
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index cfaa70f551..12ca05b930 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -1,21 +1,140 @@
1<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > 3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<article id='yocto-project-qs-intro'> 5<book id='yocto-project-qs' lang='en'
6 <articleinfo> 6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 <title>Yocto Project Quick Start</title> 7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/ypqs-title.png'
14 format='SVG'
15 align='center' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title>
20 Yocto Project Quick Start
21 </title>
22
23 <authorgroup>
24 <author>
25 <firstname>Scott</firstname> <surname>Rifenbark</surname>
26 <affiliation>
27 <orgname>Scotty's Documentation Services, INC</orgname>
28 </affiliation>
29 <email>srifenbark@gmail.com</email>
30 </author>
31 </authorgroup>
8 32
9 <copyright> 33<!--
10 <year>&COPYRIGHT_YEAR;</year> 34 <revhistory>
11 <holder>Linux Foundation</holder> 35 <revision>
12 </copyright> 36 <revnumber>0.9</revnumber>
37 <date>24 November 2010</date>
38 <revremark>The initial document draft released with the Yocto Project 0.9 Release.</revremark>
39 </revision>
40 <revision>
41 <revnumber>1.0</revnumber>
42 <date>6 April 2011</date>
43 <revremark>Released with the Yocto Project 1.0 Release.</revremark>
44 </revision>
45 <revision>
46 <revnumber>1.0.1</revnumber>
47 <date>23 May 2011</date>
48 <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
49 </revision>
50 <revision>
51 <revnumber>1.1</revnumber>
52 <date>6 October 2011</date>
53 <revremark>Released with the Yocto Project 1.1 Release.</revremark>
54 </revision>
55 <revision>
56 <revnumber>1.2</revnumber>
57 <date>April 2012</date>
58 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
59 </revision>
60 <revision>
61 <revnumber>1.3</revnumber>
62 <date>October 2012</date>
63 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
64 </revision>
65 <revision>
66 <revnumber>1.4</revnumber>
67 <date>April 2013</date>
68 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
69 </revision>
70 <revision>
71 <revnumber>1.5</revnumber>
72 <date>October 2013</date>
73 <revremark>Released with the Yocto Project 1.5 Release.</revremark>
74 </revision>
75 <revision>
76 <revnumber>1.5.1</revnumber>
77 <date>January 2014</date>
78 <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
79 </revision>
80 <revision>
81 <revnumber>1.6</revnumber>
82 <date>April 2014</date>
83 <revremark>Released with the Yocto Project 1.6 Release.</revremark>
84 </revision>
85 <revision>
86 <revnumber>1.7</revnumber>
87 <date>October 2014</date>
88 <revremark>Released with the Yocto Project 1.7 Release.</revremark>
89 </revision>
90 <revision>
91 <revnumber>1.8</revnumber>
92 <date>April 2015</date>
93 <revremark>Released with the Yocto Project 1.8 Release.</revremark>
94 </revision>
95 <revision>
96 <revnumber>2.0</revnumber>
97 <date>October 2015</date>
98 <revremark>Released with the Yocto Project 2.0 Release.</revremark>
99 </revision>
100 <revision>
101 <revnumber>2.1</revnumber>
102 <date>April 2016</date>
103 <revremark>Released with the Yocto Project 2.1 Release.</revremark>
104 </revision>
105 <revision>
106 <revnumber>2.2</revnumber>
107 <date>October 2016</date>
108 <revremark>Released with the Yocto Project 2.2 Release.</revremark>
109 </revision>
110 <revision>
111 <revnumber>2.3</revnumber>
112 <date>May 2017</date>
113 <revremark>Released with the Yocto Project 2.3 Release.</revremark>
114 </revision>
115 <revision>
116 <revnumber>2.4</revnumber>
117 <date>October 2017</date>
118 <revremark>Released with the Yocto Project 2.4 Release.</revremark>
119 </revision>
120 <revision>
121 <revnumber>2.5</revnumber>
122 <date>April 2018</date>
123 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
124 </revision>
125 </revhistory>
126-->
13 127
14 <legalnotice> 128 <copyright>
15 <para> 129 <year>&COPYRIGHT_YEAR;</year>
16 Permission is granted to copy, distribute and/or modify this document under 130 <holder>Linux Foundation</holder>
17 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons. 131 </copyright>
18 </para> 132
133 <legalnotice>
134 <para>
135 Permission is granted to copy, distribute and/or modify this document under
136 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
137 </para>
19 <note><title>Manual Notes</title> 138 <note><title>Manual Notes</title>
20 <itemizedlist> 139 <itemizedlist>
21 <listitem><para> 140 <listitem><para>
@@ -44,1022 +163,18 @@
44 </para></listitem> 163 </para></listitem>
45 </itemizedlist> 164 </itemizedlist>
46 </note> 165 </note>
47 </legalnotice> 166 </legalnotice>
48
49 <abstract>
50 <imagedata fileref="figures/yocto-project-transp.png"
51 width="6in" depth="1in"
52 align="right" scale="25" />
53 </abstract>
54 </articleinfo>
55 167
56 <section id='welcome'> 168 </bookinfo>
57 <title>Welcome!</title>
58 <para>
59 Welcome to the Yocto Project!
60 The Yocto Project is an open-source collaboration project whose
61 focus is developers of embedded Linux systems.
62 Among other things, the Yocto Project uses a build host based
63 on the OpenEmbedded (OE) project, which uses the
64 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
65 tool, to construct complete Linux images.
66 The BitBake and OE components combine together to form
67 a reference build host, historically known as
68 <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>
69 (<emphasis>Pah</emphasis>-kee).
70 </para>
71 169
72 <para> 170 <xi:include href="qs.xml"/>
73 This quick start is written so that you can quickly get a
74 build host set up to use the Yocto Project and then build some
75 Linux images.
76 Rather than go into great detail about the Yocto Project and its
77 many capabilities, this quick start provides the minimal
78 information you need to try out the Yocto Project using either a
79 supported Linux build host or a build host set up to use
80 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
81 which leverages
82 <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
83 </para>
84 171
85 <para> 172<!-- <index id='index'>
86 Reading and using the quick start should result in you having a 173 <title>Index</title>
87 basic understanding of what the Yocto Project is and how to use 174 </index>
88 some of its core components.
89 You will also have worked through steps to produce two images:
90 one that runs on the emulator (QEMU) and one that boots on actual
91 hardware (i.e. MinnowBoard Turbot).
92 The examples highlight the ease with which you can use the
93 Yocto Project to create images for multiple types of hardware.
94 </para>
95
96 <para>
97 The following list directs you to key sections of this
98 quick start:
99 <itemizedlist>
100 <listitem><para>
101 <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#yp-resources'>Setting Up to Use the Yocto Project</ulink>
102 </para></listitem>
103 <listitem><para>
104 <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#building-an-image-for-emulation'>Building an Image for Emulation</ulink>
105 </para></listitem>
106 <listitem><para>
107 <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#building-an-image-for-hardware'>Building an Image for Hardware</ulink>
108 </para></listitem>
109 </itemizedlist>
110<!--
111 <note>
112 If you do not have a system that runs Linux and you want to give
113 the Yocto Project a test run, you might consider using the Yocto
114 Project Build Appliance.
115 The Build Appliance allows you to build and boot a custom
116 embedded Linux image with the Yocto Project using a non-Linux
117 development system.
118 See the
119 <ulink url='https://www.yoctoproject.org/tools-resources/projects/build-appliance'>Yocto Project Build Appliance</ulink>
120 for more information.
121 </note>
122--> 175-->
123 </para>
124
125 <para>
126 For more detailed information on the Yocto Project, you can
127 reference these resources:
128 <itemizedlist>
129 <listitem><para>
130 <emphasis>Website:</emphasis>
131 The
132 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
133 provides bacground information, the latest builds, breaking
134 news, full development documentation, and access to a rich
135 Yocto Project Development Community into which you can tap.
136 </para></listitem>
137 <listitem><para>
138 <emphasis>Yocto Project Development Environment Overview:</emphasis>
139 The
140 "<ulink url='&YOCTO_DOCS_REF_URL;#yp-intro'>Introducing the Yocto Project Development Environment</ulink>"
141 section presents an overview of the Yocto Project
142 development environment.
143 </para></listitem>
144 <listitem><para>
145 <emphasis>FAQs:</emphasis>
146 Lists commonly asked Yocto Project questions and answers.
147 You can find two FAQs:
148 <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>Yocto Project FAQ</ulink>
149 on a wiki, and the
150 "<ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink>"
151 chapter in the Yocto Project Reference Manual.
152 </para></listitem>
153 <listitem><para>
154 <emphasis>Developer Screencast:</emphasis>
155 The
156 <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>
157 provides a 30-minute video created for users unfamiliar
158 with the Yocto Project but familiar with Linux build
159 hosts.
160 While this screencast is somewhat dated, the introductory
161 and fundamental concepts are useful for the beginner.
162 </para></listitem>
163 <listitem><para>
164 <emphasis>Comprehensive List of Links and Other Documentation:</emphasis>
165 The
166 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
167 section in the Yocto Project Reference Manual provides a
168 comprehensive list of related links and documentation.
169 </para></listitem>
170 </itemizedlist>
171 </para>
172 </section>
173
174 <section id='yp-resources'>
175 <title>Setting Up to Use the Yocto Project</title>
176
177 <para>
178 Setting up to use the Yocto Project involves getting your build
179 host ready.
180 If you have a native Linux machine that runs a Yocto Project
181 supported distribution as described by the
182 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
183 section in the Yocto Project Reference Manual, you can prepare
184 that machine as your build host.
185 See the
186 "<link linkend='qs-native-linux-build-host'>Using a Native Linux Machine</link>"
187 section for more information.
188 </para>
189
190 <para>
191 If you do not want to use the Yocto Project on a native Linux
192 machine, you can prepare your build host to use
193 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
194 which leverages
195 <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
196 You can set up a build host for Windows, Mac, and Linux
197 machines.
198 See the
199 "<link linkend='qs-crops-build-host'>Using CROPS and Containers</link>"
200 section for more information.
201 </para>
202
203 <section id='qs-crops-build-host'>
204 <title>Using CROPS and Containers</title>
205
206 <para>
207 Follow these steps to get your build host set up with a
208 Poky container that you can use to complete the build
209 examples further down in the Quick Start:
210 <orderedlist>
211 <listitem><para>
212 <emphasis>Set Up to use CROss PlatformS (CROPS):</emphasis>
213 Work through the first six steps of the procedure
214 in the
215 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
216 section of the Yocto Project Development Tasks Manual.
217 </para></listitem>
218 <listitem><para>
219 <emphasis>Set Up the Poky Container to Use the Yocto Project:</emphasis>
220 Go to
221 <ulink url='https://github.com/crops/poky-container/blob/master/README.md'></ulink>
222 and follow the directions to set up the Poky container
223 on your build host.</para>
224
225 <para>Once you complete the setup instructions for your
226 machine, you need to get a copy of the
227 <filename>poky</filename> repository on your build
228 host.
229 See the
230 "<link linkend='releases'>Yocto Project Release</link>"
231 section to continue.
232 </para></listitem>
233 </orderedlist>
234 </para>
235 </section>
236
237 <section id='qs-native-linux-build-host'>
238 <title>Using a Native Linux Machine</title>
239
240 <para>
241 The following list shows what you need in order to use a
242 Linux-based build host to use the Yocto Project to build images:
243 </para>
244
245 <itemizedlist>
246 <listitem><para><emphasis>Build Host</emphasis>
247 A build host with a minimum of 50 Gbytes of free disk
248 space that is running a supported Linux distribution (i.e.
249 recent releases of Fedora, openSUSE, CentOS, Debian, or
250 Ubuntu).
251 </para></listitem>
252 <listitem><para><emphasis>Build Host Packages</emphasis>
253 Appropriate packages installed on the build host.
254 </para></listitem>
255 </itemizedlist>
256
257 <section id='the-linux-distro'>
258 <title>The Linux Distribution</title>
259
260 <para>
261 The Yocto Project team verifies each release against recent
262 versions of the most popular Linux distributions that
263 provide stable releases.
264 In general, if you have the current release minus one of the
265 following distributions, you should have no problems.
266 <itemizedlist>
267 <listitem><para>
268 Ubuntu
269 </para></listitem>
270 <listitem><para>
271 Fedora
272 </para></listitem>
273 <listitem><para>
274 openSUSE
275 </para></listitem>
276 <listitem><para>
277 CentOS
278 </para></listitem>
279 <listitem><para>
280 Debian
281 </para></listitem>
282 </itemizedlist>
283 For a more detailed list of distributions that support the
284 Yocto Project, see the
285 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
286 section in the Yocto Project Reference Manual.
287 </para>
288
289 <para>
290 The OpenEmbedded build system should be able to run on any
291 modern distribution that has the following versions for
292 Git, tar, and Python.
293 <itemizedlist>
294 <listitem><para>
295 Git 1.8.3.1 or greater
296 </para></listitem>
297 <listitem><para>
298 tar 1.27 or greater
299 </para></listitem>
300 <listitem><para>
301 Python 3.4.0 or greater.
302 </para></listitem>
303 </itemizedlist>
304 If your build host does not meet any of these three listed
305 version requirements, you can take steps to prepare the
306 system so that you can still use the Yocto Project.
307 See the
308 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
309 section in the Yocto Project Reference Manual for information.
310 </para>
311 </section>
312
313 <section id='packages'>
314 <title>The Build Host Packages</title>
315
316 <para>
317 Required build host packages vary depending on your
318 build machine and what you want to do with the Yocto Project.
319 For example, if you want to build an image that can run
320 on QEMU in graphical mode (a minimal, basic build
321 requirement), then the build host package requirements
322 are different than if you want to build an image on a headless
323 system or build out the Yocto Project documentation set.
324 </para>
325
326 <para>
327 Collectively, the number of required packages is large
328 if you want to be able to cover all cases.
329 <note>
330 In general, you need to have root access and then install
331 the required packages.
332 Thus, the commands in the following section may or may
333 not work depending on whether or not your Linux
334 distribution has <filename>sudo</filename> installed.
335 </note>
336 </para>
337
338 <para>
339 The following list shows the required packages needed to build
340 an image that runs on QEMU in graphical mode (e.g. essential
341 plus graphics support).
342 For lists of required packages for other scenarios, see the
343 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
344 section in the Yocto Project Reference Manual.
345 <itemizedlist>
346 <listitem><para><emphasis>Ubuntu and Debian</emphasis>
347 <literallayout class='monospaced'>
348 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
349 </literallayout>
350 </para></listitem>
351 <listitem><para><emphasis>Fedora</emphasis>
352 <literallayout class='monospaced'>
353 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
354 </literallayout>
355 </para></listitem>
356 <listitem><para><emphasis>OpenSUSE</emphasis>
357 <literallayout class='monospaced'>
358 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm
359 </literallayout>
360 </para></listitem>
361 <listitem><para><emphasis>CentOS</emphasis>
362 <literallayout class='monospaced'>
363 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
364 </literallayout>
365 <note><title>Notes</title>
366 <itemizedlist>
367 <listitem><para>
368 CentOS 6.x users need to ensure that the
369 required versions of Git, tar and Python
370 are available.
371 For details, See the
372 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
373 section in the Yocto Project Reference
374 Manual for information.
375 </para></listitem>
376 <listitem><para>
377 Extra Packages for Enterprise Linux
378 (i.e. <filename>epel-release</filename>)
379 is a collection of packages from Fedora
380 built on RHEL/CentOS for easy installation
381 of packages not included in enterprise
382 Linux by default.
383 You need to install these packages
384 separately.
385 </para></listitem>
386 <listitem><para>
387 The <filename>makecache</filename> command
388 consumes additional Metadata from
389 <filename>epel-release</filename>.
390 </para></listitem>
391 </itemizedlist>
392 </note>
393 </para></listitem>
394 </itemizedlist>
395 </para>
396 </section>
397
398 <para>
399 Once you complete the setup instructions for your
400 machine, you need to get a copy of the
401 <filename>poky</filename> repository on your build
402 host.
403 Continue with the
404 "<link linkend='releases'>Yocto Project Release</link>"
405 section.
406 </para>
407 </section>
408
409 <section id='releases'>
410 <title>Yocto Project Release</title>
411
412 <para>
413 Now that your build host has the right packages (native
414 Linux machine) or you have the Poky container set up
415 (CROPS), you need to get a copy of the Yocto Project.
416 It is recommended that you get the latest Yocto Project release
417 by setting up (cloning in
418 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> terms) a
419 local copy of the <filename>poky</filename> Git repository on
420 your build host and then checking out the latest release.
421 Doing so allows you to easily update to newer Yocto Project
422 releases as well as contribute back to the Yocto Project.
423 </para>
424
425 <para>
426 Here is an example from a native Linux machine that is
427 running Ubuntu.
428 <note>
429 If your build host is using a Poky container, you can
430 use the same Git commands.
431 </note>
432 The following example clones the <filename>poky</filename>
433 repository and then checks out the latest Yocto Project Release
434 by tag (i.e. <filename>&DISTRO_REL_TAG;</filename>):
435 <literallayout class='monospaced'>
436 $ git clone git://git.yoctoproject.org/poky
437 Cloning into 'poky'...
438 remote: Counting objects: 361782, done.
439 remote: Compressing objects: 100% (87100/87100), done.
440 remote: Total 361782 (delta 268619), reused 361439 (delta 268277)
441 Receiving objects: 100% (361782/361782), 131.94 MiB | 6.88 MiB/s, done.
442 Resolving deltas: 100% (268619/268619), done.
443 Checking connectivity... done.
444 $ git checkout tags/&DISTRO_REL_TAG; -b poky_&DISTRO;
445 </literallayout>
446 </para>
447
448 <para>
449 The previous Git <filename>checkout</filename> command
450 creates a local branch named
451 <filename>poky_&DISTRO;</filename>.
452 The files available to you in that branch exactly match the
453 repository's files in the
454 <filename>&DISTRO_NAME_NO_CAP;</filename>
455 development branch at the time of the Yocto Project &DISTRO;
456 release.
457 <note>
458 Rather than checking out the entire development branch
459 of a release (i.e. the tip), which could be continuously
460 changing while you are doing your development, you would
461 check out a branch based on a release tag as shown in
462 the previous example.
463 Doing so provides you with an unchanging, stable set of
464 files.
465 </note>
466 </para>
467
468 <para>
469 For more options and information about accessing Yocto
470 Project related repositories, see the
471 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
472 section in the Yocto Project Development Tasks Manual.
473 </para>
474 </section>
475 </section>
476
477 <section id='qs-building-images'>
478 <title>Building Images</title>
479
480 <para>
481 You are now ready to give the Yocto Project a try.
482 For this example, you will be using the command line to build
483 your images.
484 <note>
485 A graphical user interface to the Yocto Project is available
486 through
487 <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>.
488 See the
489 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>
490 for more information.
491 </note>
492 </para>
493
494 <para>
495 The remainder of this quick start steps you through the
496 following:
497 <itemizedlist>
498 <listitem><para>
499 Build a <filename>qemux86</filename> reference image
500 and run it in the QEMU emulator.
501 </para></listitem>
502 <listitem><para>
503 Easily change configurations so that you can quickly
504 create a second image that you can load onto bootable
505 media and actually boot target hardware.
506 This example uses the MinnowBoard
507 Turbot-compatible boards.
508 </para></listitem>
509 </itemizedlist>
510 <note>
511 The steps in the following two sections do not provide detail,
512 but rather provide minimal, working commands and examples
513 designed to just get you started.
514 For more details, see the appropriate manuals in the
515 <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project manual set</ulink>.
516 </note>
517 </para>
518
519 <section id='building-an-image-for-emulation'>
520 <title>Building an Image for Emulation</title>
521
522 <para>
523 Use the following commands to build your image.
524 The OpenEmbedded build system creates an entire Linux
525 distribution, including the toolchain, from source.
526 <note><title>Notes about Network Proxies</title>
527 <itemizedlist>
528 <listitem><para>
529 By default, the build process searches for source
530 code using a pre-determined order through a set of
531 locations.
532 If you are working behind a firewall and your build
533 host is not set up for proxies, you could encounter
534 problems with the build process when fetching source
535 code (e.g. fetcher failures or Git failures).
536 </para></listitem>
537 <listitem><para>
538 If you do not know your proxy settings, consult your
539 local network infrastructure resources and get that
540 information.
541 A good starting point could also be to check your
542 web browser settings.
543 Finally, you can find more information on using the
544 Yocto Project behind a firewall in the Yocto Project
545 Reference Manual
546 <ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</ulink>
547 and on the
548 "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
549 wiki page.
550 </para></listitem>
551 </itemizedlist>
552 </note>
553 </para>
554
555 <para>
556 <orderedlist>
557 <listitem><para>
558 <emphasis>Be Sure Your Build Host is Set Up:</emphasis>
559 The steps to build an image in this section depend on
560 your build host being properly set up.
561 Be sure you have worked through the requirements
562 described in the
563 "<link linkend='yp-resources'>Setting Up to Use the Yocto Project</link>"
564 section.
565 </para></listitem>
566 <listitem><para>
567 <emphasis>Check Out Your Branch:</emphasis>
568 Be sure you are in the
569 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
570 (e.g. <filename>poky</filename>) and then check out
571 the branch associated with the latest Yocto Project
572 Release:
573 <literallayout class='monospaced'>
574 $ cd ~/poky
575 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
576 </literallayout>
577 Git's <filename>checkout</filename> command checks out
578 the current Yocto Project release into a local branch
579 whose name matches the release (i.e.
580 <filename>&DISTRO_NAME_NO_CAP;</filename>).
581 The local branch tracks the upstream branch of the
582 same name.
583 Creating your own branch based on the released
584 branch ensures you are using the latest files for
585 that release.
586 </para></listitem>
587 <listitem><para>
588 <emphasis>Initialize the Build Environment:</emphasis>
589 Run the
590 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
591 environment setup script to define the OpenEmbedded
592 build environment on your build host.
593 <literallayout class='monospaced'>
594 $ source &OE_INIT_FILE;
595 </literallayout>
596 Among other things, the script creates the
597 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
598 which is <filename>build</filename> in this case
599 and is located in the
600 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
601 After the script runs, your current working directory
602 is set to the Build Directory.
603 Later, when the build completes, the Build Directory
604 contains all the files created during the build.
605 </para></listitem>
606 <listitem><para>
607 <emphasis>Examine Your Local Configuration File:</emphasis>
608 When you set up the build environment, a local
609 configuration file named
610 <filename>local.conf</filename> becomes available in
611 a <filename>conf</filename> subdirectory of the
612 Build Directory.
613 Before using BitBake to start the build, you can
614 look at this file and be sure your general
615 configurations are how you want them:
616 <itemizedlist>
617 <listitem><para>
618 To help conserve disk space during builds,
619 you can add the following statement to your
620 project's configuration file, which for this
621 example is
622 <filename>poky/build/conf/local.conf</filename>.
623 Adding this statement deletes the work
624 directory used for building a recipe once the
625 recipe is built.
626 <literallayout class='monospaced'>
627 INHERIT += "rm_work"
628 </literallayout>
629 </para></listitem>
630 <listitem><para>
631 By default, the target machine for the build is
632 <filename>qemux86</filename>,
633 which produces an image that can be used in
634 the QEMU emulator and is targeted at an
635 <trademark class='registered'>Intel</trademark>
636 32-bit based architecture.
637 Further on in this example, this default is
638 easily changed through the
639 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
640 variable so that you can quickly
641 build an image for a different machine.
642 </para></listitem>
643 <listitem><para>
644 Another consideration before you build is the
645 package manager used when creating the image.
646 The default <filename>local.conf</filename>
647 file selects the RPM package manager.
648 You can control this configuration by using the
649 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename>
650 variable.</para>
651 <para>Selection of the package manager is separate
652 from whether package management is used at runtime
653 in the target image.</para>
654 <para>For additional package manager selection
655 information, see the
656 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package.bbclass</filename></ulink>"
657 section in the Yocto Project Reference Manual.
658 </para></listitem>
659 </itemizedlist>
660 </para></listitem>
661 <listitem><para>
662 <emphasis>Start the Build:</emphasis>
663 Continue with the following command to build an OS image
664 for the target, which is
665 <filename>core-image-sato</filename> in this example:
666 <note>
667 Depending on the number of processors and cores, the
668 amount of RAM, the speed of your Internet connection
669 and other factors, the build process could take
670 several hours the first time you run it.
671 Subsequent builds run much faster since parts of the
672 build are cached.
673 </note>
674 <literallayout class='monospaced'>
675 $ bitbake core-image-sato
676 </literallayout>
677 <note>
678 <para>
679 If you experience a build error due to resources
680 temporarily being unavailable and it appears you
681 should not be having this issue, it might be due
682 to the combination of a 4.3+ Linux kernel and
683 <filename>systemd</filename> version 228+
684 (i.e. see this
685 <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
686 for information).
687 </para>
688
689 <para>
690 To work around this issue, you can try either
691 of the following:
692 <itemizedlist>
693 <listitem><para>
694 Try the build again.
695 </para></listitem>
696 <listitem><para>
697 Modify the "DefaultTasksMax"
698 <filename>systemd</filename> parameter
699 by uncommenting it and setting it to
700 "infinity".
701 You can find this parameter in the
702 <filename>system.conf</filename> file
703 located in
704 <filename>/etc/systemd</filename>
705 on most systems.
706 </para></listitem>
707 </itemizedlist>
708 </para>
709 </note>
710 For information on using the
711 <filename>bitbake</filename> command, see the
712 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
713 section in the Yocto Project Reference Manual, or see the
714 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"
715 section in the BitBake User Manual.
716 For information on other targets, see the
717 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
718 chapter in the Yocto Project Reference Manual.
719 </para></listitem>
720 <listitem><para>
721 <emphasis>Simulate Your Image Using QEMU:</emphasis>
722 Once this particular image is built, you can start QEMU
723 and run the image:
724 <literallayout class='monospaced'>
725 $ runqemu qemux86
726 </literallayout>
727 If you want to learn more about running QEMU, see the
728 "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
729 chapter in the Yocto Project Development Tasks Manual.
730 </para></listitem>
731 <listitem><para>
732 <emphasis>Exit QEMU:</emphasis>
733 Exit QEMU by either clicking on the shutdown icon or by
734 typing <filename>Ctrl-C</filename> in the QEMU
735 transcript window from which you evoked QEMU.
736 </para></listitem>
737 </orderedlist>
738 </para>
739 </section>
740
741 <section id='building-an-image-for-hardware'>
742 <title>Building an Image for Hardware</title>
743
744 <para id='qs-minnowboard-example'>
745 The following steps show how easy it is to set up to build an
746 image for a new machine.
747 These steps build an image for the MinnowBoard Turbot, which is
748 supported by the Yocto Project and the
749 <filename>meta-intel</filename> <filename>intel-corei7-64</filename>
750 and <filename>intel-core2-32</filename> Board Support Packages
751 (BSPs).
752 <note>
753 The MinnowBoard Turbot ships with 64-bit firmware.
754 If you want to use the board in 32-bit mode, you must
755 download the
756 <ulink url='http://firmware.intel.com/projects/minnowboard-max'>32-bit firmware</ulink>.
757 </note>
758 </para>
759
760 <para>
761 <orderedlist>
762 <listitem><para>
763 <emphasis>Create a Local Copy of the
764 <filename>meta-intel</filename> Repository:</emphasis>
765 Building an image for the MinnowBoard Turbot requires
766 the
767 <filename>meta-intel</filename> layer.
768 Use the <filename>git clone</filename> command to create
769 a local copy of the repository inside your
770 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
771 which is <filename>poky</filename> in this example:
772 <literallayout class='monospaced'>
773 $ cd $HOME/poky
774 $ git clone git://git.yoctoproject.org/meta-intel
775 Cloning into 'meta-intel'...
776 remote: Counting objects: 14039, done.
777 remote: Compressing objects: 100% (4471/4471), done.
778 remote: Total 14039 (delta 8130), reused 13837 (delta 7947)
779 Receiving objects: 100% (14039/14039), 4.27 MiB | 3.98 MiB/s, done.
780 Resolving deltas: 100% (8130/8130), done.
781 Checking connectivity... done.
782 </literallayout>
783 By default when you clone a Git repository, the
784 "master" branch is checked out.
785 Before you build your image that uses the
786 <filename>meta-intel</filename> layer, you must be
787 sure that both repositories
788 (<filename>meta-intel</filename> and
789 <filename>poky</filename>) are using the same releases.
790 Because you used the <filename>&DISTRO_REL_TAG;</filename>
791 tag when you checked out the <filename>poky</filename>
792 repository by tag, you should use a
793 <filename>meta-intel</filename>
794 tag that corresponds with the release you used for
795 <filename>poky</filename>.
796 Consequently, you need to checkout out the
797 "<filename>&METAINTELVERSION;-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;</filename>"
798 branch after cloning <filename>meta-intel</filename>:
799 <literallayout class='monospaced'>
800 $ cd $HOME/poky/meta-intel
801 $ git checkout tags/&METAINTELVERSION;-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION; -b meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;
802 Switched to a new branch 'meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;'
803 </literallayout>
804 The previous Git <filename>checkout</filename> command
805 creates a local branch named
806 <filename>meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;</filename>.
807 You have the option to name your local branch whatever
808 you want by providing any name you like for
809 "meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;"
810 in the above example.
811 </para></listitem>
812 <listitem><para>
813 <emphasis>Configure the Build:</emphasis>
814 To configure the build, you edit the
815 <filename>bblayers.conf</filename> and
816 <filename>local.conf</filename> files, both of which are
817 located in the <filename>build/conf</filename> directory.
818 </para>
819
820 <para>Here is a quick way to make the edits.
821 The first command uses the
822 <filename>bitbake-layers add-layer</filename> command
823 to add the <filename>meta-intel</filename>
824 layer, which contains the <filename>intel-core*</filename>
825 BSPs to the build.
826 The second command selects the BSP by setting the
827 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
828 variable.
829 <literallayout class='monospaced'>
830 $ cd $HOME/poky/build
831 $ bitbake-layers add-layer "$HOME/poky/meta-intel"
832 $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf
833 </literallayout>
834 <note><title>Notes</title>
835 <para>
836 If you want a 64-bit build, use the following:
837 <literallayout class='monospaced'>
838 $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf
839 </literallayout>
840 </para>
841
842 <para>
843 If you want 32-bit images, use the following:
844 <literallayout class='monospaced'>
845 $ echo 'MACHINE = "intel-core2-32"' >> conf/local.conf
846 </literallayout>
847 </para>
848 </note>
849 </para></listitem>
850 <listitem><para>
851 <emphasis>Build an Image for MinnowBoard
852 Turbot:</emphasis>
853 The type of image you build depends on your goals.
854 For example, the previous build created a
855 <filename>core-image-sato</filename> image, which is an
856 image with Sato support.
857 It is possible to build many image types for the
858 MinnowBoard Turbot.
859 Some possibilities are <filename>core-image-base</filename>,
860 which is a console-only image.
861 Another choice could be a
862 <filename>core-image-full-cmdline</filename>, which is
863 another console-only image but has more full-features
864 Linux system functionality installed.
865 For types of images you can build using the Yocto
866 Project, see the
867 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
868 chapter in the Yocto Project Reference Manual.</para>
869 <para>Because configuration changes are minimal to set up
870 for this second build, the OpenEmbedded build system can
871 re-use files from previous builds as much as possible.
872 Re-using files means this second build will be much faster
873 than an initial build.
874 For this example, the <filename>core-image-base</filename>
875 image is built:
876 <literallayout class='monospaced'>
877 $ bitbake core-image-base
878 </literallayout>
879 <note>
880 <para>
881 If you experience a build error due to resources
882 temporarily being unavailable and it appears you
883 should not be having this issue, it might be due
884 to the combination of a 4.3+ Linux kernel and
885 <filename>systemd</filename> version 228+
886 (i.e. see this
887 <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
888 for information).
889 </para>
890
891 <para>
892 To work around this issue, you can try either
893 of the following:
894 <itemizedlist>
895 <listitem><para>
896 Try the build again.
897 </para></listitem>
898 <listitem><para>
899 Modify the "DefaultTasksMax"
900 <filename>systemd</filename> parameter
901 by uncommenting it and setting it to
902 "infinity".
903 You can find this parameter in the
904 <filename>system.conf</filename> file
905 located in
906 <filename>/etc/systemd</filename>
907 on most systems.
908 </para></listitem>
909 </itemizedlist>
910 </para>
911 </note>
912 Once the build completes, the resulting console-only image
913 is located in the Build Directory here:
914 <literallayout class='monospaced'>
915 tmp/deploy/images/intel-corei7-64/core-image-base-intel-corei7-64.wic
916 </literallayout>
917 </para></listitem>
918 <listitem><para>
919 <emphasis>Write the Image:</emphasis>
920 You can write the image just built to a bootable media
921 (e.g. a USB key, SATA drive, SD card, etc.) using the
922 <filename>dd</filename> utility:
923 <literallayout class='monospaced'>
924 $ sudo dd if=tmp/deploy/images/intel-corei7-64/core-image-base-intel-corei7-64.wic of=TARGET_DEVICE
925 </literallayout>
926 In the previous command, the
927 <filename>TARGET_DEVICE</filename> is the device node in
928 the host machine (e.g. <filename>/dev/sdc</filename>, which
929 is most likely a USB stick, or
930 <filename>/dev/mmcblk0</filename>, which is most likely an
931 SD card).
932 </para></listitem>
933 <listitem><para>
934 <emphasis>Boot the Hardware:</emphasis>
935 With the boot device provisioned, you can insert the
936 media into the MinnowBoard Turbot and boot the hardware.
937 The board should automatically detect the media and boot to
938 the bootloader and subsequently the operating system.
939 </para>
940
941 <para>If the board does not boot automatically, you can
942 boot it manually from the EFI shell as follows:
943 <literallayout class='monospaced'>
944 Shell> connect -r
945 Shell> map -r
946 Shell> fs0:
947 Shell> bootx64
948 </literallayout>
949 <note>
950 For a 32-bit image use the following:
951 <literallayout class='monospaced'>
952 Shell> bootia32
953 </literallayout>
954 </note>
955 </para></listitem>
956 </orderedlist>
957 </para>
958 </section>
959 </section>
960
961 <section id='qs-next-steps'>
962 <title>Next Steps</title>
963
964 <para>
965 If you completed all the steps in the previous section then
966 congratulations!
967 What now?
968 </para>
969 176
970 <para> 177</book>
971 Depending on what you primary interests are with the Yocto Project,
972 you could consider any of the following:
973 <itemizedlist>
974 <listitem><para>
975 <emphasis>Visit the Yocto Project Web Site:</emphasis>
976 The official
977 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
978 web site contains information on the entire project.
979 Visiting this site is a good way to familiarize yourself
980 with the overall project.
981 </para></listitem>
982 <listitem><para>
983 <emphasis>Look Through the
984 <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-intro'>Yocto Project Development Tasks Manual</ulink>:</emphasis>
985 This manual contains procedural information grouped to
986 help you get set up, work with layers, customize images,
987 write new recipes, work with libraries, and use QEMU.
988 The information is task-based and spans the breadth of the
989 Yocto Project.
990 </para></listitem>
991 <listitem><para>
992 <emphasis>Look Through the
993 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
994 manual:</emphasis>
995 This manual describes how to use both the
996 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink>
997 and the
998 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>,
999 which are used primarily for application development.
1000 This manual also provides example workflows
1001 that use the popular <trademark class='trade'>Eclipse</trademark>
1002 development environment and that use <filename>devtool</filename>.
1003 See the
1004 "<ulink url='&YOCTO_DOCS_SDK_URL;#workflow-using-eclipse'>Workflow using Eclipse™</ulink>"
1005 and
1006 "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in your SDK Workflow</ulink>"
1007 sections for more information.
1008 </para></listitem>
1009 <listitem><para>
1010 <emphasis>Learn About Kernel Development:</emphasis>
1011 If you want to see how to work with the kernel and
1012 understand Yocto Linux kernels, see the
1013 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-dev-intro'>Yocto Project Linux Kernel Development Manual</ulink>.
1014 This manual provides information on how to patch the
1015 kernel, modify kernel recipes, and configure the kernel.
1016 </para></listitem>
1017 <listitem><para>
1018 <emphasis>Learn About Board Support Packages (BSPs):</emphasis>
1019 If you want to learn about BSPs, see the
1020 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>.
1021 This manual also provides an example BSP creation workflow.
1022 See the
1023 <ulink url='&YOCTO_DOCS_BSP_URL;#developing-a-board-support-package-bsp'>"Developing a Board Support Package (BSP)</ulink>"
1024 section.
1025 </para></listitem>
1026 <listitem><para>
1027 <emphasis>Learn About Toaster:</emphasis>
1028 Toaster is a web interface to the Yocto Project's
1029 OpenEmbedded build system.
1030 If you are interested in using this type of interface to
1031 create images, see the
1032 <ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink>.
1033 </para></listitem>
1034 <listitem><para>
1035 <emphasis>Have Available the
1036 <ulink url='&YOCTO_DOCS_REF_URL;#ref-manual-intro'>Yocto Project Reference Manual:</ulink></emphasis>
1037 Unlike the rest of the Yocto Project manual set, this manual
1038 is comprised of material suited for reference rather than
1039 procedures.
1040 You can get
1041 <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky'>build details</ulink>,
1042 a
1043 <ulink url='&YOCTO_DOCS_REF_URL;#development-concepts'>closer look</ulink>
1044 at how the pieces of the Yocto Project development
1045 environment work together, information on various
1046 <ulink url='&YOCTO_DOCS_REF_URL;#technical-details'>technical details</ulink>,
1047 guidance on
1048 <ulink url='&YOCTO_DOCS_REF_URL;#migration'>migrating to a newer Yocto Project release</ulink>,
1049 reference material on the
1050 <ulink url='&YOCTO_DOCS_REF_URL;#ref-structure'>directory structure</ulink>,
1051 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>classes</ulink>,
1052 and
1053 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks'>tasks</ulink>.
1054 The Yocto Project Reference Manual also contains a fairly
1055 comprehensive
1056 <ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glossary'>glossary of variables</ulink>
1057 used within the Yocto Project.
1058 </para></listitem>
1059 </itemizedlist>
1060 </para>
1061 </section>
1062</article>
1063<!-- 178<!--
1064vim: expandtab tw=80 ts=4 179vim: expandtab tw=80 ts=4
1065--> 180-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-11 19:53:17 +0000