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