summaryrefslogtreecommitdiffstats
path: root/documentation/yocto-project-qs
diff options
context:
space:
mode:
authorScott Rifenbark <scott@scott-desktop.(none)>2011-01-19 10:20:11 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-01-20 21:37:01 +0000
commit75ee154c64a5ee177d3d25111cc35ea690fc8612 (patch)
tree41d44d39bc4eb08702e27b2e6f6e824a5efd9b05 /documentation/yocto-project-qs
parent6d5adf104895db47a0d426f68cb81454bd855790 (diff)
downloadpoky-75ee154c64a5ee177d3d25111cc35ea690fc8612.tar.gz
documentation/yocto-project-qs/yocto-project-qs.xml: General edits to YP QS.
Revised the manual for better grammar and more technically accurate wordings. Worked closely with Scott Garman on the revision. Signed-off-by: Scott Rifenbark <scott@scott-desktop.(none)>
Diffstat (limited to 'documentation/yocto-project-qs')
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml187
1 files changed, 133 insertions, 54 deletions
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index c62ec58df1..2748a68005 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -160,14 +160,14 @@
160 autoconf automake 160 autoconf automake
161 </literallayout> 161 </literallayout>
162 162
163 <para> 163 <note><para>
164 <emphasis>NOTE:</emphasis> Packages vary in number and name for other Linux distributions. 164 Packages vary in number and name for other Linux distributions.
165 The commands here should work. We are interested, though, to learn what works for you. 165 The commands here should work. We are interested, though, to learn what works for you.
166 You can find more information for package requirements on common Linux distributions 166 You can find more information for package requirements on common Linux distributions
167 at <ulink url="http://wiki.openembedded.net/index.php/OEandYourDistro"></ulink>. 167 at <ulink url="http://wiki.openembedded.net/index.php/OEandYourDistro"></ulink>.
168 However, you should be careful when using this information as the information applies 168 However, you should be careful when using this information as the information applies
169 to old Linux distributions that are known to not work with a current Poky install. 169 to old Linux distributions that are known to not work with a current Poky install.
170 </para> 170 </para></note>
171 </section> 171 </section>
172 172
173 <section id='releases'> 173 <section id='releases'>
@@ -216,15 +216,16 @@
216 </mediaobject> 216 </mediaobject>
217 217
218 <para> 218 <para>
219 Use the following commands from a shell on your Debian-based host to build your image. 219 Use the following commands to build your image.
220 The build creates an entire Linux system including the Toolchain from the source. 220 The build process creates an entire Linux distribution, including the toolchain, from source.
221 </para> 221 </para>
222 222
223 <para><emphasis>NOTE:</emphasis> The build process using Sato currently consumes 223 <note><para>
224 50GB of disk space. 224 The build process using Sato currently consumes
225 To allow for variations in the build process and for future package expansion we 225 about 50GB of disk space.
226 recommend 100GB of free disk space. 226 To allow for variations in the build process and for future package expansion, we
227 </para> 227 recommend having at least 100GB of free disk space.
228 </para></note>
228 229
229 <para> 230 <para>
230 <literallayout class='monospaced'> 231 <literallayout class='monospaced'>
@@ -235,52 +236,56 @@
235 </para> 236 </para>
236 <itemizedlist> 237 <itemizedlist>
237 <listitem><para>The first two commands extract the Yocto Project files from the 238 <listitem><para>The first two commands extract the Yocto Project files from the
238 release area and place them into a subdirectory of your current directory 239 release tarball and place them into a subdirectory of your current directory.</para></listitem>
239 (<command>poky-4.0-build</command> in this example).</para></listitem> 240 <listitem><para>The <command>source</command> command creates the
240 <listitem><para>The <command>$ source</command> command creates the directory and places 241 <filename>poky-4.0-build</filename> directory and executes the <command>cd</command>
241 you there. 242 command to make <filename>poky-4.0-build</filename> the working directory.
242 The build directory contains all the object files used during the build. 243 The resulting build directory contains all the files created during the build.
243 The default build directory is <command>poky-4.0-build</command>. 244 By default the target architecture is qemux86.
244 Note that you can change the target architecture by editing the 245 To change this default, edit the value of the MACHINE variable in the
245 <command>&lt;build_directory&gt;/conf/local.conf</command> file. 246 <filename>conf/local.conf</filename> file.</para></listitem>
246 By default the target architecture is qemux86.</para></listitem>
247 </itemizedlist> 247 </itemizedlist>
248 <para> 248 <para>
249 Now might be a good time to edit the <command>conf/local.conf</command> 249 Take some time to examine your <filename>conf/local.conf</filename> file.
250 file. 250 The defaults should work fine.
251 The defaults should all be fine. However, you might want to look at the variables 251 However, if you have a multi-core CPU you might want to set the variables
252 BB_NUMBER_THREADS and PARALLEL_MAKE. 252 BB_NUMBER_THREADS and PARALLEL_MAKE to the number of processor cores on your build machine.
253 By default, these variables are commented out. 253 By default, these variables are commented out.
254 </para> 254 </para>
255 <para> 255 <para>
256 Continue with the following command to build the OS image for the target, which is 256 Continue with the following command to build an OS image for the target, which is
257 poky-image-sato in this example. 257 <filename>poky-image-sato</filename> in this example.
258 <literallayout class='monospaced'> 258 <literallayout class='monospaced'>
259 $ bitbake poky-image-sato 259 $ bitbake poky-image-sato
260 </literallayout> 260 </literallayout>
261 <emphasis>NOTE:</emphasis> If you are running Fedora 14 or another distribution 261 <note><para>
262 with GNU make 3.82 you might have to run the following two 262 If you are running Fedora 14 or another distribution
263 <command>$bitbake</command> commands instead: 263 that ships with GNU make v3.82 you need to run the following two
264 <literallayout class='monospaced'> 264 <command>bitbake</command> commands instead:
265 <literallayout class='monospaced'>
265 $ bitbake make-native 266 $ bitbake make-native
266 $ bitbake poky-image-sato 267 $ bitbake poky-image-sato
267 </literallayout> 268 </literallayout>
269 </para></note>
268 The final command runs the image: 270 The final command runs the image:
269 <literallayout class='monospaced'> 271 <literallayout class='monospaced'>
270 $ poky-qemu qemux86 272 $ poky-qemu qemux86
271 </literallayout> 273 </literallayout>
272 The build process could take several hours the first time you run it. 274 <note><para>
273 Depending on the number of processors and cores, the amount or RAM, the speed of your 275 Depending on the number of processors and cores, the amount or RAM, the speed of your
274 internet connection and other factors. 276 Internet connection and other factors, the build process could take several hours the first
275 After the initial build, subsequent builds run much faster. 277 time you run it.
278 Subsequent builds run much faster since parts of the build are cached.
279 </para></note>
276 </para> 280 </para>
277 </section> 281 </section>
278 282
279 <section id='using-pre-built'> 283 <section id='using-pre-built'>
280 <title>Using Pre-Built Binaries and QEMU</title> 284 <title>Using Pre-Built Binaries and QEMU</title>
281 <para> 285 <para>
282 If hardware, libraries and services are stable you can use a pre-built binary of the image, kernel and toolchain and just run it on the target using the emulator QEMU. 286 If hardware, libraries and services are stable you can get started by using a pre-built binary
283 This situation is perfect for developing application software. 287 of the image, kernel and toolchain and run it using the emulator QEMU.
288 This scenario is useful for developing application software.
284 </para> 289 </para>
285 290
286 <para></para> 291 <para></para>
@@ -303,25 +308,60 @@
303 <itemizedlist> 308 <itemizedlist>
304 <listitem> 309 <listitem>
305 <para> 310 <para>
306 Install the standalone Yocto toolchain tarball. 311 Install the stand-alone Yocto toolchain tarball.
307 </para> 312 </para>
308 </listitem> 313 </listitem>
309 <listitem> 314 <listitem>
310 <para> 315 <para>
311 Download the pre-built kernel that will run on QEMU. 316 Download the pre-built kernel that will boot with QEMU.
312 You need to be sure to get the QEMU image that matches your target machine’s architecture (e.g. x86, ARM, etc.). 317 You need to be sure to get the QEMU image that matches your target machine’s
318 architecture (e.g. x86, ARM, etc.).
313 </para> 319 </para>
314 </listitem> 320 </listitem>
315 <listitem> 321 <listitem>
316 <para> 322 <para>
317 Download and decompress the file image system. 323 Download the filesystem image for your target machine's architecture.
318 </para> 324 </para>
319 </listitem> 325 </listitem>
320 </itemizedlist> 326 </itemizedlist>
321 327
322 <para> 328 <para>
323 You can download the pre-built toolchain, which includes the poky-qemu script and support files, from <ulink url='http://yoctoproject.org/downloads/yocto-0.9/toolchain/'></ulink>. These are available for i586 (32-bit) and x86_64 (64 bit) host machines, targeting each of the five supported target architectures. The tarballs are self contained and install into <filename>/opt/poky</filename>. 329 You can download the pre-built toolchain, which includes the poky-qemu script and
324 Use these commands to install the toolchain tarball (taking the 64 bit host, 32 bit i586 target as an example): 330 support files, from <ulink url='http://yoctoproject.org/downloads/yocto-0.9/toolchain/'></ulink>.
331 Toolchains are available for 32-bit and 64-bit development systems from the
332 <filename>i586</filename> and <filename>x86_64</filename> folders, respectively.
333 Each type of development system supports five target architectures.
334 The tarball files are named such that a string representing the host system appears
335 first in the filename and then is immediately followed by a string representing
336 the target architecture.
337 </para>
338
339 <literallayout class='monospaced'>
340 yocto-eglibc&lt;<emphasis>host_system</emphasis>&gt;-&lt;<emphasis>arch</emphasis>&gt;-toolchain-sdk-&lt;<emphasis>release</emphasis>&gt;.tar.bz2
341
342 Where:
343 &lt;<emphasis>host_system</emphasis>&gt; is a string representing your development system:
344 i586 or x86_64.
345
346 &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
347 i585, x86_64, powerpc, mips, or arm.
348
349 &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project.
350 </literallayout>
351
352 <para>
353 For example, the following toolchain tarball is for a 64-bit development
354 host system and a 32-bit target architecture:
355 </para>
356
357 <literallayout class='monospaced'>
358 yocto-eglibc-x86_64-i586-toolchain-sdk-0.9.tar.bz2
359 </literallayout>
360
361 <para>
362 The toolchain tarballs are self-contained and should be installed into <filename>/opt/poky</filename>.
363 The following commands show how you install the toolchain tarball given a 64-bit development host system
364 and a 32-bit target architecture.
325 </para> 365 </para>
326 366
327 <para> 367 <para>
@@ -332,44 +372,83 @@
332 </para> 372 </para>
333 373
334 <para> 374 <para>
335 You can download the pre-built Linux kernel and the file image system suitable for 375 You can download the pre-built Linux kernel and the filesystem image suitable for
336 running in the emulator QEMU from 376 running in the emulator QEMU from
337 <ulink url='http://yoctoproject.org/downloads/yocto-0.9/qemu'></ulink>. 377 <ulink url='http://yoctoproject.org/downloads/yocto-0.9/qemu'></ulink>.
338 Be sure to use the kernel and file image system that matches the architecture you want 378 Be sure to use the kernel and filesystem image that matches the architecture you want
339 to simulate. 379 to simulate.
340 </para> 380 </para>
341 381
342 <para> 382 <para>
343 The kernel and file image system have the following forms, respectively: 383 Most kernel files have the following form:
384 </para>
385
386 <literallayout class='monospaced'>
387 *zImage*qemu&lt;<emphasis>arch</emphasis>&gt;*.bin
388
389 Where:
390 &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
391 x86, x86-64, ppc, mips, or arm.
392 </literallayout>
393
394 <para>
395 The filesystem image has two forms.
396 One form is an <filename>ext3</filename> filesystem image.
397 The other form is a tarball of the filesystem and is booted using user-space NFS.
398 Here are the respective forms:
344 </para> 399 </para>
345 400
346 <literallayout class='monospaced'> 401 <literallayout class='monospaced'>
347 *zImage*qemu*.bin 402 yocto-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;.rootfs.ext3
348 yocto-image-*-qemu*.ext3.bz2 403 yocto-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;.rootfs.tar.bz2
404
405 Where:
406 &lt;<emphasis>profile</emphasis>&gt; is the filesystem image's profile:
407 sdk, sato, minimal, or lsb.
408
409 &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
410 x86, x86-64, ppc, mips, or arm.
349 </literallayout> 411 </literallayout>
350 412
351 <para> 413 <para>
352 You must decompress the file image system using the following command: 414 The following command form sets up the emulation environment.
353 </para> 415 </para>
354 416
355 <literallayout class='monospaced'> 417 <literallayout class='monospaced'>
356 $ bzip2 -d 418 $ source /opt/poky/environment-setup-&lt;<emphasis>arch</emphasis>&gt;-poky-linux
419
420 Where:
421 &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
422 i586, x86-64, ppc, mips, or arm.
357 </literallayout> 423 </literallayout>
358 424
359 <para> 425 <para>
360 You can now start the emulator using these commands (assuming an 32 bit i586 target): 426 Finally, this command form invokes the QEMU emulator
361 </para> 427 </para>
362 428
363 <literallayout class='monospaced'> 429 <literallayout class='monospaced'>
364 $ source /opt/poky/environment-setup-i586-poky-linux
365 $ poky-qemu &lt;<emphasis>qemuarch</emphasis>&gt; &lt;<emphasis>kernel</emphasis>&gt; &lt;<emphasis>image</emphasis>&gt; &lt;<emphasis>fstype</emphasis>&gt; 430 $ poky-qemu &lt;<emphasis>qemuarch</emphasis>&gt; &lt;<emphasis>kernel</emphasis>&gt; &lt;<emphasis>image</emphasis>&gt; &lt;<emphasis>fstype</emphasis>&gt;
431
432 Where:
433 &lt;<emphasis>qemuarch</emphasis>&gt; is a string representing the target architecture: qemux86, qemux86-64,
434 qemuppc, qemumips, or qemuarm.
435
436 &lt;<emphasis>kernel</emphasis>&gt; is the architecture-specific kernel.
437
438 &lt;<emphasis>image</emphasis>&gt; is the .ext3 filesystem image.
439
440 &lt;<emphasis>fstype</emphasis>&gt; is the filesystem type.
366 </literallayout> 441 </literallayout>
442
367 <para> 443 <para>
368 For example: 444 Continuing with the example, the following two commands setup the emulation
445 environment and launch QEMu.
446 The kernel and filesystem are for a 32-bit target architecture.
369 </para> 447 </para>
448
370 <literallayout class='monospaced'> 449 <literallayout class='monospaced'>
371 $ poky-qemu qemuppc zImage-2.6.34-qemuppc-0.9 \ 450 $ source /opt/poky/environment-setup-i586-poky-linux
372 yocto-image-minimal-qemuppc-0.9.rootfs.ext3 ext3 451 $ poky-qemu qemui586 zImage-2.6.34-qemux86-0.9 yocto-image-sdk-qemux86-0.9.rootfs.ext3 ext3
373 </literallayout> 452 </literallayout>
374 453
375 </section> 454 </section>