diff --git a/documentation/adt-manual/adt-eclipse.xml b/documentation/adt-manual/adt-eclipse.xml
deleted file mode 100644
index 4d400ad6df..0000000000
--- a/documentation/adt-manual/adt-eclipse.xml
+++ /dev/null
@@ -1,740 +0,0 @@
- %poky; ] >
-
-
-Working Within Eclipse
-
-
- The Eclipse IDE is a popular development environment and it fully supports
- development using the Yocto Project.
- When you install and configure the Eclipse Yocto Project Plug-in into
- the Eclipse IDE, you maximize your Yocto Project experience.
- Installing and configuring the Plug-in results in an environment that
- has extensions specifically designed to let you more easily develop software.
- These extensions allow for cross-compilation, deployment, and execution of
- your output into a QEMU emulation session.
- You can also perform cross-debugging and profiling.
- The environment also supports a suite of tools that allows you to perform
- remote profiling, tracing, collection of power data, collection of
- latency data, and collection of performance data.
-
-
- This section describes how to install and configure the Eclipse IDE
- Yocto Plug-in and how to use it to develop your application.
-
-
-
- Setting Up the Eclipse IDE
-
-
- To develop within the Eclipse IDE, you need to do the following:
-
- Install the optimal version of the Eclipse IDE.
- Configure the Eclipse IDE.
- Install the Eclipse Yocto Plug-in.
- Configure the Eclipse Yocto Plug-in.
-
-
- Do not install Eclipse from your distribution's package repository.
- Be sure to install Eclipse from the official Eclipse download site as directed
- in the next section.
-
-
-
-
- Installing the Eclipse IDE
-
-
- It is recommended that you have the Indigo 3.7.2 version of the
- Eclipse IDE installed on your development system.
- If you don’t have this version, you can find it at
- .
- From that site, choose the Eclipse Classic version particular to your development
- host.
- This version contains the Eclipse Platform, the Java Development
- Tools (JDT), and the Plug-in Development Environment.
-
-
-
- Once you have downloaded the tarball, extract it into a clean
- directory.
- For example, the following commands unpack and install the Eclipse IDE
- tarball found in the Downloads area
- into a clean directory using the default name eclipse:
-
- $ cd ~
- $ tar -xzvf ~/Downloads/eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz
-
-
-
-
- One issue exists that you need to be aware of regarding the Java
- Virtual machine’s garbage collection (GC) process.
- The GC process does not clean up the permanent generation
- space (PermGen).
- This space stores metadata descriptions of classes.
- The default value is set too small and it could trigger an
- out-of-memory error such as the following:
-
- Java.lang.OutOfMemoryError: PermGen space
-
-
-
-
- This error causes the application to hang.
-
-
-
- To fix this issue, you can use the --vmargs
- option when you start Eclipse to increase the size of the permanent generation space:
-
- eclipse --vmargs --XX:PermSize=256M
-
-
-
-
-
- Configuring the Eclipse IDE
-
-
- Before installing and configuring the Eclipse Yocto Plug-in, you need to configure
- the Eclipse IDE.
- Follow these general steps to configure Eclipse:
-
- Start the Eclipse IDE.
- Make sure you are in your Workbench and select
- "Install New Software" from the "Help" pull-down menu.
-
- Select indigo - &ECLIPSE_INDIGO_URL;
- from the "Work with:" pull-down menu.
- Expand the box next to Programming Languages
- and select the Autotools Support for CDT (incubation)
- and C/C++ Development Tools boxes.
- Expand the box next to "Linux Tools" and select the
- "LTTng - Linux Tracing Toolkit(incubation)" boxes.
- Complete the installation and restart the Eclipse IDE.
- After the Eclipse IDE restarts and from the Workbench, select
- "Install New Software" from the "Help" pull-down menu.
- Click the
- "Available Software Sites" link.
- Check the box next to
- &ECLIPSE_UPDATES_URL;
- and click "OK".
- Select &ECLIPSE_UPDATES_URL;
- from the "Work with:" pull-down menu.
- Check the box next to TM and RSE Main Features.
-
- Expand the box next to TM and RSE Optional Add-ons
- and select every item except RSE Unit Tests and
- RSE WinCE Services (incubation).
- Complete the installation and restart the Eclipse IDE.
- If necessary, select
- "Install New Software" from the "Help" pull-down menu so you can click the
- "Available Software Sites" link again.
- After clicking "Available Software Sites", check the box next to
- http://download.eclipse.org/tools/cdt/releases/indigo
- and click "OK".
- Select &ECLIPSE_INDIGO_CDT_URL;
- from the "Work with:" pull-down menu.
- Check the box next to CDT Main Features.
-
- Expand the box next to CDT Optional Features
- and select C/C++ Remote Launch and
- Target Communication Framework (incubation).
- Complete the installation and restart the Eclipse IDE.
-
-
-
-
-
- Installing or Accessing the Eclipse Yocto Plug-in
-
-
- You can install the Eclipse Yocto Plug-in into the Eclipse IDE
- one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in,
- or build and install the plug-in from the latest source code.
- If you don't want to permanently install the plug-in but just want to try it out
- within the Eclipse environment, you can import the plug-in project from the
- Yocto Project source repositories.
-
-
-
- Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site
-
-
- To install the Eclipse Yocto Plug-in from the update site,
- follow these steps:
-
- Start up the Eclipse IDE.
- In Eclipse, select "Install New Software" from the "Help" menu.
- Click "Add..." in the "Work with:" area.
- Enter
- &ECLIPSE_DL_PLUGIN_URL;
- in the URL field and provide a meaningful name in the "Name" field.
- Click "OK" to have the entry added to the "Work with:"
- drop-down list.
- Select the entry for the plug-in from the "Work with:" drop-down
- list.
- Check the box next to Development tools and SDKs for Yocto Linux.
-
- Complete the remaining software installation steps and
- then restart the Eclipse IDE to finish the installation of the plug-in.
-
-
-
-
-
-
- Installing the Plug-in Using the Latest Source Code
-
- To install the Eclipse Yocto Plug-in from the latest source code, follow these steps:
-
- Open a shell and create a Git repository with:
-
- $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
-
- For this example, the repository is named
- ~/yocto-eclipse.
- Locate the build.sh script in the
- Git repository you created in the previous step.
- The script is located in the scripts.
- Be sure to set and export the ECLIPSE_HOME environment
- variable to the top-level directory in which you installed the Indigo
- version of Eclipse.
- For example, if your Eclipse directory is $HOME/eclipse,
- use the following:
-
- $ export ECLIPSE_HOME=$HOME/eclipse
-
- Run the build.sh script and provide the
- name of the Git branch along with the Yocto Project release you are
- using.
- Here is an example that uses the master Git repository
- and the 1.1M4 release:
-
- $ scripts/build.sh master 1.1M4
-
- After running the script, the file
- org.yocto.sdk-<release>-<date>-archive.zip
- is in the current directory.
- If necessary, start the Eclipse IDE and be sure you are in the
- Workbench.
- Select "Install New Software" from the "Help" pull-down menu.
-
- Click "Add".
- Provide anything you want in the "Name" field.
- Click "Archive" and browse to the ZIP file you built
- in step four.
- This ZIP file should not be "unzipped", and must be the
- *archive.zip file created by running the
- build.sh script.
- Check the box next to the new entry in the installation window and complete
- the installation.
- Restart the Eclipse IDE if necessary.
-
-
-
-
- At this point you should be able to configure the Eclipse Yocto Plug-in as described in the
- "Configuring the Eclipse Yocto Plug-in"
- section.
-
-
-
- Importing the Plug-in Project into the Eclipse Environment
-
- Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories
- is useful when you want to try out the latest plug-in from the tip of plug-in's
- development tree.
- It is important to understand when you import the plug-in you are not installing
- it into the Eclipse application.
- Rather, you are importing the project and just using it.
- To import the plug-in project, follow these steps:
-
- Open a shell and create a Git repository with:
-
- $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
-
- For this example, the repository is named
- ~/yocto-eclipse.
- In Eclipse, select "Import" from the "File" menu.
- Expand the "General" box and select "existing projects into workspace"
- and then click "Next".
- Select the root directory and browse to
- ~/yocto-eclipse/plugins.
- Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and
- "org.yocto.sdk.remotetools".
- Select and import all of them.
-
-
-
-
- The left navigation pane in the Eclipse application shows the default projects.
- Right-click on one of these projects and run it as an Eclipse application.
- This brings up a second instance of Eclipse IDE that has the Yocto Plug-in.
-
-
-
-
-
- Configuring the Eclipse Yocto Plug-in
-
-
- Configuring the Eclipse Yocto Plug-in involves setting the Cross
- Compiler options and the Target options.
- The configurations you choose become the default settings for all projects.
- You do have opportunities to change them later when
- you configure the project (see the following section).
-
-
-
- To start, you need to do the following from within the Eclipse IDE:
-
- Choose Windows -> Preferences to display
- the Preferences Dialog
- Click Yocto Project ADT
-
-
-
-
- Configuring the Cross-Compiler Options
-
-
- To configure the Cross Compiler Options, you must select the type of toolchain,
- point to the toolchain, specify the sysroot location, and select the target architecture.
-
- Selecting the Toolchain Type:
- Choose between Standalone pre-built toolchain
- and Build system derived toolchain for Cross
- Compiler Options.
-
-
- Standalone Pre-built Toolchain:
- Select this mode when you are using a stand-alone cross-toolchain.
- For example, suppose you are an application developer and do not
- need to build a target image.
- Instead, you just want to use an architecture-specific toolchain on an
- existing kernel and target root filesystem.
-
-
- Build System Derived Toolchain:
- Select this mode if the cross-toolchain has been installed and built
- as part of the build directory.
- When you select Build system derived toolchain,
- you are using the toolchain bundled
- inside the build directory.
-
-
-
- Point to the Toolchain:
- If you are using a stand-alone pre-built toolchain, you should be pointing to the
- &YOCTO_ADTPATH_DIR; directory.
- This is the location for toolchains installed by the ADT Installer or by hand.
- Sections "Configuring
- and Running the ADT Installer Script" and
- "Using a Cross-Toolchain
- Tarball" describe two ways to install
- a stand-alone cross-toolchain in the
- /opt/poky directory.
- It is possible to install a stand-alone cross-toolchain in a directory
- other than /opt/poky.
- However, doing so is discouraged.
- If you are using a system-derived toolchain, the path you provide
- for the Toolchain Root Location
- field is the build directory.
- See section "Using
- BitBake and the build directory" for
- information on how to install the toolchain into the build directory.
- Specify the Sysroot Location:
- This location is where the root filesystem for the
- target hardware is created on the development system by the ADT Installer.
- The QEMU user-space tools, the
- NFS boot process, and the cross-toolchain all use the sysroot location.
-
- Select the Target Architecture:
- The target architecture is the type of hardware you are
- going to use or emulate.
- Use the pull-down Target Architecture menu to make
- your selection.
- The pull-down menu should have the supported architectures.
- If the architecture you need is not listed in the menu, you
- will need to build the image.
- See the "Building an Image" section
- of The Yocto Project Quick Start for more information.
-
-
-
-
-
- Configuring the Target Options
-
-
- You can choose to emulate hardware using the QEMU emulator, or you
- can choose to run your image on actual hardware.
-
- QEMU: Select this option if
- you will be using the QEMU emulator.
- If you are using the emulator, you also need to locate the kernel
- and specify any custom options.
- If you selected Build system derived toolchain,
- the target kernel you built will be located in the
- build directory in tmp/deploy/images directory.
- If you selected Standalone pre-built toolchain, the
- pre-built image you downloaded is located
- in the directory you specified when you downloaded the image.
- Most custom options are for advanced QEMU users to further
- customize their QEMU instance.
- These options are specified between paired angled brackets.
- Some options must be specified outside the brackets.
- In particular, the options serial,
- nographic, and kvm must all
- be outside the brackets.
- Use the man qemu command to get help on all the options
- and their use.
- The following is an example:
-
- serial ‘<-m 256 -full-screen>’
-
-
- Regardless of the mode, Sysroot is already defined as part of the
- Cross Compiler Options configuration in the
- Sysroot Location: field.
- External HW: Select this option
- if you will be using actual hardware.
-
-
-
-
- Click the OK button to save your plug-in configurations.
-
-
-
-
-
-
-Creating the Project
-
-
- You can create two types of projects: Autotools-based, or Makefile-based.
- This section describes how to create Autotools-based projects from within
- the Eclipse IDE.
- For information on creating Makefile-based projects in a terminal window, see the section
- "Using the Command Line".
-
-
-
- To create a project based on a Yocto template and then display the source code,
- follow these steps:
-
- Select File -> New -> Project.
- Double click CC++.
- Double click C Project to create the project.
- Expand Yocto Project ADT Project.
- Select Hello World ANSI C Autotools Project.
- This is an Autotools-based project based on a Yocto template.
- Put a name in the Project name: field.
- Do not use hyphens as part of the name.
- Click Next.
- Add information in the Author and
- Copyright notice fields.
- Be sure the License field is correct.
- Click Finish.
- If the "open perspective" prompt appears, click "Yes" so that you
- in the C/C++ perspective.
- The left-hand navigation pane shows your project.
- You can display your source by double clicking the project's source file.
-
-
-
-
-
-
-Configuring the Cross-Toolchains
-
-
- The earlier section, "Configuring
- the Eclipse Yocto Plug-in", sets up the default project
- configurations.
- You can override these settings for a given project by following these steps:
-
- Select Project -> Change Yocto Project Settings:
- This selection brings up the Yocot Project Settings Dialog
- and allows you to make changes specific to an individual project.
-
- By default, the Cross Compiler Options and Target Options for a project
- are inherited from settings you provide using the Preferences
- Dialog as described earlier
- in the "Configuring the Eclipse
- Yocto Plug-in" section.
- The Yocto Project Settings
- Dialog allows you to override those default settings
- for a given project.
- Make your configurations for the project and click "OK".
- Select Project -> Reconfigure Project:
- This selection reconfigures the project by running
- autogen.sh in the workspace for your project.
- The script also runs libtoolize, aclocal,
- autoconf, autoheader,
- automake --a, and
- ./configure.
- Click on the Console tab beneath your source code to
- see the results of reconfiguring your project.
-
-
-
-
-
-Building the Project
-
-
- To build the project, select Project -> Build Project.
- The console should update and you can note the cross-compiler you are using.
-
-
-
-
-Starting QEMU in User Space NFS Mode
-
-
- To start the QEMU emulator from within Eclipse, follow these steps:
-
- Expose the Run -> External Tools menu.
- Your image should appear as a selectable menu item.
-
- Select your image from the menu to launch the
- emulator in a new window.
- If needed, enter your host root password in the shell window at the prompt.
- This sets up a Tap 0 connection needed for running in user-space
- NFS mode.
- Wait for QEMU to launch.
- Once QEMU launches, you can begin operating within that
- environment.
- For example, you could determine the IP Address
- for the user-space NFS by using the ifconfig command.
-
-
-
-
-
-
-Deploying and Debugging the Application
-
-
- Once the QEMU emulator is running the image, using the Eclipse IDE
- you can deploy your application and use the emulator to perform debugging.
- Follow these steps to deploy the application.
-
- Select Run -> Debug Configurations...
- In the left area, expand C/C++Remote Application.
- Locate your project and select it to bring up a new
- tabbed view in the Debug Configurations Dialog.
- Enter the absolute path into which you want to deploy
- the application.
- Use the Remote Absolute File Path for C/C++Application: field.
- For example, enter /usr/bin/<programname>.
- Click on the Debugger tab to see the cross-tool debugger
- you are using.
- Click on the Main tab.
- Create a new connection to the QEMU instance
- by clicking on new.
- Select TCF, which means Target Communication
- Framework.
- Click Next.
- Clear out the host name field and enter the IP Address
- determined earlier.
- Click Finish to close the
- New Connections Dialog.
- Use the drop-down menu now in the Connection field and pick
- the IP Address you entered.
- Click Debug to bring up a login screen
- and login.
- Accept the debug perspective.
-
-
-
-
-
-Running User-Space Tools
-
-
- As mentioned earlier in the manual, several tools exist that enhance
- your development experience.
- These tools are aids in developing and debugging applications and images.
- You can run these user-space tools from within the Eclipse IDE through the
- YoctoTools menu.
-
-
-
- Once you pick a tool, you need to configure it for the remote target.
- Every tool needs to have the connection configured.
- You must select an existing TCF-based RSE connection to the remote target.
- If one does not exist, click New to create one.
-
-
-
- Here are some specifics about the remote tools:
-
- OProfile: Selecting this tool causes
- the oprofile-server on the remote target to launch on
- the local host machine.
- The oprofile-viewer must be installed on the local host machine and the
- oprofile-server must be installed on the remote target,
- respectively, in order to use.
- You must compile and install the oprofile-viewer from the source code
- on your local host machine.
- Furthermore, in order to convert the target's sample format data into a form that the
- host can use, you must have oprofile version 0.9.4 or
- greater installed on the host.
- You can locate both the viewer and server from
- .
- The oprofile-server is installed by default on
- the core-image-sato-sdk image.
- Lttng-ust: Selecting this tool runs
- usttrace on the remote target, transfers the output data back
- to the local host machine, and uses the lttng Eclipse plug-in to
- graphically display the output.
- For information on how to use lttng to trace an application, see
- .
- For Application, you must supply the absolute path name of the
- application to be traced by user mode lttng.
- For example, typing /path/to/foo triggers
- usttrace /path/to/foo on the remote target to trace the
- program /path/to/foo.
- Argument is passed to usttrace
- running on the remote target.
- Before you use the lttng-ust tool, you need to setup
- the lttng Eclipse plug-in and create a lttng
- project.
- Do the following:
-
- Follow these
- instructions
- to download and install the lttng parser library.
-
- Select Window -> Open Perspective -> Other
- and then select LTTng.
- Click OK to change the Eclipse perspective
- into the LTTng perspective.
- Create a new LTTng project by selecting
- File -> New -> Project.
- Choose LTTng -> LTTng Project.
- Click YoctoTools -> lttng-ust to start user mode
- lttng on the remote target.
-
- After the output data has been transferred from the remote target back to the local
- host machine, new traces will be imported into the selected LTTng project.
- Then you can go to the LTTng project, right click the imported
- trace, and set the trace type as the LTTng kernel trace.
- Finally, right click the imported trace and select Open
- to display the data graphically.
- PowerTOP: Selecting this tool runs
- powertop on the remote target machine and displays the results in a
- new view called powertop.
- Time to gather data(sec): is the time passed in seconds before data
- is gathered from the remote target for analysis.
- show pids in wakeups list: corresponds to the
- -p argument
- passed to powertop.
- LatencyTOP and Perf:
- latencytop identifies system latency, while
- perf monitors the system's
- performance counter registers.
- Selecting either of these tools causes an RSE terminal view to appear
- from which you can run the tools.
- Both tools refresh the entire screen to display results while they run.
-
-
-
-
-
- Customizing an Image Using a BitBake Commander Project and Hob
-
-
- Within Eclipse, you can create a Yocto BitBake Commander project,
- edit the metadata, and then use the
- Hob to build a customized
- image all within one IDE.
-
-
-
- Creating the Yocto BitBake Commander Project
-
-
- To create a Yocto BitBake Commander project, follow these steps:
-
- Select Window -> Open Perspective -> Other
- and then choose Bitbake Commander.
- Click OK to change the Eclipse perspective into the
- Bitbake Commander perspective.
- Select File -> New -> Project to create a new Yocto
- Bitbake Commander project.
- Choose Yocto Project Bitbake Commander -> New Yocto Project
- and click Next.
- Enter the Project Name and choose the Project Location.
- The Yocto project's metadata files will be put under the directory
- <project_location>/<project_name>.
- If that directory does not exist, you need to check
- the "Clone from Yocto Git Repository" box, which would execute a
- git clone command to get the project's metadata files.
-
- Select Finish to create the project.
-
-
-
-
-
- Editing the Metadata Files
-
-
- After you create the Yocto Bitbake Commander project, you can modify the metadata files
- by opening them in the project.
- When editing recipe files (.bb files), you can view BitBake
- variable values and information by hovering the mouse pointer over the variable name and
- waiting a few seconds.
-
-
-
- To edit the metadata, follow these steps:
-
- Select your Yocto Bitbake Commander project.
- Select File -> New -> Yocto BitBake Commander -> BitBake Recipe
- to open a new recipe wizard.
- Point to your source by filling in the "SRC_URL" field.
- For example, you can add a recipe to your
- source directory structure
- by defining "SRC_URL" as follows:
-
- ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
-
- Click "Populate" to calculate the archive md5, sha256,
- license checksum values and to auto-generate the recipe filename.
- Fill in the "Description" field.
- Be sure values for all required fields exist.
- Click Finish.
-
-
-
-
-
- Building and Customizing the Image
-
-
- To build and customize the image in Eclipse, follow these steps:
-
- Select your Yocto Bitbake Commander project.
- Select Project -> Launch HOB.
- Enter the build directory where you want to put your final images.
- Click OK to launch Hob.
- Use Hob to customize and build your own images.
- For information on Hob, see the
- Hob Project Page on the
- Yocto Project website.
-
-
-
-
-
-
diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml
index 04c47369f9..93737826b5 100644
--- a/documentation/adt-manual/adt-intro.xml
+++ b/documentation/adt-manual/adt-intro.xml
@@ -13,11 +13,13 @@
The Yocto Project provides an application development environment based on
- an Application Development Toolkit (ADT).
- This manual describes the ADT and how you can configure and install it.
- You will also learn how to customize the development packages installation,
- learn about the Eclipse Yocto Plug-in, and learn how to use command line
- development for both Autotools-based and Makefile-based projects.
+ an Application Development Toolkit (ADT) and the availability of stand-alone
+ cross-development toolchains and other tools.
+ This manual describes the ADT and how you can configure and install it,
+ how to access and use the cross-development toolchains, how to
+ customize the development packages installation,
+ how to use command line development for both Autotools-based and Makefile-based projects,
+ and an introduction to the Eclipse Yocto Plug-in.
@@ -88,6 +90,14 @@
remote profiling, tracing, collection of power data, collection of
latency data, and collection of performance data.
+
+
+ For information about the application development workflow that uses the Eclipse
+ IDE and for a detailed example of how to install and configure the Eclipse
+ Yocto Project Plug-in, see the
+ "Working Within Eclipse" section
+ of the Yocto Project Development Manual.
+
diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml
index c553e7cc08..285c347fae 100644
--- a/documentation/adt-manual/adt-manual.xml
+++ b/documentation/adt-manual/adt-manual.xml
@@ -85,8 +85,6 @@
-
-