summaryrefslogtreecommitdiffstats
path: root/documentation/yocto-project-qs/qs.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/yocto-project-qs/qs.xml')
-rw-r--r--documentation/yocto-project-qs/qs.xml1116
1 files changed, 1116 insertions, 0 deletions
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-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-24 05:08:57 +0000