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