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