aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLiping Ke <liping.ke@intel.com>2010-06-21 15:43:24 +0800
committerLiping Ke <liping.ke@intel.com>2010-06-28 13:37:17 +0800
commite2f3fc45a7cc606442f78340432589ab68b456c1 (patch)
tree20c8b6ad4676867b0ae903fe18030925542a2fc5
parent3334ddc95d85dff847580997b9e898b255eb0fa3 (diff)
downloadanjuta-poky-e2f3fc45a7cc606442f78340432589ab68b456c1.tar.gz
anjuta-poky-e2f3fc45a7cc606442f78340432589ab68b456c1.tar.bz2
anjuta-poky-e2f3fc45a7cc606442f78340432589ab68b456c1.zip
Update README document for Anjuta POKY plugin
Signed-off-by: Liping Ke <Liping.ke@intel.com>
-rw-r--r--README319
1 files changed, 180 insertions, 139 deletions
diff --git a/README b/README
index 7156eb8..5b4a4d7 100644
--- a/README
+++ b/README
@@ -1,8 +1,11 @@
-Anjuta Poky SDK Plugin
-~~~~~~ ~~~~ ~~~ ~~~~~~
+Anjuta Poky SDK Plugin quick start
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This plugin provides a platform for software development against the Poky
-platform.
+[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.
@@ -10,139 +13,177 @@ Technologies B.V.
Please see the AUTHORS file for details of the authors.
-Features:
-~~~~~~~~~
-
-* Starting and stopping QEMU
-* Cross-compiling an autotooled project within the the Anjuta IDE
-* Deployment of the built project and data files into QEMU
-* Remote invocation of programs in QEMU
-* Cross-debugging of the binaries in QEMU
-* Integration with OProfileUI
-
-
-Dependencies
-~~~~~~~~~~~~
-
-* A Poky cross toolchain (this can be fetched fetched by following the links
- from http://www.pokylinux.org).
-
-* Anjuta 2.4.0 or newer (e.g. SVN trunk). Although this can be installed into
- a custom prefix please ensure you do not have any older versions installed
- in other prefixes which might conflict.
-
-* OProfileUI 0.2.0 or newer (e.g. SVN trunk). [Optional]
-
-
-Pre-built packages
-~~~~~~~~~ ~~~~~~~~
-
-Packages built for Debian 'unstable' and Ubuntu 'gutsy' can be found in the
-OpenedHand repository. Details of the entries to add to your sources.list can
-be found at http://debian.o-hand.com.
-
-The packages that you need to install are: anjuta, anjuta-plugin-sdk and
-optionally oprofile and oprofile-viewer.
-
-
-Building
-~~~~~~~~
-
-Once Anjuta is installed the plugin can be built with the following commands:
-
-./configure
-make
-sudo make install
-
-(NB: If you install an updated Anjuta you may need to rebuild the plugin and
-reinstall it.)
-
-
-Setup
-~~~~~
-
-Extract the tarball for the toolchain into / as root. The toolchain will be
-installed into /usr/local/poky.
-
-To use the plugin, first open or create an existing project. If creating a new
-project the "C GTK+" project type will allow itself to be cross-compiled.
-However you should be aware that this uses glade for the UI.
-
-To activate the plugin go Edit->Preferences, then choose "General" from the left
-hand side. Choose the Installed plugins tab, scroll down to "Poky SDK" and
-check the box. The plugin is now activated but first it must be configured.
-
-Choose the "Poky SDK" icon from the left hand side, this will show the
-configuration options for the plugin.
-
-
-Configuration
-~~~~~~~~~~~~~
-
-The configuration options presented in the preferences are:
-
-* "SDK root" this is the root directory of the SDK for an ARM EABI SDK this
- will be "/usr/local/poky/eabi-glibc/arm". This directory will contain
- directories named like "bin", "include", "var", etc. With the file chooser
- it is important to enter into the "arm" subdirectory for this example.
-
-* "Toolchain triplet" this is the cross compile triplet, e.g.
- "arm-poky-linux-gnueabi". The triplet can be identified from a directory
- within the "SDK root"
-
-* "Kernel" use the file chooser to select the kernel to use with QEMU
-
-* "Root filesystem" use the file chooser to select the root filesystem image,
- this should be an image (not a tarball)
-
-
-Usage
-~~~~~
-
-As an example, cross-compiling a project, deploying it into QEMU and running a
-debugger against it.
-
-* Choose "Build->Run Configure" or "Build->Run Autogenerate" to configure (or
- to run "autogen" on the project.) This passes command line arguments to
- instruct it to cross-compile.
-
-* Next do "Build->Build Project" to build and compile the project. If you have
- previously built the project in the same tree without using the
- cross-compiler you may find that your project fails to link. Simply do
- "Build->Clean Project" to remove the old binaries. You may then try building
- again.
-
-* Next start QEMU by using "Tools->Start QEMU", this will start QEMU and will
- show some any error messages in an message view. Once Poky has fully booted
- within QEMU you may now deploy into it
-
-* Once built and QEMU is running, choose "Tools->Deploy", this will install
- the package into a temporary directory and then copy using rsync over SSH
- into the target. Progress and messages will be shown in the message view.
-
-* 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. You should setup any breakpoints
- or watchpoints now since you might not be able to interrupt the execution
- later. You may find it necessary to stop the debugger on the target using
- "Tools->Stop debugger".
-
-* It is also possible to execute a command in the target over SSH, the
- appropriate environment will be be set for the execution. Choose "Tools->Run
- remote" to do this. This will open a terminal with the SSH command inside.
-
-* To do a system wide profile against the system running in QEMU choose
- "Tools->Profile remote". This will start up OProfileUI with the appropriate
- parameters to connect to the server running inside QEMU and will also supply
- the path to the debug information necessary to get a useful profile.
-
-
-Bugs
-~~~~
+[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)
-Please submit bugs to http://bugzilla.o-hand.com