diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-using.xml')
| -rw-r--r-- | documentation/sdk-manual/sdk-using.xml | 1053 |
1 files changed, 1044 insertions, 9 deletions
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml index f2acaa7fc4..1403632db1 100644 --- a/documentation/sdk-manual/sdk-using.xml +++ b/documentation/sdk-manual/sdk-using.xml | |||
| @@ -273,7 +273,7 @@ | |||
| 273 | <listitem><para><emphasis>Source the cross-toolchain | 273 | <listitem><para><emphasis>Source the cross-toolchain |
| 274 | environment setup file:</emphasis> | 274 | environment setup file:</emphasis> |
| 275 | Installation of the cross-toolchain creates a cross-toolchain | 275 | Installation of the cross-toolchain creates a cross-toolchain |
| 276 | environment setup script in the directory that the ADT | 276 | environment setup script in the directory that the SDK |
| 277 | was installed. | 277 | was installed. |
| 278 | Before you can use the tools to develop your project, you must | 278 | Before you can use the tools to develop your project, you must |
| 279 | source this setup script. | 279 | source this setup script. |
| @@ -281,7 +281,7 @@ | |||
| 281 | the machine architecture, which is followed by the string | 281 | the machine architecture, which is followed by the string |
| 282 | "poky-linux". | 282 | "poky-linux". |
| 283 | Here is an example that sources a script from the | 283 | Here is an example that sources a script from the |
| 284 | default ADT installation directory that uses the | 284 | default SDK installation directory that uses the |
| 285 | 32-bit Intel x86 Architecture and the | 285 | 32-bit Intel x86 Architecture and the |
| 286 | &DISTRO_NAME; Yocto Project release: | 286 | &DISTRO_NAME; Yocto Project release: |
| 287 | <literallayout class='monospaced'> | 287 | <literallayout class='monospaced'> |
| @@ -439,15 +439,1050 @@ | |||
| 439 | </para> | 439 | </para> |
| 440 | </section> | 440 | </section> |
| 441 | 441 | ||
| 442 | <section id='sdk-using-the-sdk-to-task-1'> | 442 | <section id='sdk-developing-applications-using-eclipse'> |
| 443 | <title>Using the SDK to <replaceable>item 1</replaceable></title> | 443 | <title>Devloping Applications Using <trademark class='trade'>Eclipse</trademark></title> |
| 444 | 444 | ||
| 445 | <para role='writernotes'> | 445 | <para> |
| 446 | Describe the specific task you are going to accomplish with the SDK. | 446 | If you are familiar with the popular Eclipse IDE, you can use an |
| 447 | Provide a diagram showing the rough flow of the task. | 447 | Eclipse Yocto Plug-in to allow you to develop, deploy, and test your |
| 448 | Provide specific steps using a real example that works through the | 448 | application all from within Eclipse. |
| 449 | task. | 449 | This section describes general workflow using the SDK and Eclipse |
| 450 | and how to configure and set up Eclipse. | ||
| 450 | </para> | 451 | </para> |
| 452 | |||
| 453 | <section id='workflow-using-eclipse'> | ||
| 454 | |||
| 455 | <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title> | ||
| 456 | |||
| 457 | <para> | ||
| 458 | The following figure and supporting list summarize the application | ||
| 459 | development general workflow that employs both the SDK Eclipse. | ||
| 460 | </para> | ||
| 461 | |||
| 462 | <para> | ||
| 463 | <imagedata fileref="figures/sdk-eclipse-dev-flow.png" | ||
| 464 | width="7in" depth="7in" align="center" scale="100" /> | ||
| 465 | </para> | ||
| 466 | |||
| 467 | <para> | ||
| 468 | <orderedlist> | ||
| 469 | <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>: | ||
| 470 | See | ||
| 471 | "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" | ||
| 472 | and | ||
| 473 | "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both | ||
| 474 | in the Yocto Project Reference Manual for requirements. | ||
| 475 | In particular, be sure your host system has the | ||
| 476 | <filename>xterm</filename> package installed. | ||
| 477 | </para></listitem> | ||
| 478 | <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>: | ||
| 479 | You must have a target kernel image that has been built using the OpenEmbedded | ||
| 480 | build system.</para> | ||
| 481 | <para>Depending on whether the Yocto Project has a pre-built image that matches your target | ||
| 482 | architecture and where you are going to run the image while you develop your application | ||
| 483 | (QEMU or real hardware), the area from which you get the image differs. | ||
| 484 | <itemizedlist> | ||
| 485 | <listitem><para>Download the image from | ||
| 486 | <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> | ||
| 487 | if your target architecture is supported and you are going to develop | ||
| 488 | and test your application on actual hardware.</para></listitem> | ||
| 489 | <listitem><para>Download the image from | ||
| 490 | <ulink url='&YOCTO_QEMU_DL_URL;'> | ||
| 491 | <filename>machines/qemu</filename></ulink> if your target architecture is supported | ||
| 492 | and you are going to develop and test your application using the QEMU | ||
| 493 | emulator.</para></listitem> | ||
| 494 | <listitem><para>Build your image if you cannot find a pre-built image that matches | ||
| 495 | your target architecture. | ||
| 496 | If your target architecture is similar to a supported architecture, you can | ||
| 497 | modify the kernel image before you build it. | ||
| 498 | See the | ||
| 499 | "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" | ||
| 500 | section in the Yocto Project Development | ||
| 501 | manual for an example.</para></listitem> | ||
| 502 | </itemizedlist></para> | ||
| 503 | <para>For information on pre-built kernel image naming schemes for images | ||
| 504 | that can run on the QEMU emulator, see the | ||
| 505 | <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. | ||
| 506 | </para></listitem> | ||
| 507 | <listitem><para><emphasis>Install the SDK</emphasis>: | ||
| 508 | The SDK provides a target-specific cross-development toolchain, the root filesystem, | ||
| 509 | the QEMU emulator, and other tools that can help you develop your application. | ||
| 510 | For information on how to install the SDK, see the | ||
| 511 | "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" | ||
| 512 | section. | ||
| 513 | </para></listitem> | ||
| 514 | <listitem><para><emphasis>Secure the target root filesystem | ||
| 515 | and the Cross-development toolchain</emphasis>: | ||
| 516 | You need to find and download the appropriate root filesystem and | ||
| 517 | the cross-development toolchain.</para> | ||
| 518 | <para>You can find the tarballs for the root filesystem in the same area used | ||
| 519 | for the kernel image. | ||
| 520 | Depending on the type of image you are running, the root filesystem you need differs. | ||
| 521 | For example, if you are developing an application that runs on an image that | ||
| 522 | supports Sato, you need to get a root filesystem that supports Sato.</para> | ||
| 523 | <para>You can find the cross-development toolchains at | ||
| 524 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. | ||
| 525 | Be sure to get the correct toolchain for your development host and your | ||
| 526 | target architecture. | ||
| 527 | See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>" | ||
| 528 | section for information and the | ||
| 529 | "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" | ||
| 530 | section for installation information. | ||
| 531 | </para></listitem> | ||
| 532 | <listitem><para><emphasis>Create and build your application</emphasis>: | ||
| 533 | At this point, you need to have source files for your application. | ||
| 534 | Once you have the files, you can use the Eclipse IDE to import them and build the | ||
| 535 | project. | ||
| 536 | If you are not using Eclipse, you need to use the cross-development tools you have | ||
| 537 | installed to create the image.</para></listitem> | ||
| 538 | <listitem><para><emphasis>Deploy the image with the application</emphasis>: | ||
| 539 | If you are using the Eclipse IDE, you can deploy your image to the hardware or to | ||
| 540 | QEMU through the project's preferences. | ||
| 541 | If you are not using the Eclipse IDE, then you need to deploy the application | ||
| 542 | to the hardware using other methods. | ||
| 543 | Or, if you are using QEMU, you need to use that tool and | ||
| 544 | load your image in for testing. | ||
| 545 | See the | ||
| 546 | "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" | ||
| 547 | chapter in the Yocto Project Development Manual | ||
| 548 | for information on using QEMU. | ||
| 549 | </para></listitem> | ||
| 550 | <listitem><para><emphasis>Test and debug the application</emphasis>: | ||
| 551 | Once your application is deployed, you need to test it. | ||
| 552 | Within the Eclipse IDE, you can use the debugging environment along with the | ||
| 553 | set of installed user-space tools to debug your application. | ||
| 554 | Of course, the same user-space tools are available separately if you choose | ||
| 555 | not to use the Eclipse IDE.</para></listitem> | ||
| 556 | </orderedlist> | ||
| 557 | </para> | ||
| 558 | </section> | ||
| 559 | |||
| 560 | <section id='adt-eclipse'> | ||
| 561 | <title>Working Within Eclipse</title> | ||
| 562 | |||
| 563 | <para> | ||
| 564 | The Eclipse IDE is a popular development environment and it fully | ||
| 565 | supports development using the Yocto Project. | ||
| 566 | <note> | ||
| 567 | This release of the Yocto Project supports both the Luna | ||
| 568 | and Kepler versions of the Eclipse IDE. | ||
| 569 | Thus, the following information provides setup information for | ||
| 570 | both versions. | ||
| 571 | </note> | ||
| 572 | </para> | ||
| 573 | |||
| 574 | <para> | ||
| 575 | When you install and configure the Eclipse Yocto Project Plug-in | ||
| 576 | into the Eclipse IDE, you maximize your Yocto Project experience. | ||
| 577 | Installing and configuring the Plug-in results in an environment | ||
| 578 | that has extensions specifically designed to let you more easily | ||
| 579 | develop software. | ||
| 580 | These extensions allow for cross-compilation, deployment, and | ||
| 581 | execution of your output into a QEMU emulation session as well as | ||
| 582 | actual target hardware. | ||
| 583 | You can also perform cross-debugging and profiling. | ||
| 584 | The environment also supports a suite of tools that allows you | ||
| 585 | to perform remote profiling, tracing, collection of power data, | ||
| 586 | collection of latency data, and collection of performance data. | ||
| 587 | </para> | ||
| 588 | |||
| 589 | <para> | ||
| 590 | This section describes how to install and configure the Eclipse IDE | ||
| 591 | Yocto Plug-in and how to use it to develop your application. | ||
| 592 | </para> | ||
| 593 | |||
| 594 | <section id='setting-up-the-eclipse-ide'> | ||
| 595 | <title>Setting Up the Eclipse IDE</title> | ||
| 596 | |||
| 597 | <para> | ||
| 598 | To develop within the Eclipse IDE, you need to do the following: | ||
| 599 | <orderedlist> | ||
| 600 | <listitem><para>Install the optimal version of the Eclipse | ||
| 601 | IDE.</para></listitem> | ||
| 602 | <listitem><para>Configure the Eclipse IDE. | ||
| 603 | </para></listitem> | ||
| 604 | <listitem><para>Install the Eclipse Yocto Plug-in. | ||
| 605 | </para></listitem> | ||
| 606 | <listitem><para>Configure the Eclipse Yocto Plug-in. | ||
| 607 | </para></listitem> | ||
| 608 | </orderedlist> | ||
| 609 | <note> | ||
| 610 | Do not install Eclipse from your distribution's package | ||
| 611 | repository. | ||
| 612 | Be sure to install Eclipse from the official Eclipse | ||
| 613 | download site as directed in the next section. | ||
| 614 | </note> | ||
| 615 | </para> | ||
| 616 | |||
| 617 | <section id='installing-eclipse-ide'> | ||
| 618 | <title>Installing the Eclipse IDE</title> | ||
| 619 | |||
| 620 | <para> | ||
| 621 | It is recommended that you have the Luna SR2 (4.4.2) | ||
| 622 | version of the Eclipse IDE installed on your development | ||
| 623 | system. | ||
| 624 | However, if you currently have the Kepler 4.3.2 version | ||
| 625 | installed and you do not want to upgrade the IDE, you can | ||
| 626 | configure Kepler to work with the Yocto Project. | ||
| 627 | </para> | ||
| 628 | |||
| 629 | <para> | ||
| 630 | If you do not have the Luna SR2 (4.4.2) Eclipse IDE | ||
| 631 | installed, you can find the tarball at | ||
| 632 | <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. | ||
| 633 | From that site, choose the appropriate download from the | ||
| 634 | "Eclipse IDE for C/C++ Developers". | ||
| 635 | This version contains the Eclipse Platform, the Java | ||
| 636 | Development Tools (JDT), and the Plug-in Development | ||
| 637 | Environment. | ||
| 638 | </para> | ||
| 639 | |||
| 640 | <para> | ||
| 641 | Once you have downloaded the tarball, extract it into a | ||
| 642 | clean directory. | ||
| 643 | For example, the following commands unpack and install the | ||
| 644 | downloaded Eclipse IDE tarball into a clean directory | ||
| 645 | using the default name <filename>eclipse</filename>: | ||
| 646 | <literallayout class='monospaced'> | ||
| 647 | $ cd ~ | ||
| 648 | $ tar -xzvf ~/Downloads/eclipse-cpp-luna-SR2-linux-gtk-x86_64.tar.gz | ||
| 649 | </literallayout> | ||
| 650 | </para> | ||
| 651 | </section> | ||
| 652 | |||
| 653 | <section id='configuring-the-eclipse-ide'> | ||
| 654 | <title>Configuring the Eclipse IDE</title> | ||
| 655 | |||
| 656 | <para> | ||
| 657 | This section presents the steps needed to configure the | ||
| 658 | Eclipse IDE. | ||
| 659 | </para> | ||
| 660 | |||
| 661 | <para> | ||
| 662 | Before installing and configuring the Eclipse Yocto Plug-in, | ||
| 663 | you need to configure the Eclipse IDE. | ||
| 664 | Follow these general steps: | ||
| 665 | <orderedlist> | ||
| 666 | <listitem><para>Start the Eclipse IDE.</para></listitem> | ||
| 667 | <listitem><para>Make sure you are in your Workbench and | ||
| 668 | select "Install New Software" from the "Help" | ||
| 669 | pull-down menu.</para></listitem> | ||
| 670 | <listitem><para>Select | ||
| 671 | <filename>Luna - &ECLIPSE_LUNA_URL;</filename> | ||
| 672 | from the "Work with:" pull-down menu. | ||
| 673 | <note> | ||
| 674 | For Kepler, select | ||
| 675 | <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename> | ||
| 676 | </note> | ||
| 677 | </para></listitem> | ||
| 678 | <listitem><para>Expand the box next to "Linux Tools" | ||
| 679 | and select the | ||
| 680 | <filename>Linux Tools LTTng Tracer Control</filename>, | ||
| 681 | <filename>Linux Tools LTTng Userspace Analysis</filename>, | ||
| 682 | and | ||
| 683 | <filename>LTTng Kernel Analysis</filename> boxes. | ||
| 684 | If these selections do not appear in the list, | ||
| 685 | that means the items are already installed. | ||
| 686 | <note> | ||
| 687 | For Kepler, select | ||
| 688 | <filename>LTTng - Linux Tracing Toolkit</filename> | ||
| 689 | box. | ||
| 690 | </note> | ||
| 691 | </para></listitem> | ||
| 692 | <listitem><para>Expand the box next to "Mobile and | ||
| 693 | Device Development" and select the following boxes. | ||
| 694 | Again, if any of the following items are not | ||
| 695 | available for selection, that means the items are | ||
| 696 | already installed: | ||
| 697 | <itemizedlist> | ||
| 698 | <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem> | ||
| 699 | <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem> | ||
| 700 | <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem> | ||
| 701 | <listitem><para><filename>Target Management Terminal (Core SDK)</filename></para></listitem> | ||
| 702 | <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem> | ||
| 703 | <listitem><para><filename>TCF Target Explorer</filename></para></listitem> | ||
| 704 | </itemizedlist></para></listitem> | ||
| 705 | <listitem><para>Expand the box next to "Programming | ||
| 706 | Languages" and select the | ||
| 707 | <filename>C/C++ Autotools Support</filename> | ||
| 708 | and <filename>C/C++ Development Tools</filename> | ||
| 709 | boxes. | ||
| 710 | For Luna, these items do not appear on the list | ||
| 711 | as they are already installed. | ||
| 712 | </para></listitem> | ||
| 713 | <listitem><para>Complete the installation and restart | ||
| 714 | the Eclipse IDE.</para></listitem> | ||
| 715 | </orderedlist> | ||
| 716 | </para> | ||
| 717 | </section> | ||
| 718 | |||
| 719 | <section id='installing-the-eclipse-yocto-plug-in'> | ||
| 720 | <title>Installing or Accessing the Eclipse Yocto Plug-in</title> | ||
| 721 | |||
| 722 | <para> | ||
| 723 | You can install the Eclipse Yocto Plug-in into the Eclipse | ||
| 724 | IDE one of two ways: use the Yocto Project's Eclipse | ||
| 725 | Update site to install the pre-built plug-in or build and | ||
| 726 | install the plug-in from the latest source code. | ||
| 727 | </para> | ||
| 728 | |||
| 729 | <section id='new-software'> | ||
| 730 | <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> | ||
| 731 | |||
| 732 | <para> | ||
| 733 | To install the Eclipse Yocto Plug-in from the update | ||
| 734 | site, follow these steps: | ||
| 735 | <orderedlist> | ||
| 736 | <listitem><para>Start up the Eclipse IDE. | ||
| 737 | </para></listitem> | ||
| 738 | <listitem><para>In Eclipse, select "Install New | ||
| 739 | Software" from the "Help" menu. | ||
| 740 | </para></listitem> | ||
| 741 | <listitem><para>Click "Add..." in the "Work with:" | ||
| 742 | area.</para></listitem> | ||
| 743 | <listitem><para>Enter | ||
| 744 | <filename>&ECLIPSE_DL_PLUGIN_URL;/luna</filename> | ||
| 745 | in the URL field and provide a meaningful name | ||
| 746 | in the "Name" field. | ||
| 747 | <note> | ||
| 748 | If you are using Kepler, use | ||
| 749 | <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename> | ||
| 750 | in the URL field. | ||
| 751 | </note></para></listitem> | ||
| 752 | <listitem><para>Click "OK" to have the entry added | ||
| 753 | to the "Work with:" drop-down list. | ||
| 754 | </para></listitem> | ||
| 755 | <listitem><para>Select the entry for the plug-in | ||
| 756 | from the "Work with:" drop-down list. | ||
| 757 | </para></listitem> | ||
| 758 | <listitem><para>Check the boxes next to | ||
| 759 | <filename>Yocto Project ADT Plug-in</filename>, | ||
| 760 | <filename>Yocto Project Bitbake Commander Plug-in</filename>, | ||
| 761 | and | ||
| 762 | <filename>Yocto Project Documentation plug-in</filename>. | ||
| 763 | </para></listitem> | ||
| 764 | <listitem><para>Complete the remaining software | ||
| 765 | installation steps and then restart the Eclipse | ||
| 766 | IDE to finish the installation of the plug-in. | ||
| 767 | <note> | ||
| 768 | You can click "OK" when prompted about | ||
| 769 | installing software that contains unsigned | ||
| 770 | content. | ||
| 771 | </note> | ||
| 772 | </para></listitem> | ||
| 773 | </orderedlist> | ||
| 774 | </para> | ||
| 775 | </section> | ||
| 776 | |||
| 777 | <section id='zip-file-method'> | ||
| 778 | <title>Installing the Plug-in Using the Latest Source Code</title> | ||
| 779 | |||
| 780 | <para> | ||
| 781 | To install the Eclipse Yocto Plug-in from the latest | ||
| 782 | source code, follow these steps: | ||
| 783 | <orderedlist> | ||
| 784 | <listitem><para>Be sure your development system | ||
| 785 | is not using OpenJDK to build the plug-in | ||
| 786 | by doing the following: | ||
| 787 | <orderedlist> | ||
| 788 | <listitem><para>Use the Oracle JDK. | ||
| 789 | If you don't have that, go to | ||
| 790 | <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink> | ||
| 791 | and download the latest appropriate | ||
| 792 | Java SE Development Kit tarball for | ||
| 793 | your development system and | ||
| 794 | extract it into your home directory. | ||
| 795 | </para></listitem> | ||
| 796 | <listitem><para>In the shell you are going | ||
| 797 | to do your work, export the location of | ||
| 798 | the Oracle Java. | ||
| 799 | The previous step creates a new folder | ||
| 800 | for the extracted software. | ||
| 801 | You need to use the following | ||
| 802 | <filename>export</filename> command | ||
| 803 | and provide the specific location: | ||
| 804 | <literallayout class='monospaced'> | ||
| 805 | export PATH=~/<replaceable>extracted_jdk_location</replaceable>/bin:$PATH | ||
| 806 | </literallayout> | ||
| 807 | </para></listitem> | ||
| 808 | </orderedlist> | ||
| 809 | </para></listitem> | ||
| 810 | <listitem><para>In the same shell, create a Git | ||
| 811 | repository with: | ||
| 812 | <literallayout class='monospaced'> | ||
| 813 | $ cd ~ | ||
| 814 | $ git clone git://git.yoctoproject.org/eclipse-poky | ||
| 815 | </literallayout> | ||
| 816 | </para></listitem> | ||
| 817 | <listitem><para>Be sure to checkout the correct | ||
| 818 | tag. | ||
| 819 | For example, if you are using Luna, do the | ||
| 820 | following: | ||
| 821 | <literallayout class='monospaced'> | ||
| 822 | $ git checkout luna/yocto-&DISTRO; | ||
| 823 | </literallayout> | ||
| 824 | This puts you in a detached HEAD state, which | ||
| 825 | is fine since you are only going to be building | ||
| 826 | and not developing. | ||
| 827 | <note> | ||
| 828 | If you are building kepler, checkout the | ||
| 829 | <filename>kepler/yocto-&DISTRO;</filename> | ||
| 830 | branch. | ||
| 831 | </note> | ||
| 832 | </para></listitem> | ||
| 833 | <listitem><para>Change to the | ||
| 834 | <filename>scripts</filename> | ||
| 835 | directory within the Git repository: | ||
| 836 | <literallayout class='monospaced'> | ||
| 837 | $ cd scripts | ||
| 838 | </literallayout> | ||
| 839 | </para></listitem> | ||
| 840 | <listitem><para>Set up the local build environment | ||
| 841 | by running the setup script: | ||
| 842 | <literallayout class='monospaced'> | ||
| 843 | $ ./setup.sh | ||
| 844 | </literallayout> | ||
| 845 | </para></listitem> | ||
| 846 | <listitem><para>When the script finishes execution, | ||
| 847 | it prompts you with instructions on how to run | ||
| 848 | the <filename>build.sh</filename> script, which | ||
| 849 | is also in the <filename>scripts</filename> | ||
| 850 | directory of the Git repository created | ||
| 851 | earlier. | ||
| 852 | </para></listitem> | ||
| 853 | <listitem><para>Run the <filename>build.sh</filename> | ||
| 854 | script as directed. | ||
| 855 | Be sure to provide the tag name, documentation | ||
| 856 | branch, and a release name. | ||
| 857 | Here is an example that uses the | ||
| 858 | <filename>luna/yocto-&DISTRO;</filename> tag, the | ||
| 859 | <filename>master</filename> documentation | ||
| 860 | branch, and | ||
| 861 | <filename>&DISTRO_NAME;</filename> for the | ||
| 862 | release name: | ||
| 863 | <literallayout class='monospaced'> | ||
| 864 | $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh luna/yocto-&DISTRO; master &DISTRO_NAME; 2>&1 | tee -a build.log | ||
| 865 | </literallayout> | ||
| 866 | After running the script, the file | ||
| 867 | <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename> | ||
| 868 | is in the current directory. | ||
| 869 | </para></listitem> | ||
| 870 | <listitem><para>If necessary, start the Eclipse IDE | ||
| 871 | and be sure you are in the Workbench. | ||
| 872 | </para></listitem> | ||
| 873 | <listitem><para>Select "Install New Software" from | ||
| 874 | the "Help" pull-down menu. | ||
| 875 | </para></listitem> | ||
| 876 | <listitem><para>Click "Add".</para></listitem> | ||
| 877 | <listitem><para>Provide anything you want in the | ||
| 878 | "Name" field. | ||
| 879 | </para></listitem> | ||
| 880 | <listitem><para>Click "Archive" and browse to the | ||
| 881 | ZIP file you built in step eight. | ||
| 882 | This ZIP file should not be "unzipped", and must | ||
| 883 | be the <filename>*archive.zip</filename> file | ||
| 884 | created by running the | ||
| 885 | <filename>build.sh</filename> script. | ||
| 886 | </para></listitem> | ||
| 887 | <listitem><para>Click the "OK" button. | ||
| 888 | </para></listitem> | ||
| 889 | <listitem><para>Check the boxes that appear in | ||
| 890 | the installation window to install the | ||
| 891 | <filename>Yocto Project ADT Plug-in</filename>, | ||
| 892 | <filename>Yocto Project Bitbake Commander Plug-in</filename>, | ||
| 893 | and the | ||
| 894 | <filename>Yocto Project Documentation plug-in</filename>. | ||
| 895 | </para></listitem> | ||
| 896 | <listitem><para>Finish the installation by clicking | ||
| 897 | through the appropriate buttons. | ||
| 898 | You can click "OK" when prompted about | ||
| 899 | installing software that contains unsigned | ||
| 900 | content. | ||
| 901 | </para></listitem> | ||
| 902 | <listitem><para>Restart the Eclipse IDE if | ||
| 903 | necessary. | ||
| 904 | </para></listitem> | ||
| 905 | </orderedlist> | ||
| 906 | </para> | ||
| 907 | |||
| 908 | <para> | ||
| 909 | At this point you should be able to configure the | ||
| 910 | Eclipse Yocto Plug-in as described in the | ||
| 911 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" | ||
| 912 | section.</para> | ||
| 913 | </section> | ||
| 914 | </section> | ||
| 915 | |||
| 916 | <section id='configuring-the-eclipse-yocto-plug-in'> | ||
| 917 | <title>Configuring the Eclipse Yocto Plug-in</title> | ||
| 918 | |||
| 919 | <para> | ||
| 920 | Configuring the Eclipse Yocto Plug-in involves setting the | ||
| 921 | Cross Compiler options and the Target options. | ||
| 922 | The configurations you choose become the default settings | ||
| 923 | for all projects. | ||
| 924 | You do have opportunities to change them later when | ||
| 925 | you configure the project (see the following section). | ||
| 926 | </para> | ||
| 927 | |||
| 928 | <para> | ||
| 929 | To start, you need to do the following from within the | ||
| 930 | Eclipse IDE: | ||
| 931 | <itemizedlist> | ||
| 932 | <listitem><para>Choose "Preferences" from the | ||
| 933 | "Window" menu to display the Preferences Dialog. | ||
| 934 | </para></listitem> | ||
| 935 | <listitem><para>Click "Yocto Project ADT" to display | ||
| 936 | the configuration screen. | ||
| 937 | </para></listitem> | ||
| 938 | </itemizedlist> | ||
| 939 | </para> | ||
| 940 | |||
| 941 | <section id='configuring-the-cross-compiler-options'> | ||
| 942 | <title>Configuring the Cross-Compiler Options</title> | ||
| 943 | |||
| 944 | <para> | ||
| 945 | To configure the Cross Compiler Options, you must select | ||
| 946 | the type of toolchain, point to the toolchain, specify | ||
| 947 | the sysroot location, and select the target | ||
| 948 | architecture. | ||
| 949 | <itemizedlist> | ||
| 950 | <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> | ||
| 951 | Choose between | ||
| 952 | <filename>Standalone pre-built toolchain</filename> | ||
| 953 | and | ||
| 954 | <filename>Build system derived toolchain</filename> | ||
| 955 | for Cross Compiler Options. | ||
| 956 | <itemizedlist> | ||
| 957 | <listitem><para><emphasis> | ||
| 958 | <filename>Standalone Pre-built Toolchain:</filename></emphasis> | ||
| 959 | Select this mode when you are using | ||
| 960 | a stand-alone cross-toolchain. | ||
| 961 | For example, suppose you are an | ||
| 962 | application developer and do not | ||
| 963 | need to build a target image. | ||
| 964 | Instead, you just want to use an | ||
| 965 | architecture-specific toolchain on | ||
| 966 | an existing kernel and target root | ||
| 967 | filesystem.</para></listitem> | ||
| 968 | <listitem><para><emphasis> | ||
| 969 | <filename>Build System Derived Toolchain:</filename></emphasis> | ||
| 970 | Select this mode if the | ||
| 971 | cross-toolchain has been installed | ||
| 972 | and built as part of the | ||
| 973 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
| 974 | When you select | ||
| 975 | <filename>Build system derived toolchain</filename>, | ||
| 976 | you are using the toolchain bundled | ||
| 977 | inside the Build Directory. | ||
| 978 | </para></listitem> | ||
| 979 | </itemizedlist> | ||
| 980 | </para></listitem> | ||
| 981 | <listitem><para><emphasis>Point to the Toolchain:</emphasis> | ||
| 982 | If you are using a stand-alone pre-built | ||
| 983 | toolchain, you should be pointing to where it is | ||
| 984 | installed. | ||
| 985 | See the | ||
| 986 | "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" | ||
| 987 | section for information about how the SDK is | ||
| 988 | installed.</para> | ||
| 989 | <para>If you are using a system-derived | ||
| 990 | toolchain, the path you provide for the | ||
| 991 | <filename>Toolchain Root Location</filename> | ||
| 992 | field is the | ||
| 993 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
| 994 | See the | ||
| 995 | "<link linkend='sdk-optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>" | ||
| 996 | section.</para></listitem> | ||
| 997 | <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> | ||
| 998 | This location is where the root filesystem for | ||
| 999 | the target hardware resides. | ||
| 1000 | </para> | ||
| 1001 | <para>The location of | ||
| 1002 | the sysroot filesystem depends on where you | ||
| 1003 | separately extracted and installed the | ||
| 1004 | filesystem.</para> | ||
| 1005 | <para>For information on how to install the | ||
| 1006 | toolchain and on how to extract and install the | ||
| 1007 | sysroot filesystem, see the | ||
| 1008 | "<link linkend='sdk-optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>" | ||
| 1009 | section. | ||
| 1010 | </para></listitem> | ||
| 1011 | <listitem><para><emphasis>Select the Target Architecture:</emphasis> | ||
| 1012 | The target architecture is the type of hardware | ||
| 1013 | you are going to use or emulate. | ||
| 1014 | Use the pull-down | ||
| 1015 | <filename>Target Architecture</filename> menu | ||
| 1016 | to make your selection. | ||
| 1017 | The pull-down menu should have the supported | ||
| 1018 | architectures. | ||
| 1019 | If the architecture you need is not listed in | ||
| 1020 | the menu, you will need to build the image. | ||
| 1021 | See the | ||
| 1022 | "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" | ||
| 1023 | section of the Yocto Project Quick Start for | ||
| 1024 | more information.</para></listitem> | ||
| 1025 | </itemizedlist> | ||
| 1026 | </para> | ||
| 1027 | </section> | ||
| 1028 | |||
| 1029 | <section id='configuring-the-target-options'> | ||
| 1030 | <title>Configuring the Target Options</title> | ||
| 1031 | |||
| 1032 | <para> | ||
| 1033 | You can choose to emulate hardware using the QEMU | ||
| 1034 | emulator, or you can choose to run your image on actual | ||
| 1035 | hardware. | ||
| 1036 | <itemizedlist> | ||
| 1037 | <listitem><para><emphasis>QEMU:</emphasis> | ||
| 1038 | Select this option if you will be using the | ||
| 1039 | QEMU emulator. | ||
| 1040 | If you are using the emulator, you also need to | ||
| 1041 | locate the kernel and specify any custom | ||
| 1042 | options.</para> | ||
| 1043 | <para>If you selected | ||
| 1044 | <filename>Build system derived toolchain</filename>, | ||
| 1045 | the target kernel you built will be located in | ||
| 1046 | the Build Directory in | ||
| 1047 | <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> | ||
| 1048 | directory. | ||
| 1049 | If you selected | ||
| 1050 | <filename>Standalone pre-built toolchain</filename>, | ||
| 1051 | the pre-built image you downloaded is located | ||
| 1052 | in the directory you specified when you | ||
| 1053 | downloaded the image.</para> | ||
| 1054 | <para>Most custom options are for advanced QEMU | ||
| 1055 | users to further customize their QEMU instance. | ||
| 1056 | These options are specified between paired | ||
| 1057 | angled brackets. | ||
| 1058 | Some options must be specified outside the | ||
| 1059 | brackets. | ||
| 1060 | In particular, the options | ||
| 1061 | <filename>serial</filename>, | ||
| 1062 | <filename>nographic</filename>, and | ||
| 1063 | <filename>kvm</filename> must all be outside the | ||
| 1064 | brackets. | ||
| 1065 | Use the <filename>man qemu</filename> command | ||
| 1066 | to get help on all the options and their use. | ||
| 1067 | The following is an example: | ||
| 1068 | <literallayout class='monospaced'> | ||
| 1069 | serial ‘<-m 256 -full-screen>’ | ||
| 1070 | </literallayout></para> | ||
| 1071 | <para> | ||
| 1072 | Regardless of the mode, Sysroot is already | ||
| 1073 | defined as part of the Cross-Compiler Options | ||
| 1074 | configuration in the | ||
| 1075 | <filename>Sysroot Location:</filename> field. | ||
| 1076 | </para></listitem> | ||
| 1077 | <listitem><para><emphasis>External HW:</emphasis> | ||
| 1078 | Select this option if you will be using actual | ||
| 1079 | hardware.</para></listitem> | ||
| 1080 | </itemizedlist> | ||
| 1081 | </para> | ||
| 1082 | |||
| 1083 | <para> | ||
| 1084 | Click the "OK" to save your plug-in configurations. | ||
| 1085 | </para> | ||
| 1086 | </section> | ||
| 1087 | </section> | ||
| 1088 | </section> | ||
| 1089 | |||
| 1090 | <section id='creating-the-project'> | ||
| 1091 | <title>Creating the Project</title> | ||
| 1092 | |||
| 1093 | <para> | ||
| 1094 | You can create two types of projects: Autotools-based, or | ||
| 1095 | Makefile-based. | ||
| 1096 | This section describes how to create Autotools-based projects | ||
| 1097 | from within the Eclipse IDE. | ||
| 1098 | For information on creating Makefile-based projects in a | ||
| 1099 | terminal window, see the | ||
| 1100 | "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>" | ||
| 1101 | section. | ||
| 1102 | <note> | ||
| 1103 | Do not use special characters in project names | ||
| 1104 | (e.g. spaces, underscores, etc.). Doing so can | ||
| 1105 | cause configuration to fail. | ||
| 1106 | </note> | ||
| 1107 | </para> | ||
| 1108 | |||
| 1109 | <para> | ||
| 1110 | To create a project based on a Yocto template and then display | ||
| 1111 | the source code, follow these steps: | ||
| 1112 | <orderedlist> | ||
| 1113 | <listitem><para>Select "Project" from the "File -> New" menu. | ||
| 1114 | </para></listitem> | ||
| 1115 | <listitem><para>Double click <filename>CC++</filename>. | ||
| 1116 | </para></listitem> | ||
| 1117 | <listitem><para>Double click <filename>C Project</filename> | ||
| 1118 | to create the project.</para></listitem> | ||
| 1119 | <listitem><para>Expand <filename>Yocto Project ADT Autotools Project</filename>. | ||
| 1120 | </para></listitem> | ||
| 1121 | <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. | ||
| 1122 | This is an Autotools-based project based on a Yocto | ||
| 1123 | template.</para></listitem> | ||
| 1124 | <listitem><para>Put a name in the <filename>Project name:</filename> | ||
| 1125 | field. | ||
| 1126 | Do not use hyphens as part of the name. | ||
| 1127 | </para></listitem> | ||
| 1128 | <listitem><para>Click "Next".</para></listitem> | ||
| 1129 | <listitem><para>Add information in the | ||
| 1130 | <filename>Author</filename> and | ||
| 1131 | <filename>Copyright notice</filename> fields. | ||
| 1132 | </para></listitem> | ||
| 1133 | <listitem><para>Be sure the <filename>License</filename> | ||
| 1134 | field is correct.</para></listitem> | ||
| 1135 | <listitem><para>Click "Finish".</para></listitem> | ||
| 1136 | <listitem><para>If the "open perspective" prompt appears, | ||
| 1137 | click "Yes" so that you in the C/C++ perspective. | ||
| 1138 | </para></listitem> | ||
| 1139 | <listitem><para>The left-hand navigation pane shows your | ||
| 1140 | project. | ||
| 1141 | You can display your source by double clicking the | ||
| 1142 | project's source file.</para></listitem> | ||
| 1143 | </orderedlist> | ||
| 1144 | </para> | ||
| 1145 | </section> | ||
| 1146 | |||
| 1147 | <section id='configuring-the-cross-toolchains'> | ||
| 1148 | <title>Configuring the Cross-Toolchains</title> | ||
| 1149 | |||
| 1150 | <para> | ||
| 1151 | The earlier section, | ||
| 1152 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>", | ||
| 1153 | sets up the default project configurations. | ||
| 1154 | You can override these settings for a given project by following | ||
| 1155 | these steps: | ||
| 1156 | <orderedlist> | ||
| 1157 | <listitem><para>Select "Change Yocto Project Settings" from | ||
| 1158 | the "Project" menu. | ||
| 1159 | This selection brings up the Yocto Project Settings | ||
| 1160 | Dialog and allows you to make changes specific to an | ||
| 1161 | individual project.</para> | ||
| 1162 | <para>By default, the Cross Compiler Options and Target | ||
| 1163 | Options for a project are inherited from settings you | ||
| 1164 | provided using the Preferences Dialog as described | ||
| 1165 | earlier in the | ||
| 1166 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section. | ||
| 1167 | The Yocto Project Settings Dialog allows you to override | ||
| 1168 | those default settings for a given project. | ||
| 1169 | </para></listitem> | ||
| 1170 | <listitem><para>Make your configurations for the project | ||
| 1171 | and click "OK". | ||
| 1172 | </para></listitem> | ||
| 1173 | <listitem><para>Right-click in the navigation pane and | ||
| 1174 | select "Reconfigure Project" from the pop-up menu. | ||
| 1175 | This selection reconfigures the project by running | ||
| 1176 | <filename>autogen.sh</filename> in the workspace for | ||
| 1177 | your project. | ||
| 1178 | The script also runs <filename>libtoolize</filename>, | ||
| 1179 | <filename>aclocal</filename>, | ||
| 1180 | <filename>autoconf</filename>, | ||
| 1181 | <filename>autoheader</filename>, | ||
| 1182 | <filename>automake --a</filename>, and | ||
| 1183 | <filename>./configure</filename>. | ||
| 1184 | Click on the "Console" tab beneath your source code to | ||
| 1185 | see the results of reconfiguring your project. | ||
| 1186 | </para></listitem> | ||
| 1187 | </orderedlist> | ||
| 1188 | </para> | ||
| 1189 | </section> | ||
| 1190 | |||
| 1191 | <section id='building-the-project'> | ||
| 1192 | <title>Building the Project</title> | ||
| 1193 | |||
| 1194 | <para> | ||
| 1195 | To build the project select "Build Project" from the | ||
| 1196 | "Project" menu. | ||
| 1197 | The console should update and you can note the cross-compiler | ||
| 1198 | you are using. | ||
| 1199 | <note> | ||
| 1200 | When building "Yocto Project ADT Autotools" projects, the Eclipse | ||
| 1201 | IDE might display error messages for Functions/Symbols/Types | ||
| 1202 | that cannot be "resolved", even when the related include file | ||
| 1203 | is listed at the project navigator and when the project is | ||
| 1204 | able to build. | ||
| 1205 | For these cases only, it is recommended to add a new linked | ||
| 1206 | folder to the appropriate sysroot. | ||
| 1207 | Use these steps to add the linked folder: | ||
| 1208 | <orderedlist> | ||
| 1209 | <listitem><para> | ||
| 1210 | Select the project. | ||
| 1211 | </para></listitem> | ||
| 1212 | <listitem><para> | ||
| 1213 | Select "Folder" from the | ||
| 1214 | <filename>File > New</filename> menu. | ||
| 1215 | </para></listitem> | ||
| 1216 | <listitem><para> | ||
| 1217 | In the "New Folder" Dialog, select "Link to alternate | ||
| 1218 | location (linked folder)". | ||
| 1219 | </para></listitem> | ||
| 1220 | <listitem><para> | ||
| 1221 | Click "Browse" to navigate to the include folder inside | ||
| 1222 | the same sysroot location selected in the Yocto Project | ||
| 1223 | configuration preferences. | ||
| 1224 | </para></listitem> | ||
| 1225 | <listitem><para> | ||
| 1226 | Click "OK". | ||
| 1227 | </para></listitem> | ||
| 1228 | <listitem><para> | ||
| 1229 | Click "Finish" to save the linked folder. | ||
| 1230 | </para></listitem> | ||
| 1231 | </orderedlist> | ||
| 1232 | </note> | ||
| 1233 | </para> | ||
| 1234 | </section> | ||
| 1235 | |||
| 1236 | <section id='starting-qemu-in-user-space-nfs-mode'> | ||
| 1237 | <title>Starting QEMU in User-Space NFS Mode</title> | ||
| 1238 | |||
| 1239 | <para> | ||
| 1240 | To start the QEMU emulator from within Eclipse, follow these | ||
| 1241 | steps: | ||
| 1242 | <note> | ||
| 1243 | See the | ||
| 1244 | "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" | ||
| 1245 | chapter in the Yocto Project Development Manual | ||
| 1246 | for more information on using QEMU. | ||
| 1247 | </note> | ||
| 1248 | <orderedlist> | ||
| 1249 | <listitem><para>Expose and select "External Tools" from | ||
| 1250 | the "Run" menu. | ||
| 1251 | Your image should appear as a selectable menu item. | ||
| 1252 | </para></listitem> | ||
| 1253 | <listitem><para>Select your image from the menu to launch | ||
| 1254 | the emulator in a new window. | ||
| 1255 | </para></listitem> | ||
| 1256 | <listitem><para>If needed, enter your host root password in | ||
| 1257 | the shell window at the prompt. | ||
| 1258 | This sets up a <filename>Tap 0</filename> connection | ||
| 1259 | needed for running in user-space NFS mode. | ||
| 1260 | </para></listitem> | ||
| 1261 | <listitem><para>Wait for QEMU to launch.</para></listitem> | ||
| 1262 | <listitem><para>Once QEMU launches, you can begin operating | ||
| 1263 | within that environment. | ||
| 1264 | One useful task at this point would be to determine the | ||
| 1265 | IP Address for the user-space NFS by using the | ||
| 1266 | <filename>ifconfig</filename> command. | ||
| 1267 | </para></listitem> | ||
| 1268 | </orderedlist> | ||
| 1269 | </para> | ||
| 1270 | </section> | ||
| 1271 | |||
| 1272 | <section id='deploying-and-debugging-the-application'> | ||
| 1273 | <title>Deploying and Debugging the Application</title> | ||
| 1274 | |||
| 1275 | <para> | ||
| 1276 | Once the QEMU emulator is running the image, you can deploy | ||
| 1277 | your application using the Eclipse IDE and then use | ||
| 1278 | the emulator to perform debugging. | ||
| 1279 | Follow these steps to deploy the application. | ||
| 1280 | <orderedlist> | ||
| 1281 | <listitem><para>Select "Debug Configurations..." from the | ||
| 1282 | "Run" menu.</para></listitem> | ||
| 1283 | <listitem><para>In the left area, expand | ||
| 1284 | <filename>C/C++Remote Application</filename>. | ||
| 1285 | </para></listitem> | ||
| 1286 | <listitem><para>Locate your project and select it to bring | ||
| 1287 | up a new tabbed view in the Debug Configurations Dialog. | ||
| 1288 | </para></listitem> | ||
| 1289 | <listitem><para>Enter the absolute path into which you want | ||
| 1290 | to deploy the application. | ||
| 1291 | Use the "Remote Absolute File Path for | ||
| 1292 | C/C++Application:" field. | ||
| 1293 | For example, enter | ||
| 1294 | <filename>/usr/bin/<replaceable>programname</replaceable></filename>. | ||
| 1295 | </para></listitem> | ||
| 1296 | <listitem><para>Click on the "Debugger" tab to see the | ||
| 1297 | cross-tool debugger you are using.</para></listitem> | ||
| 1298 | <listitem><para>Click on the "Main" tab.</para></listitem> | ||
| 1299 | <listitem><para>Create a new connection to the QEMU instance | ||
| 1300 | by clicking on "new".</para></listitem> | ||
| 1301 | <listitem><para>Select <filename>TCF</filename>, which means | ||
| 1302 | Target Communication Framework.</para></listitem> | ||
| 1303 | <listitem><para>Click "Next".</para></listitem> | ||
| 1304 | <listitem><para>Clear out the "host name" field and enter | ||
| 1305 | the IP Address determined earlier.</para></listitem> | ||
| 1306 | <listitem><para>Click "Finish" to close the | ||
| 1307 | New Connections Dialog.</para></listitem> | ||
| 1308 | <listitem><para>Use the drop-down menu now in the | ||
| 1309 | "Connection" field and pick the IP Address you entered. | ||
| 1310 | </para></listitem> | ||
| 1311 | <listitem><para>Click "Debug" to bring up a login screen | ||
| 1312 | and login.</para></listitem> | ||
| 1313 | <listitem><para>Accept the debug perspective. | ||
| 1314 | </para></listitem> | ||
| 1315 | </orderedlist> | ||
| 1316 | </para> | ||
| 1317 | </section> | ||
| 1318 | |||
| 1319 | <section id='running-user-space-tools'> | ||
| 1320 | <title>Running User-Space Tools</title> | ||
| 1321 | |||
| 1322 | <para> | ||
| 1323 | As mentioned earlier in the manual, several tools exist that | ||
| 1324 | enhance your development experience. | ||
| 1325 | These tools are aids in developing and debugging applications | ||
| 1326 | and images. | ||
| 1327 | You can run these user-space tools from within the Eclipse | ||
| 1328 | IDE through the "YoctoProjectTools" menu. | ||
| 1329 | </para> | ||
| 1330 | |||
| 1331 | <para> | ||
| 1332 | Once you pick a tool, you need to configure it for the remote | ||
| 1333 | target. | ||
| 1334 | Every tool needs to have the connection configured. | ||
| 1335 | You must select an existing TCF-based RSE connection to the | ||
| 1336 | remote target. | ||
| 1337 | If one does not exist, click "New" to create one. | ||
| 1338 | </para> | ||
| 1339 | |||
| 1340 | <para> | ||
| 1341 | Here are some specifics about the remote tools: | ||
| 1342 | <itemizedlist> | ||
| 1343 | <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> | ||
| 1344 | Selecting this tool causes the | ||
| 1345 | <filename>oprofile-server</filename> on the remote | ||
| 1346 | target to launch on the local host machine. | ||
| 1347 | The <filename>oprofile-viewer</filename> must be | ||
| 1348 | installed on the local host machine and the | ||
| 1349 | <filename>oprofile-server</filename> must be installed | ||
| 1350 | on the remote target, respectively, in order to use. | ||
| 1351 | You must compile and install the | ||
| 1352 | <filename>oprofile-viewer</filename> from the source | ||
| 1353 | code on your local host machine. | ||
| 1354 | Furthermore, in order to convert the target's sample | ||
| 1355 | format data into a form that the host can use, you must | ||
| 1356 | have OProfile version 0.9.4 or greater installed on the | ||
| 1357 | host.</para> | ||
| 1358 | <para>You can locate both the viewer and server from | ||
| 1359 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. | ||
| 1360 | You can also find more information on setting up and | ||
| 1361 | using this tool in the | ||
| 1362 | "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>" | ||
| 1363 | section of the Yocto Project Profiling and Tracing | ||
| 1364 | Manual. | ||
| 1365 | <note>The <filename>oprofile-server</filename> is | ||
| 1366 | installed by default on the | ||
| 1367 | <filename>core-image-sato-sdk</filename> image.</note> | ||
| 1368 | </para></listitem> | ||
| 1369 | <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis> | ||
| 1370 | Selecting this tool transfers the remote target's | ||
| 1371 | <filename>Lttng</filename> tracing data back to the | ||
| 1372 | local host machine and uses the Lttng Eclipse plug-in | ||
| 1373 | to graphically display the output. | ||
| 1374 | For information on how to use Lttng to trace an | ||
| 1375 | application, | ||
| 1376 | see <ulink url='http://lttng.org/documentation'></ulink> | ||
| 1377 | and the | ||
| 1378 | "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>" | ||
| 1379 | section, which is in the Yocto Project Profiling and | ||
| 1380 | Tracing Manual. | ||
| 1381 | <note>Do not use | ||
| 1382 | <filename>Lttng-user space (legacy)</filename> tool. | ||
| 1383 | This tool no longer has any upstream support.</note> | ||
| 1384 | </para> | ||
| 1385 | <para>Before you use the | ||
| 1386 | <filename>Lttng2.0 trace import</filename> tool, | ||
| 1387 | you need to setup the Lttng Eclipse plug-in and create a | ||
| 1388 | Tracing project. | ||
| 1389 | Do the following: | ||
| 1390 | <orderedlist> | ||
| 1391 | <listitem><para>Select "Open Perspective" from the | ||
| 1392 | "Window" menu and then select "Other..." to | ||
| 1393 | bring up a menu of other perspectives. | ||
| 1394 | Choose "Tracing". | ||
| 1395 | </para></listitem> | ||
| 1396 | <listitem><para>Click "OK" to change the Eclipse | ||
| 1397 | perspective into the Tracing perspective. | ||
| 1398 | </para></listitem> | ||
| 1399 | <listitem><para>Create a new Tracing project by | ||
| 1400 | selecting "Project" from the "File -> New" menu. | ||
| 1401 | </para></listitem> | ||
| 1402 | <listitem><para>Choose "Tracing Project" from the | ||
| 1403 | "Tracing" menu and click "Next". | ||
| 1404 | </para></listitem> | ||
| 1405 | <listitem><para>Provide a name for your tracing | ||
| 1406 | project and click "Finish". | ||
| 1407 | </para></listitem> | ||
| 1408 | <listitem><para>Generate your tracing data on the | ||
| 1409 | remote target.</para></listitem> | ||
| 1410 | <listitem><para>Select "Lttng2.0 trace import" | ||
| 1411 | from the "Yocto Project Tools" menu to | ||
| 1412 | start the data import process.</para></listitem> | ||
| 1413 | <listitem><para>Specify your remote connection name. | ||
| 1414 | </para></listitem> | ||
| 1415 | <listitem><para>For the Ust directory path, specify | ||
| 1416 | the location of your remote tracing data. | ||
| 1417 | Make sure the location ends with | ||
| 1418 | <filename>ust</filename> (e.g. | ||
| 1419 | <filename>/usr/mysession/ust</filename>). | ||
| 1420 | </para></listitem> | ||
| 1421 | <listitem><para>Click "OK" to complete the import | ||
| 1422 | process. | ||
| 1423 | The data is now in the local tracing project | ||
| 1424 | you created.</para></listitem> | ||
| 1425 | <listitem><para>Right click on the data and then use | ||
| 1426 | the menu to Select "Generic CTF Trace" from the | ||
| 1427 | "Trace Type... -> Common Trace Format" menu to | ||
| 1428 | map the tracing type.</para></listitem> | ||
| 1429 | <listitem><para>Right click the mouse and select | ||
| 1430 | "Open" to bring up the Eclipse Lttng Trace | ||
| 1431 | Viewer so you view the tracing data. | ||
| 1432 | </para></listitem> | ||
| 1433 | </orderedlist></para></listitem> | ||
| 1434 | <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> | ||
| 1435 | Selecting this tool runs PowerTOP on the remote target | ||
| 1436 | machine and displays the results in a new view called | ||
| 1437 | PowerTOP.</para> | ||
| 1438 | <para>The "Time to gather data(sec):" field is the time | ||
| 1439 | passed in seconds before data is gathered from the | ||
| 1440 | remote target for analysis.</para> | ||
| 1441 | <para>The "show pids in wakeups list:" field corresponds | ||
| 1442 | to the <filename>-p</filename> argument passed to | ||
| 1443 | <filename>PowerTOP</filename>.</para></listitem> | ||
| 1444 | <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> | ||
| 1445 | LatencyTOP identifies system latency, while | ||
| 1446 | Perf monitors the system's performance counter | ||
| 1447 | registers. | ||
| 1448 | Selecting either of these tools causes an RSE terminal | ||
| 1449 | view to appear from which you can run the tools. | ||
| 1450 | Both tools refresh the entire screen to display results | ||
| 1451 | while they run. | ||
| 1452 | For more information on setting up and using | ||
| 1453 | <filename>perf</filename>, see the | ||
| 1454 | "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" | ||
| 1455 | section in the Yocto Project Profiling and Tracing | ||
| 1456 | Manual. | ||
| 1457 | </para></listitem> | ||
| 1458 | <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis> | ||
| 1459 | Systemtap is a tool that lets you create and reuse | ||
| 1460 | scripts to examine the activities of a live Linux | ||
| 1461 | system. | ||
| 1462 | You can easily extract, filter, and summarize data | ||
| 1463 | that helps you diagnose complex performance or | ||
| 1464 | functional problems. | ||
| 1465 | For more information on setting up and using | ||
| 1466 | <filename>SystemTap</filename>, see the | ||
| 1467 | <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>. | ||
| 1468 | </para></listitem> | ||
| 1469 | <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis> | ||
| 1470 | The <filename>yocto-bsp</filename> tool lets you | ||
| 1471 | quickly set up a Board Support Package (BSP) layer. | ||
| 1472 | The tool requires a Metadata location, build location, | ||
| 1473 | BSP name, BSP output location, and a kernel | ||
| 1474 | architecture. | ||
| 1475 | For more information on the | ||
| 1476 | <filename>yocto-bsp</filename> tool outside of Eclipse, | ||
| 1477 | see the | ||
| 1478 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>" | ||
| 1479 | section in the Yocto Project Board Support Package | ||
| 1480 | (BSP) Developer's Guide. | ||
| 1481 | </para></listitem> | ||
| 1482 | </itemizedlist> | ||
| 1483 | </para> | ||
| 1484 | </section> | ||
| 1485 | </section> | ||
| 451 | </section> | 1486 | </section> |
| 452 | 1487 | ||
| 453 | <section id='sdk-using-the-sdk-to-task-2'> | 1488 | <section id='sdk-using-the-sdk-to-task-2'> |