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