summaryrefslogtreecommitdiffstats
path: root/documentation/yocto-project-qs/yocto-project-qs.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/yocto-project-qs/yocto-project-qs.xml')
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml963
1 files changed, 963 insertions, 0 deletions
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
new file mode 100644
index 0000000000..3d6f98d5d5
--- /dev/null
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -0,0 +1,963 @@
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<article id='intro'>
6 <articleinfo>
7 <title>Yocto Project Quick Start</title>
8
9 <copyright>
10 <year>&COPYRIGHT_YEAR;</year>
11 <holder>Linux Foundation</holder>
12 </copyright>
13
14 <legalnotice>
15 <para>
16 Permission is granted to copy, distribute and/or modify this document under
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.
18 </para>
19 <note>
20 For the latest version of this manual associated with this
21 Yocto Project release, see the
22 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
23 from the Yocto Project website.
24 </note>
25 </legalnotice>
26
27
28 <abstract>
29 <imagedata fileref="figures/yocto-project-transp.png"
30 width="6in" depth="1in"
31 align="right" scale="25" />
32 </abstract>
33 </articleinfo>
34
35<section id='welcome'>
36 <title>Welcome!</title>
37 <para>
38 Welcome to the Yocto Project!
39 The Yocto Project is an open-source collaboration project focused on embedded Linux
40 developers.
41 Among other things, the Yocto Project uses a build system based on the Poky project
42 to construct complete Linux images.
43 The Poky project, in turn, draws from and contributes back to the OpenEmbedded project.
44 </para>
45
46 <para>
47 If you don't have a system that runs Linux and you want to give the Yocto Project a test run,
48 you might consider using the Yocto Project Build Appliance.
49 The Build Appliance allows you to build and boot a custom embedded Linux image with the Yocto
50 Project using a non-Linux development system.
51 See the <ulink url='http://www.yoctoproject.org/documentation/build-appliance'>Yocto
52 Project Build Appliance</ulink> for more information.
53 </para>
54
55 <para>
56 On the other hand, if you know all about open-source development, Linux development environments,
57 Git source repositories and the like and you just want some quick information that lets you try out
58 the Yocto Project on your Linux system, skip right to the
59 "<link linkend='super-user'>Super User</link>" section at the end of this quick start.
60 </para>
61
62 <para>
63 For the rest of you, this short document will give you some basic information about the environment and
64 let you experience it in its simplest form.
65 After reading this document, you will have a basic understanding of what the Yocto Project is
66 and how to use some of its core components.
67 This document steps you through a simple example showing you how to build a small image
68 and run it using the Quick EMUlator (QEMU emulator).
69 </para>
70
71 <para>
72 For more detailed information on the Yocto Project, you should check out these resources:
73 <itemizedlist>
74 <listitem><para><emphasis>Website:</emphasis> The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
75 provides the latest builds, breaking news, full development documentation, and a rich Yocto
76 Project Development Community into which you can tap.
77 </para></listitem>
78 <listitem><para><emphasis>FAQs:</emphasis> Lists commonly asked Yocto Project questions and answers.
79 You can find two FAQs: <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>Yocto Project FAQ</ulink> on
80 a wiki, and the
81 "<ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink>" chapter in
82 the Yocto Project Reference Manual.
83 </para></listitem>
84 <listitem><para><emphasis>Developer Screencast:</emphasis> The
85 <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New
86 Developer Screencast Tutorial</ulink> provides a 30-minute video for the user
87 new to the Yocto Project but familiar with Linux build systems.</para></listitem>
88 </itemizedlist>
89 </para>
90</section>
91
92<section id='yp-intro'>
93 <title>Introducing the Yocto Project Development Environment</title>
94 <para>
95 The Yocto Project through the OpenEmbedded build system provides an open source development
96 environment targeting the ARM, MIPS, PowerPC and x86 architectures for a variety of
97 platforms including x86-64 and emulated ones.
98 You can use components from the Yocto Project to design, develop, build, debug, simulate,
99 and test the complete software stack using Linux, the X Window System, GNOME Mobile-based
100 application frameworks, and Qt frameworks.
101 </para>
102
103 <mediaobject>
104 <imageobject>
105 <imagedata fileref="figures/yocto-environment.png"
106 format="PNG" align='center' scalefit='1' width="100%"/>
107 </imageobject>
108 <caption>
109 <para>The Yocto Project Development Environment</para>
110 </caption>
111 </mediaobject>
112
113 <para>
114 Here are some highlights for the Yocto Project:
115 </para>
116
117 <itemizedlist>
118 <listitem>
119 <para>Provides a recent Linux kernel along with a set of system commands and libraries suitable for the embedded environment.</para>
120 </listitem>
121 <listitem>
122 <para>Makes available system components such as X11, GTK+, Qt, Clutter, and SDL
123 (among others) so you can create a rich user experience on devices
124 that have display hardware.
125 For devices that don't have a display or where you wish to use alternative UI
126 frameworks, these components need not be installed.</para>
127 </listitem>
128 <listitem>
129 <para>Creates a focused and stable core compatible with the OpenEmbedded
130 project with which you can easily and reliably build and develop.</para>
131 </listitem>
132 <listitem>
133 <para>Fully supports a wide range of hardware and device emulation through the QEMU
134 Emulator.</para>
135 </listitem>
136 </itemizedlist>
137
138 <para>
139 The Yocto Project can generate images for many kinds of devices.
140 However, the standard example machines target QEMU full-system emulation for x86, x86-64, ARM, MIPS,
141 and PPC-based architectures as well as specific hardware such as the
142 <trademark class='registered'>Intel</trademark> Desktop Board DH55TC.
143 Because an image developed with the Yocto Project can boot inside a QEMU emulator, the
144 development environment works nicely as a test platform for developing embedded software.
145 </para>
146
147 <para>
148 Another important Yocto Project feature is the Sato reference User Interface.
149 This optional GNOME mobile-based UI, which is intended for devices with
150 restricted screen sizes, sits neatly on top of a device using the
151 GNOME Mobile Stack and provides a well-defined user experience.
152 Implemented in its own layer, it makes it clear to developers how they can implement
153 their own user interface on top of a Linux image created with the Yocto Project.
154 </para>
155</section>
156
157<section id='yp-resources'>
158 <title>What You Need and How You Get It</title>
159
160 <para>
161 You need these things to develop in the Yocto Project environment:
162 </para>
163
164 <itemizedlist>
165 <listitem>
166 <para>A host system running a supported Linux distribution
167 (i.e. recent releases of Fedora, openSUSE, CentOS, Debian,
168 and Ubuntu).
169 If the host system supports multiple cores and threads, you can configure the
170 Yocto Project build system to decrease the time needed to build images
171 significantly.
172 </para>
173 </listitem>
174 <listitem>
175 <para>The right packages.</para>
176 </listitem>
177 <listitem>
178 <para>A release of the Yocto Project.</para>
179 </listitem>
180 </itemizedlist>
181
182 <section id='the-linux-distro'>
183 <title>The Linux Distribution</title>
184
185 <para>
186 The Yocto Project team is continually verifying more and more Linux
187 distributions with each release.
188 In general, if you have the current release minus one of the following
189 distributions you should have no problems.
190 <itemizedlist>
191 <listitem><para>Ubuntu</para></listitem>
192 <listitem><para>Fedora</para></listitem>
193 <listitem><para>openSUSE</para></listitem>
194 <listitem><para>CentOS</para></listitem>
195 <listitem><para>Debian</para></listitem>
196 </itemizedlist>
197 For a more detailed list of distributions that support the Yocto Project,
198 see the
199 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
200 in the Yocto Project Reference Manual.
201 </para>
202 <para>
203 The OpenEmbedded build system should be able to run on any modern
204 distribution that has the following versions for Git, tar, and
205 Python.
206 <itemizedlist>
207 <listitem><para>Git 1.7.5 or greater</para></listitem>
208 <listitem><para>tar 1.24 or greater</para></listitem>
209 <listitem><para>Python 2.7.3 or greater excluding Python
210 3.x, which is not supported.</para></listitem>
211 </itemizedlist>
212 Earlier releases of Python are known to not work and the system
213 does not support Python 3 at this time.
214 If your system does not meet any of these three listed
215 version requirements, you can
216 take steps to prepare the system so that you can still use the build
217 system.
218 See the
219 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
220 section in the Yocto Project Reference Manual for information.
221 </para>
222 <para>
223 This document assumes you are running one of the previously noted
224 distributions on your Linux-based host systems.
225 </para>
226 <note>
227 <para>
228 If you attempt to use a distribution not in the above list,
229 you may or may not have success.
230 Yocto Project releases are tested against the stable Linux
231 distributions listed in the
232 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
233 section of the Yocto Project Reference Manual.
234 Refer to
235 <ulink url='&OE_HOME_URL;/index.php?title=OEandYourDistro'>OE and Your Distro</ulink> and
236 <ulink url='&OE_HOME_URL;/index.php?title=Required_software'>Required Software</ulink>
237 for information for information about dependencies and
238 requirements.
239 If you encounter problems, please go to
240 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
241 and submit a bug.
242 We are interested in hearing about your experience.
243 </para>
244 </note>
245 </section>
246
247 <section id='packages'>
248 <title>The Packages</title>
249
250 <para>
251 Packages and package installation vary depending on your development system
252 and on your intent.
253 For example, if you want to build an image that can run
254 on QEMU in graphical mode (a minimal, basic build
255 requirement), then the number of packages is different than if you want to
256 build an image on a headless system or build out the Yocto Project
257 documentation set.
258 Collectively, the number of required packages is large
259 if you want to be able to cover all cases.
260 <note>In general, you need to have root access and then install the
261 required packages.
262 Thus, the commands in the following section may or may not work
263 depending on whether or not your Linux distribution has
264 <filename>sudo</filename> installed.</note>
265 </para>
266
267 <para>
268 The next few sections list, by supported Linux Distributions, the required
269 packages needed to build an image that runs on QEMU in graphical mode
270 (e.g. essential plus graphics support).
271 </para>
272
273 <para>
274 For lists of required packages for other scenarios, see the
275 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
276 section in the Yocto Project Reference Manual.
277 </para>
278
279 <section id='ubuntu'>
280 <title>Ubuntu and Debian</title>
281
282 <para>
283 The essential and graphical support packages you need for a
284 supported Ubuntu or Debian distribution are shown in the
285 following command:
286 <literallayout class='monospaced'>
287 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
288 </literallayout>
289 </para>
290 </section>
291
292 <section id='fedora'>
293 <title>Fedora</title>
294
295 <para>
296 The essential and graphical packages you need for a supported
297 Fedora distribution are shown in the following command:
298 <literallayout class='monospaced'>
299 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
300 </literallayout>
301 </para>
302 </section>
303
304 <section id='opensuse'>
305 <title>OpenSUSE</title>
306
307 <para>
308 The essential and graphical packages you need for a supported
309 OpenSUSE distribution are shown in the following command:
310 <literallayout class='monospaced'>
311 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm
312 </literallayout>
313 </para>
314 </section>
315
316 <section id='centos'>
317 <title>CentOS</title>
318
319 <para>
320 The essential and graphical packages you need for a supported
321 CentOS distribution are shown in the following command:
322 <literallayout class='monospaced'>
323 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
324 </literallayout>
325 <note>Depending on the CentOS version you are using, other requirements
326 and dependencies might exist.
327 For details, you should look at the CentOS sections on the
328 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
329 wiki page.</note>
330 </para>
331 </section>
332 </section>
333
334 <section id='releases'>
335 <title>Yocto Project Release</title>
336
337 <para>
338 You can download the latest Yocto Project release by going to the
339 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>
340 clicking "Downloads" in the navigation pane to the left to view all
341 available Yocto Project releases.
342 Current and archived releases are available for download to the
343 right.
344 Nightly and developmental builds are also maintained at
345 <ulink url="&YOCTO_AB_NIGHTLY_URL;"></ulink>.
346 However, for this document a released version of Yocto Project is used.
347 </para>
348
349 <para>
350 You can also get the Yocto Project files you need by setting up (cloning in Git terms)
351 a local copy of the <filename>poky</filename> Git repository on your host development
352 system.
353 Doing so allows you to contribute back to the Yocto Project project.
354 For information on how to get set up using this method, see the
355 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto
356 Project Release</ulink>" item in the Yocto Project Development Manual.
357 </para>
358 </section>
359</section>
360
361<section id='test-run'>
362 <title>A Quick Test Run</title>
363
364 <para>
365 Now that you have your system requirements in order, you can give the Yocto Project a try.
366 This section presents some steps that let you do the following:
367 </para>
368
369 <itemizedlist>
370 <listitem>
371 <para>Build an image and run it in the QEMU emulator</para>
372 </listitem>
373 <listitem>
374 <para>Use a pre-built image and run it in the QEMU emulator</para>
375 </listitem>
376 </itemizedlist>
377
378 <section id='building-image'>
379 <title>Building an Image</title>
380
381 <para>
382 In the development environment you will need to build an image whenever you change hardware
383 support, add or change system libraries, or add or change services that have dependencies.
384 </para>
385
386 <mediaobject>
387 <imageobject>
388 <imagedata fileref="figures/building-an-image.png" format="PNG" align='center' scalefit='1'/>
389 </imageobject>
390 <caption>
391 <para>Building an Image</para>
392 </caption>
393 </mediaobject>
394
395 <para>
396 Use the following commands to build your image.
397 The OpenEmbedded build process creates an entire Linux distribution, including the toolchain,
398 from source.
399 </para>
400
401 <note><para>
402 The build process using Sato currently consumes about 50GB of disk space.
403 To allow for variations in the build process and for future package expansion, we
404 recommend having at least 100GB of free disk space.
405 </para></note>
406
407 <note><para>
408 By default, the build process searches for source code using a pre-determined order
409 through a set of locations.
410 If you encounter problems with the build process finding and downloading source code, see the
411 "<ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>How does the OpenEmbedded build system obtain source code and will it work behind my
412 firewall or proxy server?</ulink>" in the Yocto Project Reference Manual.
413 </para></note>
414
415 <para>
416 <literallayout class='monospaced'>
417 $ wget &YOCTO_POKY_DL_URL;
418 $ tar xjf &YOCTO_POKY;.tar.bz2
419 $ cd &YOCTO_POKY;
420 $ source &OE_INIT_FILE;
421 </literallayout>
422 </para>
423
424 <tip><para>
425 To help conserve disk space during builds, you can add the following statement
426 to your project's configuration file, which for this example
427 is <filename>&YOCTO_POKY;/build/conf/local.conf</filename>.
428 Adding this statement deletes the work directory used for building a package
429 once the package is built.
430 <literallayout class='monospaced'>
431 INHERIT += "rm_work"
432 </literallayout>
433 </para></tip>
434
435 <itemizedlist>
436 <listitem><para>In the previous example, the first command retrieves the Yocto Project
437 release tarball from the source repositories using the
438 <filename>wget</filename> command.
439 Alternatively, you can go to the
440 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink>
441 "Downloads" page to retrieve the tarball.</para></listitem>
442 <listitem><para>The second command extracts the files from the tarball and places
443 them into a directory named <filename>&YOCTO_POKY;</filename> in the current
444 directory.</para></listitem>
445 <listitem><para>The third and fourth commands change the working directory to the
446 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
447 and run the Yocto Project
448 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
449 environment setup script.
450 Running this script defines OpenEmbedded build environment settings needed to
451 complete the build.
452 The script also creates the
453 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
454 which is <filename>build</filename> in this case and is located in the
455 Source Directory.
456 After the script runs, your current working directory is set
457 to the Build Directory.
458 Later, when the build completes, the Build Directory contains all the files
459 created during the build.
460 <note>
461 For information on running a memory-resident BitBake, see
462 the
463 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
464 setup script.
465 </note></para></listitem>
466 </itemizedlist>
467 <para>
468 Take some time to examine your <filename>local.conf</filename> file
469 in your project's configuration directory, which is found in the Build Directory.
470 The defaults in that file should work fine.
471 However, there are some variables of interest at which you might look.
472 </para>
473
474 <para>
475 By default, the target architecture for the build is <filename>qemux86</filename>,
476 which produces an image that can be used in the QEMU emulator and is targeted at an
477 <trademark class='registered'>Intel</trademark> 32-bit based architecture.
478 To change this default, edit the value of the
479 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
480 variable in the configuration file before launching the build.
481 </para>
482
483 <para>
484 Another couple of variables of interest are the
485 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink> and the
486 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> variables.
487 By default, these variables are commented out.
488 However, if you have a multi-core CPU you might want to uncomment
489 the lines and set both variables equal to twice the number of your
490 host's processor cores.
491 Setting these variables can significantly shorten your build time.
492 </para>
493
494 <para>
495 Another consideration before you build is the package manager used when creating
496 the image.
497 By default, the OpenEmbedded build system uses the RPM package manager.
498 You can control this configuration by using the
499 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename> variable.
500 For additional package manager selection information, see the
501 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'>Packaging - <filename>package*.bbclass</filename></ulink>"
502 section in the Yocto Project Reference Manual.
503 </para>
504
505 <para>
506 Continue with the following command to build an OS image for the target, which is
507 <filename>core-image-sato</filename> in this example.
508 For information on the <filename>-k</filename> option use the
509 <filename>bitbake --help</filename> command or see the
510 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>" section in
511 the Yocto Project Reference Manual.
512 <literallayout class='monospaced'>
513 $ bitbake -k core-image-sato
514 </literallayout>
515 <note><para>
516 BitBake requires Python 2.6 or 2.7. For more information on this requirement,
517 see the
518 <ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink> in the Yocto Project Reference
519 Manual.
520 </para></note>
521 The final command runs the image:
522 <literallayout class='monospaced'>
523 $ runqemu qemux86
524 </literallayout>
525 <note><para>
526 Depending on the number of processors and cores, the amount or RAM, the speed of your
527 Internet connection and other factors, the build process could take several hours the first
528 time you run it.
529 Subsequent builds run much faster since parts of the build are cached.
530 </para></note>
531 </para>
532 </section>
533
534 <section id='using-pre-built'>
535 <title>Using Pre-Built Binaries and QEMU</title>
536
537 <para>
538 If hardware, libraries and services are stable, you can get started by using a pre-built binary
539 of the filesystem image, kernel, and toolchain and run it using the QEMU emulator.
540 This scenario is useful for developing application software.
541 </para>
542
543 <mediaobject>
544 <imageobject>
545 <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/>
546 </imageobject>
547 <caption>
548 <para>Using a Pre-Built Image</para>
549 </caption>
550 </mediaobject>
551
552 <para>
553 For this scenario, you need to do several things:
554 </para>
555
556 <itemizedlist>
557 <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem>
558 <listitem><para>Download the pre-built image that will boot with QEMU.
559 You need to be sure to get the QEMU image that matches your target machine’s
560 architecture (e.g. x86, ARM, etc.).</para></listitem>
561 <listitem><para>Download the filesystem image for your target machine's architecture.
562 </para></listitem>
563 <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator.
564 </para></listitem>
565 </itemizedlist>
566
567 <section id='installing-the-toolchain'>
568 <title>Installing the Toolchain</title>
569
570 <para>
571 You can download a tarball installer, which includes the
572 pre-built toolchain, the <filename>runqemu</filename>
573 script, and support files from the appropriate directory under
574 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
575 Toolchains are available for 32-bit and 64-bit x86 development
576 systems from the <filename>i686</filename> and
577 <filename>x86_64</filename> directories, respectively.
578 The toolchains the Yocto Project provides are based off the
579 <filename>core-image-sato</filename> image and contain
580 libraries appropriate for developing against that image.
581 Each type of development system supports five or more target
582 architectures.
583 </para>
584
585 <para>
586 The names of the tarball installer scripts are such that a
587 string representing the host system appears first in the
588 filename and then is immediately followed by a string
589 that represents the target architecture.
590 </para>
591
592 <literallayout class='monospaced'>
593 poky-eglibc-&lt;<emphasis>host_system</emphasis>&gt;-&lt;<emphasis>image_type</emphasis>&gt;-&lt;<emphasis>arch</emphasis>&gt;-toolchain-&lt;<emphasis>release_version</emphasis>&gt;.sh
594
595 Where:
596 &lt;<emphasis>host_system</emphasis>&gt; is a string representing your development system:
597
598 i686 or x86_64.
599
600 &lt;<emphasis>image_type</emphasis>&gt; is a string representing the image you wish to
601 develop a Software Development Toolkit (SDK) for use against.
602 The Yocto Project builds toolchain installers using the
603 following BitBake command:
604
605 bitbake core-image-sato -c do_populatesdk core-image-sato
606
607 &lt;<emphasis>arch</emphasis>&gt; is a string representing the tuned target architecture:
608
609 i586, x86_64, powerpc, mips, armv7a or armv5te
610
611 &lt;<emphasis>release_version</emphasis>&gt; is a string representing the release number of the
612 Yocto Project:
613
614 &DISTRO;, &DISTRO;+snapshot
615 </literallayout>
616
617 <para>
618 For example, the following toolchain installer is for a 64-bit
619 development host system and a i586-tuned target architecture
620 based off the SDK for <filename>core-image-sato</filename>:
621 <literallayout class='monospaced'>
622 poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
623 </literallayout>
624 </para>
625
626 <para>
627 Toolchains are self-contained and by default are installed into
628 <filename>/opt/poky</filename>.
629 However, when you run the toolchain installer, you can choose an
630 installation directory.
631 </para>
632
633 <para>
634 The following command shows how to run the installer given a toolchain tarball
635 for a 64-bit x86 development host system and a 32-bit x86 target architecture.
636 You must change the permissions on the toolchain
637 installer script so that it is executable.
638 </para>
639
640 <para>
641 The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.
642 <note>
643 If you do not have write permissions for the directory into which you are installing
644 the toolchain, the toolchain installer notifies you and exits.
645 Be sure you have write permissions in the directory and run the installer again.
646 </note>
647 </para>
648
649 <para>
650 <literallayout class='monospaced'>
651 $ ~/Downloads/poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
652 </literallayout>
653 </para>
654
655 <para>
656 For more information on how to install tarballs, see the
657 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and
658 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide.
659 </para>
660 </section>
661
662 <section id='downloading-the-pre-built-linux-kernel'>
663 <title>Downloading the Pre-Built Linux Kernel</title>
664
665 <para>
666 You can download the pre-built Linux kernel suitable for running in the QEMU emulator from
667 <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
668 Be sure to use the kernel that matches the architecture you want to simulate.
669 Download areas exist for the five supported machine architectures:
670 <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,
671 <filename>qemux86</filename>, and <filename>qemux86-64</filename>.
672 </para>
673
674 <para>
675 Most kernel files have one of the following forms:
676 <literallayout class='monospaced'>
677 *zImage-qemu&lt;<emphasis>arch</emphasis>&gt;.bin
678 vmlinux-qemu&lt;<emphasis>arch</emphasis>&gt;.bin
679
680 Where:
681 &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
682 x86, x86-64, ppc, mips, or arm.
683 </literallayout>
684 </para>
685
686 <para>
687 You can learn more about downloading a Yocto Project kernel in the
688 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>"
689 bulleted item in the Yocto Project Development Manual.
690 </para>
691 </section>
692
693 <section id='downloading-the-filesystem'>
694 <title>Downloading the Filesystem</title>
695
696 <para>
697 You can also download the filesystem image suitable for your target architecture from
698 <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
699 Again, be sure to use the filesystem that matches the architecture you want
700 to simulate.
701 </para>
702
703 <para>
704 The filesystem image has two tarball forms: <filename>ext3</filename> and
705 <filename>tar</filename>.
706 You must use the <filename>ext3</filename> form when booting an image using the
707 QEMU emulator.
708 The <filename>tar</filename> form can be flattened out in your host development system
709 and used for build purposes with the Yocto Project.
710 <literallayout class='monospaced'>
711 core-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;.ext3
712 core-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;.tar.bz2
713
714 Where:
715 &lt;<emphasis>profile</emphasis>&gt; is the filesystem image's profile:
716 lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
717 sato-dev, or sato-sdk. For information on these types of image
718 profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in the Yocto Project
719 Reference Manual.
720
721 &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
722 x86, x86-64, ppc, mips, or arm.
723 </literallayout>
724 </para>
725 </section>
726
727 <section id='setting-up-the-environment-and-starting-the-qemu-emulator'>
728 <title>Setting Up the Environment and Starting the QEMU Emulator</title>
729
730 <para>
731 Before you start the QEMU emulator, you need to set up the emulation environment.
732 The following command form sets up the emulation environment.
733 <literallayout class='monospaced'>
734 $ source &YOCTO_ADTPATH_DIR;/environment-setup-&lt;<emphasis>arch</emphasis>&gt;-poky-linux-&lt;<emphasis>if</emphasis>&gt;
735
736 Where:
737 &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
738 i586, x86_64, ppc603e, mips, or armv5te.
739
740 &lt;<emphasis>if</emphasis>&gt; is a string representing an embedded application binary interface.
741 Not all setup scripts include this string.
742 </literallayout>
743 </para>
744
745 <para>
746 Finally, this command form invokes the QEMU emulator
747 <literallayout class='monospaced'>
748 $ runqemu &lt;<emphasis>qemuarch</emphasis>&gt; &lt;<emphasis>kernel-image</emphasis>&gt; &lt;<emphasis>filesystem-image</emphasis>&gt;
749
750 Where:
751 &lt;<emphasis>qemuarch</emphasis>&gt; is a string representing the target architecture: qemux86, qemux86-64,
752 qemuppc, qemumips, or qemuarm.
753
754 &lt;<emphasis>kernel-image</emphasis>&gt; is the architecture-specific kernel image.
755
756 &lt;<emphasis>filesystem-image</emphasis>&gt; is the .ext3 filesystem image.
757
758 </literallayout>
759 </para>
760
761 <para>
762 Continuing with the example, the following two commands setup the emulation
763 environment and launch QEMU.
764 This example assumes the root filesystem (<filename>.ext3</filename> file) and
765 the pre-built kernel image file both reside in your home directory.
766 The kernel and filesystem are for a 32-bit target architecture.
767 <literallayout class='monospaced'>
768 $ cd $HOME
769 $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux
770 $ runqemu qemux86 bzImage-qemux86.bin \
771 core-image-sato-qemux86.ext3
772 </literallayout>
773 </para>
774
775 <para>
776 The environment in which QEMU launches varies depending on the filesystem image and on the
777 target architecture.
778 For example, if you source the environment for the ARM target
779 architecture and then boot the minimal QEMU image, the emulator comes up in a new
780 shell in command-line mode.
781 However, if you boot the SDK image, QEMU comes up with a GUI.
782 <note>Booting the PPC image results in QEMU launching in the same shell in
783 command-line mode.</note>
784 </para>
785 </section>
786 </section>
787</section>
788
789<section id='super-user'>
790 <title>Super User
791</title>
792
793 <para>
794 This section
795 <footnote>
796 <para>
797 Kudos and thanks to Robert P. J. Day of
798 <ulink url='http://www.crashcourse.ca'>CrashCourse</ulink> for providing the basis
799 for this "expert" section with information from one of his
800 <ulink url='http://www.crashcourse.ca/wiki/index.php/Yocto_Project_Quick_Start'>wiki</ulink>
801 pages.
802 </para>
803 </footnote>
804 gives you a minimal description of how to use the Yocto Project to build images
805 for a BeagleBoard xM starting from scratch.
806 The steps were performed on a 64-bit Ubuntu 10.04 system.
807 </para>
808
809 <section id='getting-yocto'>
810 <title>Getting the Yocto Project</title>
811
812 <para>
813 Set up your <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
814 one of two ways:
815 <itemizedlist>
816 <listitem><para><emphasis>Tarball:</emphasis>
817 Use if you want the latest stable release:
818 <literallayout class='monospaced'>
819 $ wget &YOCTO_RELEASE_DL_URL;/&YOCTO_POKY_TARBALL;
820 $ tar xvjf &YOCTO_POKY_TARBALL;
821 </literallayout></para></listitem>
822 <listitem><para><emphasis>Git Repository:</emphasis>
823 Use if you want to work with cutting edge development content:
824 <literallayout class='monospaced'>
825 $ git clone git://git.yoctoproject.org/poky
826 </literallayout></para></listitem>
827 </itemizedlist>
828 The remainder of the section assumes the Git repository method.
829 </para>
830 </section>
831
832 <section id='setting-up-your-host'>
833 <title>Setting Up Your Host</title>
834
835 <para>
836 You need some packages for everything to work.
837 Rather than duplicate them here, look at the "<link linkend='packages'>The Packages</link>"
838 section earlier in this quick start.
839 </para>
840 </section>
841
842 <section id='initializing-the-build-environment'>
843 <title>Initializing the Build Environment</title>
844
845 <para>
846 From the parent directory your
847 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
848 initialize your environment and provide a meaningful
849 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
850 name:
851 <literallayout class='monospaced'>
852 $ source poky/&OE_INIT_FILE; mybuilds
853 </literallayout>
854 At this point, the <filename>mybuilds</filename> directory has been created for you
855 and it is now your current working directory.
856 If you don't provide your own directory name it defaults to <filename>build</filename>,
857 which is inside the Source Directory.
858 </para>
859 </section>
860
861 <section id='configuring-the-local.conf-file'>
862 <title>Configuring the local.conf File</title>
863
864 <para>
865 Initializing the build environment creates a <filename>conf/local.conf</filename> configuration file
866 in the Build Directory.
867 You need to manually edit this file to specify the machine you are building and to optimize
868 your build time.
869 Here are the minimal changes to make:
870 <literallayout class='monospaced'>
871 BB_NUMBER_THREADS = "8"
872 PARALLEL_MAKE = "-j 8"
873 MACHINE ?= "beagleboard"
874 </literallayout>
875 Briefly, set <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>
876 and <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> to
877 twice your host processor's number of cores.
878 </para>
879
880 <para>
881 A good deal that goes into a Yocto Project build is simply
882 downloading all of the source tarballs.
883 Maybe you have been working with another build system
884 (OpenEmbedded or Angstrom) for which you have built up a sizable
885 directory of source tarballs.
886 Or, perhaps someone else has such a directory for which you have
887 read access.
888 If so, you can save time by adding statements to your
889 configuration file so that the build process checks local
890 directories first for existing tarballs before checking the
891 Internet.
892 Here is an efficient way to set it up in your
893 <filename>local.conf</filename> file:
894 <literallayout class='monospaced'>
895 SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/"
896 INHERIT += "own-mirrors"
897 BB_GENERATE_MIRROR_TARBALLS = "1"
898 # BB_NO_NETWORK = "1"
899 </literallayout>
900 </para>
901
902 <para>
903 In the previous example, the
904 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
905 variable causes the OpenEmbedded build system to generate tarballs
906 of the Git repositories and store them in the
907 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
908 directory.
909 Due to performance reasons, generating and storing these tarballs
910 is not the build system's default behavior.
911 </para>
912
913 <para>
914 You can also use the
915 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
916 variable.
917 For an example, see the variable's glossary entry in the
918 Yocto Project Reference Manual.
919 </para>
920 </section>
921
922 <section id='building-the-image'>
923 <title>Building the Image</title>
924
925 <para>
926 At this point, you need to select an image to build for the BeagleBoard xM.
927 If this is your first build using the Yocto Project, you should try the smallest and simplest
928 image:
929 <literallayout class='monospaced'>
930 $ bitbake core-image-minimal
931 </literallayout>
932 Now you just wait for the build to finish.
933 </para>
934
935 <para>
936 Here are some variations on the build process that could be helpful:
937 <itemizedlist>
938 <listitem><para>Fetch all the necessary sources without starting the build:
939 <literallayout class='monospaced'>
940 $ bitbake -c fetchall core-image-minimal
941 </literallayout>
942 This variation guarantees that you have all the sources for that BitBake target
943 should you disconnect from the net and want to do the build later offline.
944 </para></listitem>
945 <listitem><para>Specify to continue the build even if BitBake encounters an error.
946 By default, BitBake aborts the build when it encounters an error.
947 This command keeps a faulty build going:
948 <literallayout class='monospaced'>
949 $ bitbake -k core-image-minimal
950 </literallayout></para></listitem>
951 </itemizedlist>
952 </para>
953
954 <para>
955 Once you have your image, you can take steps to load and boot it on the target hardware.
956 </para>
957 </section>
958</section>
959
960</article>
961<!--
962vim: expandtab tw=80 ts=4
963-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-18 09:56:47 +0000