aboutsummaryrefslogtreecommitdiffstats
Anjuta Poky SDK Plugin quick start
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[Introduction]

Poky SDK plugin provides a UI based cross build, remote deploy,
remote run, remote debug and remote profile tools integrated
with Anjuta IDE for application developers under poky build platform.

This plugin was developed by OpenedHand Ltd. with funding from iRex
Technologies B.V.

Please see the AUTHORS file for details of the authors.


[Key Features]

* Cross-compiling an autotool project within the Anjuta IDE
* Deployment of the built project and data files into remote target
* Remote invocation of applications on remote target
* Remote debugging of the binaries on remote target
* Integration with OProfileUI, providing remote target profiling support
* Provide QEMU as a sample and testing remote target


[Prerequisite Environment]

1. Poky (Please refer to http://www.pokylinux.org) platform need to be setup
   before installing poky sdk plugin. For how to setup poky cross tool chain,
   please refer to poky hand book which could be fetched in the below URL:
   http://pokylinux.org/doc/poky-handbook.html
   a. Make sure poky SDK tools tarball (include whole tool chain) are 
      successfully generated. You can get it under the folder of
     [poky_work_dir]/build/tmp/deploy/sdk/...toolchain-3.2.1-tar.bz2
   b. If you want to have QEMU as your testing device target, make sure
      QEMU Kernel and ROOTFS are successfully generated. You can fetch it
      under the folder of [poky_work_dir]/build/tmp/deploy/image/
   c. For verifying above steps, you can try whether you can start the QEMU
      successfully($runqemu qemux86). If yes, go on with following installation
      steps.

2. For viewing remote target profiling result, oprofile viewer 0.2.0 or newer
   version is required on the host and oprofile (0.9.3 or newer version) is 
   required to be cross compiled/built and installed on the target file system.
   This could be achieved by selecting profile-tools related options in poky
   local.conf configuration files. For details, please refer to poky handbook,
   profiling related sections.

3. Ubuntu 9.10 is bounded with Anjuta 2.28 version. And Ubuntu 10.04 is bounded
   with Anjuta 2.30 version. This is the two recommended platform combination
   for this poky SDK plugin since the above two platforms has been tested.


[Installation resources]

1. Fetch poky platform builder from www.pokylinux.org, latest release is 3.2.1.
   Build the whole cross tool chain for the target system. If you want to use
   QEMU as the emulated target, you have to build the whole QEMU image and QEMU
   root file system with poky platform builder. And more, if you want to
   support remote profiling, you must select all profile related tools and
   installed them in the target system. If you are using the default QEMU,
   you're recommended to build those packages into QEMU root file system
   (please refer to prerequisite environment, item 2). For details about how to
   use poky platform builder to build the whole cross tool chains and the QEMU
   emulator, please refer to poky handbook as mentioned above.

2. For Ubuntu, you can directly use apt-get install command to install
   anjuta IDE. Or you can fetch anjuta installation packages from
   http://www.anjuta.org/

3. Fetch poky anjuta sdk plugin from
  http://labs.o-hand.com/anjuta-poky-sdk-plugin/

4. For Ubuntu, you can directly use apt-get install command to install
   OprofileUI viewer related packages.


[How to build and install]

Once the above prerequisite environments are setup, you can simply untar
the plugin sdk, then run below commands:
  $./configure
  $make
  $sudo make install

For verifying your installation, please open Anjuta Preference Page, You will
see the poky SDK plugin is listed on the "installed plugin" page.

(NB: If you install an updated Anjuta you may need to rebuild the plugin
and reinstall it.)


[Setup Poky SDK plugin configuration]

1. Extract the tool chain tarball to / as root. The tool chain will be
   installed into /usr/local/poky. If you have the whole set of poky platform
   builder environment, you can skip this step.
2. Go to anjuta preference page (Edit->Preference), Choose "General" icon in
   the left column and select "Installed plugins" tab page in the right column,
   select "Poky SDK" plugin. Then poky sdk plugin will be activated.
3. After activating Poky SDK plugin after step 2, Configure Poky SDK Plugin
   as following:
   a. "SDK root" is the root directory of the SDK. This is the directory you
      created in the step 1 above. This directory contains directories like
      "bin", "include", "var", etc. Please choose option 
      "Use an external toolchain" and set SDK root to 
      "/usr/local/poky/eabi-glibc".
   b. If you already have the whole poky platform builder working directory and
      build all tool chains already, you can directly choose option
      "Use a full Poky tree" and set the poky tree root,
      eg: "/home/lke/[poky_work_dir]".
   c. Tool chain triplet is the triplet prefix name of the cross compile tools.
      eg: "i586-poky-linux". This triplet name is actually a directory name
      you can find under your poky SDK root.
   c. If we use QEMU as the target testing device, You must set the QEMU kernel
      and QEMU root file system. Please refer to the prerequisite sections for
      where to get these files. If we use real device instead of QEMU, please
      directly set the IP address of the remote device.
   

[How to create/build a hello world project with poky cross tools and
run/debug/profiling against QEMU]

1.  Create the project using poky build cross tools.
    Create the project in the normal way, then activate Poky SDK plugin as
    section[Setup Poky SDK plugin configuration], item 2. Then this newly
    created project will use poky build cross tools to build.

2.  Build this new project as normal way
    Click "Build->Run Configure" to configure this project. It will set project
    build configurations, make poky build cross tools to build the whole
    project. Then you can freely build project, clean project binaries as normal.

3.  How to run this newly created binary to the target?
    If we need to deploy the binary to the QEMU, first we need to click "Tools
    ->Start QEMU" and start QEMU. After QEMU launches,  click "Tools->deploy".
    The binary together with its docs will be successfully deployed on the 
    remote target, here it is QEMU. The binary and docs are deployed under
    /usr/local/bin/binary_name and /usr/local/doc/[project name] on the remote
    target.

4. You can also directly run a remote application through SSH  by click
   "Tools->Run Remote". The application output will be directed to the Anjuta
   Integrated message pages "Remote".

5. To debug a program installed into onto the target choose "Tools->Debug
   remote". This prompts for the local binary to debug and also the command
   line to run on the target. The command line to run should include the full
   path to the to binary installed in the target. This will start a gdbserver
   over SSH on the target and also an instance of a cross-gdb in a local
   terminal. This will be preloaded to connect to the server and use the "SDK
   root" to find symbols.  This gdb will connect to the target and load in
   various libraries and the target program. All the input output will be
   directed to the anjuta integrated vte terminals. You can operate the gdb
   commands on the host terminal as usual. For eg: You can setup any breakpoint
   or watchpoint now. "Tools->Stop Debugger" will stop remote GDB server.
   If you want to exit the GDB local, just input "quit" on the terminal as
   usual.

6. For profiling remote target, make sure all profile related tools be
   installed on the target root file system as stated in the prerequisite
   sections. And then you can click "Tools->Profile remote". This will start
   up OProfileUI with the appropriate parameters to connect to the remote
   profile server running inside QEMU and will also supply the path to the
   debug information necessary to get a useful profile.


[Known Issues]

1. For Known bugs status tracking, please refer to
   http://bugzilla.o-hand.com, anjuta-integration component.
2. Poky SDK plugin configuration is now global. eg: We can't make two
   projects using different SDK root.
3. If communication errors happening or other unexpected UI flow happening,
   the Tools Menu disable/enable status might not be correct. We have to
   restart anjuta.
4. Some instability issues are reported for gdb client and server
   communications. We have to restart the anjuta for reconnection.

[Limitations]
1. Currently poky SDK plugin is only tested under [Unbuntu9.04/Unbunt9.10,
   Anjuta 2.28] and [Ubuntu10.04 Anjuta 2.30] environment, validated under
   poky 3.2.1 purple release.
2. If you find any issues, please report@ http://bugzilla.o-hand.com,
   anjuta-integration component.


(This document is only a draft, eg. new bugzilla will soon be setup)