summaryrefslogtreecommitdiffstats
path: root/documentation/yocto-project-qs/yocto-project-qs.xml
diff options
context:
space:
mode:
authorRichard Purdie <rpurdie@linux.intel.com>2010-10-15 15:08:01 +0100
committerRichard Purdie <rpurdie@linux.intel.com>2010-10-27 07:50:33 +0100
commit00e061b56455e8bc6ab937a8114386f921f53fa5 (patch)
tree4f9bc25e480b9cc73d6b39efe35a4ee92b8c0804 /documentation/yocto-project-qs/yocto-project-qs.xml
parent74e47d42d60161a3cab97c923e852a42e1ce5940 (diff)
downloadpoky-00e061b56455e8bc6ab937a8114386f921f53fa5.tar.gz
documentation: Add Yocto quickstart guide
Signed-off-by: Richard Purdie <rpurdie@linux.intel.com>
Diffstat (limited to 'documentation/yocto-project-qs/yocto-project-qs.xml')
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml307
1 files changed, 307 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..d67ff41edc
--- /dev/null
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -0,0 +1,307 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<article id='intro'>
5 <imagedata fileref="figures/yocto-project-transp.png" width="6in" depth="1in" align="right" scale="25" />
6
7<section id='fake-title'>
8 <title>Yocto Project Quick Start</title>
9</section>
10
11<section id='welcome'>
12 <title>Welcome!</title>
13 <para>
14 Welcome to the Yocto Project!
15 The Yocto Project is an open-source Linux development environment.
16 This short document will give you some basic information about the environment as well as let you experience it in its simplest form.
17 After reading this document you will have a basic understanding of what the Yocto Project is and how to work within it.
18 This document also steps you through a simple example showing you how to build a small image and run it using the QEMU emulator.
19 </para>
20 <para>
21 For complete information on the Yocto Project you should check out the <ulink url='http://www.yoctolinux.org'>Public Yocto Website</ulink>.
22 You can find the latest builds, breaking news, full development documentation, and a rich Yocto Project Development Community into which you can tap.
23 </para>
24</section>
25
26<section id='yp-intro'>
27 <title>Introducing the Yocto Project Development Environment</title>
28
29 <para>
30 Yocto Project is an open source development environment that creates Linux-based images suitable for many types of devices (large or small) based on architectures such as x86, x86-64, Xeon, ARM, and MIPS as well as PowerPC and device emulation.
31 You can use Yocto Project to design, develop, build, debug, simulate, and test the complete software stack using Linux, the X Window System, GNOME Mobile-based application frameworks, and Qt frameworks.
32 </para>
33
34 <para></para>
35 <para></para>
36
37 <mediaobject>
38 <imageobject>
39 <imagedata fileref="figures/yocto-environment.png" format="PNG" align='center' scalefit='1'/>
40 </imageobject>
41 <caption>
42 <para>The Yocto Project Development Environment</para>
43 </caption>
44 </mediaobject>
45
46 <para>
47 Yocto Project:
48 </para>
49
50 <itemizedlist>
51 <listitem>
52 <para>Provides an open source Linux kernel along with a set of system commands and libraries suitable for the embedded environment.</para>
53 </listitem>
54 <listitem>
55 <para>Makes available system components such as X11, Matchbox, GTK+, Pimlico, Clutter, and Qt (among others) so you can create a richer user interface experience on devices that use displays or have a GUI.
56For devices that don't have a GUI or display you simply would not employ these components.</para>
57 </listitem>
58 <listitem>
59 <para>Creates a focused and stable subset of OpenEmbedded on which you can easily and reliably build and develop.</para>
60 </listitem>
61 <listitem>
62 <para>Fully supports a wide range of hardware and device emulation through the QEMU Emulator or other supported emulators.</para>
63 </listitem>
64 </itemizedlist>
65
66 <para>
67 Yocto Project generates file system images based on open source software such as the Kdrive X server, the Matchbox Window Manager, the GTK+ Toolkit and the D-Bus Message Bus System.
68 Yocto Project can generate images for many kinds of devices.
69 However, the standard example machines target QEMU full system emulation for x86, ARM, MIPS, and PPC based architectures as well as specific hardware such as the Intel Desktop Board DH55TC.
70 Because an image developed with Yocto Project can boot inside a QEMU emulator, the development environment works nicely as a test platform for developing embedded software.
71 </para>
72
73 <para>
74 Another important Yocto Project feature is the Sato component.
75 The optional Sato component, a GNOME mobile-based user interface environment well suited for devices with restricted screen sizes, sits neatly on top of any device using the GNOME Mobile Stack providing a well defined user experience.
76 </para>
77</section>
78
79<section id='resources'>
80 <title>What You Need and How You Get It</title>
81
82 <para>
83 You need these things to develop in the Yocto Project environment:
84 </para>
85
86 <itemizedlist>
87 <listitem>
88 <para>A host system running a supported Linux distribution.
89 For information on distributions on which you can use Yocto Project refer to the information found at <ulink url='http://wiki.openembedded.net/index.php/OEandYourDistro'>http://wiki.openembedded.net/index.php/OEandYourDistro</ulink>.</para>
90 </listitem>
91 <listitem>
92 <para>The right packages.</para>
93 </listitem>
94 <listitem>
95 <para>A release of Yocto Project.</para>
96 </listitem>
97 </itemizedlist>
98
99 <section id='the-linux-distro'>
100 <title>The Linux Distribution</title>
101
102 <para>
103 While this document assumes a Debian-based host system you can develop in the Yocto Linux environment using many other Linux distributions.
104 For Debian-based systems we recommend you use the Ubuntu Release 10.04 or later.
105 </para>
106 </section>
107
108 <section id='packages'>
109 <title>The Packages</title>
110
111 <para>
112 The packages you need for a Debian-based host are shown in the following command:
113 </para>
114
115 <literallayout class='monospaced'>
116 Sudo apt-get install sed wget cvs subversion git-core coreutils
117 unzip texi2html texinfo libsdll.2-dev docbook-utils gawk
118 python-pysqlite2 diffstat help2man make gcc build-essential
119 g++ desktop-file-utils chrpath libgl1-mesa-dev libglu1-mesa-dev
120 libsdl1.2-dev
121 </literallayout>
122
123 <para>
124 <emphasis>NOTE:</emphasis> Packages vary in number and name for other Linux distributions.
125 For package requirements on other Linux distributions refer to the information found at <ulink url='http://wiki.openembedded.net/index.php/OEandYourDistro'>http://wiki.openembedded.net/index.php/OEandYourDistro</ulink>.
126 </para>
127 </section>
128
129 <section id='releases'>
130 <title>Yocto Project Release</title>
131
132 <para>
133 The latest releases for Yocto Project are kept at http://yoctoproject.org/releases.
134 Nightly and developmental builds are also maintained. However, for this document a released version of Yocto Project is used.
135 </para>
136 </section>
137</section>
138
139<section id='test-run'>
140 <title>A Quick Test Run</title>
141
142 <para>
143 Now that you have your system requirements in order you can give Yocto Project a try.
144 This section presents some steps that let you do the following:
145 </para>
146
147 <itemizedlist>
148 <listitem>
149 <para>Build an image and run it in the emulator</para>
150 </listitem>
151 <listitem>
152 <para>Or, use a pre-built image and run it in the emulator</para>
153 </listitem>
154 </itemizedlist>
155
156 <section id='building-image'>
157 <title>Building an Image</title>
158
159 <para>
160 In the development environment you will need to build an image whenever you change hardware support, add or change system libraries, or add or change services that have dependencies.
161 </para>
162
163 <mediaobject>
164 <imageobject>
165 <imagedata fileref="figures/building-an-image.png" format="PNG" align='center' scalefit='1'/>
166 </imageobject>
167 <caption>
168 <para>Building an Image</para>
169 </caption>
170 </mediaobject>
171
172 <para>
173 Use the following commands from a shell on your Debian-based host to build your image.
174 The build creates an entire Linux system including the Toolchain from the source.
175 </para>
176
177 <para><emphasis>NOTE:</emphasis> The build process using Sato currently consumes 50GB of disk space.
178 To allow for vbariations in the build process and for future package expansion we recommend 100GB of free disk space.
179 </para>
180
181 <para>
182 <literallayout class='monospaced'>
183 $ wget http://pokylinux.org/releases/poky-green-3.3.tar.bz2
184 $ tar xjvf poky-green-3.3.tar.bz2
185 $ cd green-3.3-build
186 $ source green-3.3/poky-init-build-env green-3.3-build
187 $ bitbake qemu-native
188 $ bitbake poky-image-sato
189 $ poky-qemu qemux86
190 </literallayout>
191 </para>
192
193 <para>
194 Here is some explanation for these commands:
195 </para>
196
197 <itemizedlist>
198 <listitem>
199 <para>
200 The first two commands extract the Yocto Project files from the release area and place them into your build area (green-3.3-build in this example).
201 </para>
202 </listitem>
203 <listitem>
204 <para>
205 After changing to the build directory the source command sets up the Yocto Project build environment.
206 The build directory contains all the object files used during the build.
207 The default build directory is poky-dir/build.
208 </para>
209 </listitem>
210 <listitem>
211 <para>
212 The two bitbake commands build the OS image and the emulator for the target.
213 Here poky-image-sato is the name of the target. The qemu-native target is the customized QEMU Emulator.</para>
214 </listitem>
215 <listitem>
216 <para>
217 Finally, the poky-qemu command launches the customized QEMU.
218 </para>
219 </listitem>
220 </itemizedlist>
221 </section>
222
223 <section id='using-pre-built'>
224 <title>Using a Pre-Built Linux Kernel for QEMU</title>
225 <para>
226 If hardware, libraries and services are stable you can use a pre-built image of the kernel and just run it on the target using the emulator QEMU.
227 This situation is perfect for developing application software.
228 </para>
229
230 <para></para>
231 <para></para>
232 <para></para>
233
234 <mediaobject>
235 <imageobject>
236 <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/>
237 </imageobject>
238 <caption>
239 <para>Using a Pre-Built Image</para>
240 </caption>
241 </mediaobject>
242
243 <para>
244 For this scenario you need to do three things:
245 </para>
246
247 <itemizedlist>
248 <listitem>
249 <para>
250 Install the Yocto Project Scripts
251 </para>
252 </listitem>
253 <listitem>
254 <para>
255 Download the pre-built kernel that will run on QEMU.
256 You need to be sure to get the QEMU image that matches your target machine’s architecture (e.g. x86, ARM, etc.).
257 </para>
258 </listitem>
259 <listitem>
260 <para>
261 Download and decompress the file image system.
262 </para>
263 </listitem>
264 </itemizedlist>
265
266 <para>
267 Use this command to install the patched Yocto Project QEMU scripts:
268 </para>
269
270 <para>
271 <literallayout class='monospaced'>
272 $ apt-get install qemu poky-scripts
273 </literallayout>
274 </para>
275
276 <para>
277 You can download the pre-built Linux kernel and the file image system from <ulink url='http://pokylinux.org/releases/blinky-3.0'></ulink>.
278 The kernel and file image system have the following forms, respectively:
279 </para>
280
281 <literallayout class='monospaced'>
282 *zImage*qemu*.bin
283 poky-image-*-qemu*.ext2.bz2
284 </literallayout>
285
286 <para>
287 You must decompress the file image system using the following command:
288 </para>
289
290 <literallayout class='monospaced'>
291 $ bzip2 -d
292 </literallayout>
293
294 <para>
295 You can now start the emulator using this command:
296 </para>
297
298 <literallayout class='monospaced'>
299 $ poky-qemu &lt;<emphasis>kernel</emphasis>&gt; &lt;<emphasis>image</emphasis>&gt;
300 </literallayout>
301 </section>
302</section>
303
304</article>
305<!--
306vim: expandtab tw=80 ts=4
307-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-01-11 23:42:24 +0000