summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-09-23 08:07:41 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-09-25 17:59:59 +0100
commit24eaac709825044b4dc9bb8d83f6ac73cfab3ae5 (patch)
tree7f0019b85c013472eb9e3069e0ef358360c4e870
parent44963bdddd3317a7987ff35311c1ef73e0dd5860 (diff)
downloadpoky-24eaac709825044b4dc9bb8d83f6ac73cfab3ae5.tar.gz
documentation/dev-manual/dev-manual-model.xml: edit pass
These changes are the second edit pass for the new section. There are some minor changes. (From yocto-docs rev: 6c81617a2782d2f02d4900a68dd4e8c6eeb70fa1) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-model.xml304
1 files changed, 179 insertions, 125 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index a63d590c78..fa8c79f29d 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -21,7 +21,8 @@
21 see the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>" 21 see the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>"
22 appendix and the 22 appendix and the
23 "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix. 23 "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix.
24 For a user-space application development example that uses the Eclipse IDE, 24 For a user-space application development example that uses the
25 <trademark class='trade'>Eclipse</trademark> IDE,
25 see the 26 see the
26 <ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html'> 27 <ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html'>
27 The Yocto Project Application Development Toolkit (ADT) User's Guide</ulink>. 28 The Yocto Project Application Development Toolkit (ADT) User's Guide</ulink>.
@@ -364,7 +365,8 @@
364 </para> 365 </para>
365 366
366 <para> 367 <para>
367 <imagedata fileref="figures/kernel-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" /> 368 <imagedata fileref="figures/kernel-dev-flow.png"
369 width="6in" depth="7.5in" align="center" scalefit="1" />
368 </para> 370 </para>
369 371
370 <para> 372 <para>
@@ -480,137 +482,189 @@
480 <para> 482 <para>
481 Application development involves creation of an application that you want to be able 483 Application development involves creation of an application that you want to be able
482 to run on your target hardware, which is running a Linux Yocto image. 484 to run on your target hardware, which is running a Linux Yocto image.
483 Much of this process involves standard application development practices that are 485 The Yocto Project provides an Application Development Toolkit (ADT) that
484 not covered in detail in this manual. 486 facilitates quick development and integration of your application into its run-time environment.
485 However, the Yocto Project provides an application development environment that 487 Using the ADT you can employ cross-development toolchains designed for your target hardware
486 facilitates quick integration of your application into its run-time environment.
487 For example, you can employ cross-development toolchains designed for your target hardware
488 to compile and link your application. 488 to compile and link your application.
489 You can deploy your application to the actual hardware or to the QEMU emulator for testing. 489 You can then deploy your application to the actual hardware or to the QEMU emulator for testing.
490 You can even develop, deploy, and test your application all from within the popular 490 If you are familiar with the popular Eclipse IDE, you can use an Eclipse Yocto Plug-in to
491 Eclipse IDE. 491 allow you to develop, deploy, and test your application all from within Eclipse.
492 </para> 492 </para>
493 493
494 <para> 494 <para>
495 To help you understand how application development works in the Yocto Project, this section 495 While we strongly suggest using the Yocto Project ADT to develop your application, you might
496 provides an overview of the general development process. 496 not want to.
497 If you want to see a detailed example of the process as it is used from within the Eclipse 497 If this is the case, you can still use pieces of the Yocto Project for your development process.
498 IDE, see 498 However, because the process can vary greatly, this manual does not provide detail on the process.
499 <ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html'>
500 The Application Development Toolkit (ADT) User's Manual</ulink>.
501 </para> 499 </para>
502 500
503 <para> 501 <section id='workflow-using-the-adt-and-eclipse'>
504 This illustration and the following list summarizes the application development general workflow. 502 <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title>
505 </para>
506 503
507 <para> 504 <para>
508 <imagedata fileref="figures/app-dev-flow.png" width="7in" depth="7in" align="center" scalefit="1" /> 505 To help you understand how application development works in the Yocto Project ADT
509 </para> 506 environment, this section
507 provides an overview of the general development process.
508 If you want to see a detailed example of the process as it is used from within the Eclipse
509 IDE, see
510 <ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html'>
511 The Application Development Toolkit (ADT) User's Manual</ulink>.
512 </para>
510 513
511 <para> 514 <para>
512 <orderedlist> 515 This illustration and the following list summarizes the application development general workflow.
513 <listitem><para><emphasis>Set up your host development system to support 516 </para>
514 development using the Yocto Project</emphasis>: See 517
515 "<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>The Linux Distributions</ulink>" and 518 <para>
516 "<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>The Packages</ulink>" sections both 519 <imagedata fileref="figures/app-dev-flow.png"
517 in the Yocto Project Quick Start for requirements.</para></listitem> 520 width="7in" depth="8in" align="center" scale="100" />
518 <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your 521 </para>
519 system</emphasis>: Having the Yocto Project files on your system gives you access to 522
520 the build process and tools you need. 523 <para>
521 For information on how to get these files, see the bulleted item 524 <orderedlist>
522 "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual. 525 <listitem><para><emphasis>Prepare the Host System for the Yocto Project</emphasis>:
523 </para></listitem> 526 See
524 <listitem><para><emphasis>Set up the <filename>poky-extras</filename> Git 527 "<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>The Linux Distributions</ulink>" and
525 repository</emphasis>: This repository is the area for your configuration 528 "<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>The Packages</ulink>" sections both
526 fragments, new kernel recipes, and the kernel <filename>.bbappend</filename> 529 in the Yocto Project Quick Start for requirements.</para></listitem>
527 file used during the build. 530
528 It is good practice to set this repository up inside the local Yocto 531<!--
529 Project files Git repository. 532WRITER NOTE: The areas to get the kernel and root filesystem are located in the Index of
530 For information on how to get these files, see the bulleted item 533 downloads. There are many forms of each. The files that have "rootfs" are just the
531 "<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>" 534 target root filesystems. The file that is very small and starts with bzImage is just
532 earlier in this manual.</para></listitem> 535 the kernel image isolated so that it can be written to a special on-board area of
533 <listitem><para><emphasis>Establish a local copy of the Linux Yocto kernel files on your 536 flash memory. Some systems require this. In the machines directory there are
534 system</emphasis>: In order to make modifications to the kernel you need two things: 537 files that combine the kernel image and the root filesystem. These files are the ISO
535 a bare clone of the Linux Yocto kernel you are modifying and 538 and HDDIMG files. ISO images are designed to be deployed on a DVD or CD. The ISO
536 a copy of that bare clone. 539 images are designed to be deployed on a USB stick. There might be some relics in
537 The bare clone is required by the build process and is the area to which you 540 the machine directory. For example, there is the "emenlow-bernard-5.0.0.tar.bz2"
538 push your kernel source changes (pulling does not work with bare clones). 541 file. Nobody seems to know what this is. If a developer needs the image and the
539 The copy of the bare clone is a local Git repository that contains all the kernel's 542 root filesystem I think that they want the small kernel image and a matching root
540 source files. 543 filesystem. Although, Paul Eggleton says that the HDDIMG types could be used to
541 You make your changes to the files in this copy of the bare clone. 544 develop on. I am not sure that we can use one of those in the ADT though as they
542 For information on how to set these two items up, see the bulleted item 545 want you to point to the kernel image and the target root filesystem. Maybe you
543 "<link linkend='local-kernel-files'>Linux Yocto Kernel</link>" 546 could just point to the same spot. I am not sure.
544 earlier in this manual.</para></listitem> 547-->
545 <listitem><para><emphasis>Make changes to the kernel source code if 548
546 applicable</emphasis>: Modifying the kernel does not always mean directly 549 <listitem><para><emphasis>Secure the Linux Yocto Kernel Target Image</emphasis>:
547 changing source files. 550 You must have a target kernel image that has been built using the Yocto Project.</para>
548 However, if you have to do this, you make the changes in the local 551 <para>Depending on whether the Yocto Project has a pre-built image that matches your target
549 Git repository you set up to hold the source files (i.e. the copy of the 552 architecture and where you are going to run the image while you develop your application
550 bare clone). 553 (QEMU or real hardware), the area you get the image from differs.
551 Once the changes are made, you need to use Git commands to commit the changes 554 <itemizedlist>
552 and then push them to the bare clone.</para></listitem> 555 <listitem><para>Download the image from
553 <listitem><para><emphasis>Make kernel configuration changes 556 <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/machines/'>
554 to your local kernel layer if applicable</emphasis>: 557 <filename>machines</filename></ulink> if your target architecture is supported
555 If your situation calls for changing the kernel's configuration, you can 558 and you are going to develop and test your application on actual hardware.
556 use <filename>menuconfig</filename> 559 </para></listitem>
557 to enable and disable kernel configurations. 560 <listitem><para>Download the image from the
558 Using <filename>menuconfig</filename> allows you to interactively develop and test the 561 <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/machines/qemu/'>
559 configuration changes you are making to the kernel. 562 <filename>machines/qemu</filename></ulink> if your target architecture is supported
560 When saved, changes using <filename>menuconfig</filename> update the kernel's 563 and you are going to develop and test your application using the QEMU
561 <filename>.config</filename>. 564 emulator.</para></listitem>
562 As an alternative method to changing the kernel's configuration, you can simply 565 <listitem><para>Build your image if you cannot find a pre-built image that matches
563 edit the <filename>.config</filename> found in the Yocto Project build 566 your target architecture.
564 directory at <filename>tmp/sysroots/&lt;machine-name&gt;/kernel</filename> 567 If your target architecture is similar to a supported architecture, you can
565 directly.</para></listitem> 568 modify the kernel image before you build it.
566 <listitem><para><emphasis>Add new kernel recipes if applicable</emphasis>: The standard 569 See the
567 layer structure organizes recipe files inside the 570 "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
568 <filename>meta-kernel-dev</filename> layer that is within the 571 section earlier in this manual for information on how to create a modified
569 <filename>poky-extras</filename> Git repository. 572 Linux Yocto kernel.</para></listitem>
570 If you need to add new kernel recipes, you add them within this layer. 573 </itemizedlist></para>
571 Also within this area, you will find the <filename>.bbappend</filename> 574 <para>For information on pre-built kernel image naming schemes for images
572 file that appends information to the kernel's recipe file used during the 575 that can run on the QEMU emulator, see the
573 build. 576 "<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
574 </para></listitem> 577 section in
575 <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the 578 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html'>
576 changes to your kernel (configurations, source code changes, recipe additions, 579 The Yocto Project Quick Start</ulink>.</para></listitem>
577 or recipe changes), there remains a few things 580 <listitem><para><emphasis>Install the ADT</emphasis>:
578 you need to do in order for the Yocto Project build system to create your image. 581 The ADT provides a target-specific cross-development toolchain, the root filesystem,
579 If you have not done so, you need to get the build environment ready by sourcing 582 the QEMU emulator, and other tools that can help you develop your application.
580 the environment setup script described earlier. 583 While it is possible to get these pieces separately, the Yocto Project provides an
581 You also need to be sure two key configuration files 584 easy method.
582 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) 585 You can get these pieces by running an ADT installer script, which is configurable.
583 are configured appropriately.</para> 586 For information on how to install the ADT, see the
584 <para>The entire process for building an image is overviewed in the 587 "<ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html#using-the-adt-installer'>Using the ADT Installer</ulink>" section in
585 "<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>" section of the Yocto Project Quick Start. 588 <ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html'>The Yocto Project
586 You might want to reference this information. 589 Application Development (ADT) User's Manual</ulink>.</para></listitem>
587 Also, you should look at the detailed examples found in the appendices at 590 <listitem><para><emphasis>If Applicable, Secure the Target Root Filesystem</emphasis>:
588 at the end of this manual.</para></listitem> 591 If you choose not to install the ADT using the ADT Installer,
589 <listitem><para><emphasis>Build the image</emphasis>: The Yocto Project 592 you need to find and download the
590 build system Poky uses the BitBake 593 appropriate root filesystems.
591 tool to build images based on the type of image you want to create. 594 You can find these tarballs in the same areas used for the kernel images.
592 You can find more information on BitBake 595 Depending on the type of image you are running, the root filesystem you need differs.
593 <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> 596 For example, if you are developing an application that runs on an image that
594 <para>The build process supports several types of images to satisfy different needs. 597 supports Sato, you need to get root filesystem that supports Sato.
595 See the appendix 598 </para></listitem>
596 "<ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>" in the 599 <listitem><para><emphasis>Create and Build your Application</emphasis>:
597 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'> 600 At this point, you need to have source files for your application.
598 Yocto Project Reference Manual</ulink> for information on supported 601 Once you have the files, you can use the Eclipse IDE to import them and build the
599 images.</para></listitem> 602 project.
600 <listitem><para><emphasis>Make your configuration changes available 603 If you are not using Eclipse, you need to use the cross-development tools you have
601 in the kernel layer</emphasis>: Up to this point, all the configuration changes to the 604 installed to create the image.</para></listitem>
602 kernel have been done and tested iteratively. 605 <listitem><para><emphasis>Deploy the Image with the Application</emphasis>:
603 Once they are tested and ready to go, you can move them into the kernel layer, 606 If you are using the Eclipse IDE, you can deploy your image to the hardware or to
604 which allows you to distribute the layer.</para></listitem> 607 QEMU through the project's preferences.
605 <listitem><para><emphasis>If applicable, share your in-tree changes</emphasis>: 608 If you are not using the Eclipse IDE, then you need to deploy the application using
606 If the changes you made 609 other methods to the hardware.
607 are suited for all Linux Yocto users, you might want to push the changes to a 610 Or, if you are using QEMU, you need to use that tool and load your image in for testing.
608 contribution area for the Linux Yocto Git repository. 611 </para></listitem>
609 Once the changes are pushed, you can request that they 612 <listitem><para><emphasis>Test and Debug the Application</emphasis>:
610 be pulled into the master branch of the kernel tree. 613 Once your application is deployed, you need to test it.
611 Doing so makes them available to everyone using the kernel.</para></listitem> 614 Within the Eclipse IDE, you can use the debubbing environment along with the
612 </orderedlist> 615 set of user-space tools installed along with the ADT to debug your application.
613 </para> 616 Of course, the same user-space tools are available separately to use if you choose
617 not to use the Eclipse IDE.</para></listitem>
618 </orderedlist>
619 </para>
620 </section>
621
622 <section id='workflow-without-adt'>
623 <title>Workflow Without ADT</title>
624
625 <para>
626 If you want to develop an application outside of the Yocto Project ADT environment, you
627 can still employ the cross-development toolchain, the QEMU emulator, and a number of supported
628 target image files.
629 You just need to follow these general steps:
630 <orderedlist>
631 <listitem><para><emphasis>Install the cross-development toolchain for your target hardware:</emphasis>
632 For information on how to install the toolchain, see the
633 "<ulink url='http://www.yoctoproject/docs/1.1/adt-manual/adt-manual.html#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" section in
634 <ulink url='http://www.yoctoproject/docs/1.1/adt-manual/adt-manual.html'>The Yocto Project
635 Application Development (ADT) User's Manual</ulink>.</para></listitem>
636 <listitem><para><emphasis>Download the Target Image:</emphasis> The Yocto Project supports
637 several target architectures and has many pre-built kernel images and root filesystem
638 images.</para>
639 <para>If you are going to develop your application on hardware, go to the
640 <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/machines/'>
641 <filename>machines</filename></ulink> download area and choose a target machine area
642 from which to download the kernel image and root filesystem.
643 This download area could have several files in it that support development using
644 actual hardware.
645 For example, the area might contain <filename>.hddimg</filename> files that combine the
646 kernel image with the filesystem, boot loaders, etc.
647 Be sure to get the files you need for your particular development process.</para>
648 <para>If you are going to develop your application and then run and test it using the QEMU
649 emulator, go to the
650 <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/machines/qemu/'>
651 <filename>machines/qemu</filename></ulink> download area.
652 From this area, go down into the directory for your target architecture
653 (e.g. <filename>qemux86_64</filename> for an
654 <trademark class='registered'>Intel</trademark>-based 64-bit architecture).
655 Download kernel, root filesystem, and any other files you need for your process.
656 <note>In order to use the root filesystem in QEMU, you need to extract it.
657 See the
658 "<ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" section for information on how to extract the
659 root filesystem.</note></para></listitem>
660 <listitem><para><emphasis>Develop and Test your Application:</emphasis> At this point,
661 you have the tools to develop your application.
662 If you need to separately install and use the QEMU emulator, you can go to
663 <ulink url='http://www.qemu.org'>QEMU Home Page</ulink> to download and learn about the
664 emulator.</para></listitem>
665 </orderedlist>
666 </para>
667 </section>
614</section> 668</section>
615 669
616</chapter> 670</chapter>