Difference between revisions of "PDE/User Guide"
(→PDE API Tooling)
|Line 331:||Line 331:|
= Reference =
= Reference =
Revision as of 21:15, 27 July 2009
|Mailing List • Forums • IRC • mattermost|
|Open • Help Wanted • Bug Day|
|Browse Source • Project Set File|
- 1 Getting Started
- 2 Concepts
- 3 Tasks
- 3.1 PDE Build
- 3.2 PDE Build Advanced Topics
- 3.3 PDE Build Advanced Topics
- 3.4 PDE API Tooling
- 3.5 PDE UI
- 4 Reference
- 5 Tips and Tricks
The Plug-in Development Environment (PDE) provides tools to create, develop, test, debug, build and deploy Eclipse plug-ins, fragments, features, update sites and RCP products.
PDE also provides comprehensive OSGi tooling, which makes it an ideal environment for component programming, not just Eclipse plug-in development.
PDE is broken into three main components:
- UI - A rich set of models, tools and editors to develop plug-ins and OSGi bundles
- API Tooling - Tooling to assist API documentation and maintenence
- Build - Ant based tools and scripts to automate build processes
Discover the latest features in the What's New section.
PDE UI provides a editors, wizards, launchers, views and other tools to create a full featured environment to develop and deploy Eclipse plug-ins, fragments, features, update sites, RCP products and OSGi bundles.
Some of the PDE tools include:
- Form-Based Manifest Editors: Multi-page editors that centrally manage all manifest files of a plug-in or feature.
- RCP Tools: Wizards and a form-based editor that allow you to define, brand, test and export products to multiple platforms.
- 'New Project Creation Wizards: Create a new plug-in, fragment, feature, feature patch and update sites.
- Import Wizards: Import plug-ins and features from the file system.
- Export Wizards: Wizards that build, package and export plug-ins, fragments and products with a single click.
- Launchers: Test and debug Eclipse applications and OSGi bundles.
- Views: PDE provides views that help plug-in developers inspect different aspects of their development environment.
- Miscellaneous Tools: Wizards to externalize and clean up manifest files.
- Conversion Tools: Wizard to convert a plain Java project or plain JARs into a plug-in project.
- Integration with JDT: Plug-in manifest files participate in Java search and refactoring.
To get started, try out the following cheat sheets:
- Creating an Eclipse Plug-in
- Creating a Rich Client Application
PDE API Tooling
PDE API Tooling assists in the documentation and maintenance of APIs provided by plug-ins and OSGi bundles.
Some of the features include:
- Compatibility Analysis : Identify binary compatibility issues relative to a previous version of a plug-in.
- API Restriction Tags : Javadoc tags are provided to explicitly define restrictions associated with types and members.
- Version Number Validation: Identify invalid plug-in version numbers relative to a previous version of a plug-in.
@sinceTag Validation: Identify missing and invalid
@sincetags on types and members.
- API Leak Analysis : Identify API types and methods that leak non-API types.
- Quick Fixes : Quick fixes are provided to adjust plug-in versions and @since tags appropriately.
To get started, see the tasks:
PDE Build facilitates the automation of plug-in build processes. PDE Build produces Ant scripts based on development-time information provided by, for example, the plugin.xml and build.properties files. The generated Ant scripts, can fetch the relevant projects from a CVS repository, build jars, Javadoc, source zips, put everything together in a format ready to ship and send it out to a remote location (e.g., a local network or a downloads server).
To get started, see the following:
Extensions and Extension Points
A basic rule for building modular software systems is to avoid tight coupling between components. If components are tightly integrated, it becomes difficult to assemble the pieces into different configurations or to replace a component with a different implementation without causing a ripple of changes across the system.
Loose coupling in Eclipse is achieved partially through the mechanism of extensions and extension points. The simplest metaphor for describing extensions and extension points is electrical outlets. The outlet, or socket, is the extension point; the plug, or light bulb that connects to it, the extension. As with electric outlets, extension points come in a wide variety of shapes and sizes, and only the extensions that are designed for that particular extension point will fit.
When a plug-in wants to allow other plug-ins to extend or customize portions of its functionality, it will declare an extension point. The extension point declares a contract, typically a combination of XML markup and Java interfaces, that extensions must conform to. Plug-ins that want to connect to that extension point must implement that contract in their extension. The key attribute is that the plug-in being extended knows nothing about the plug-in that is connecting to it beyond the scope of that extension point contract. This allows plug-ins built by different individuals or companies to interact seamlessly, even without their knowing much about one another.
The Eclipse Platform has many applications of the extension and extension point concept. Some extensions are entirely declarative; that is, they contribute no code at all. For example, one extension point provides customized key bindings, and another defines custom file annotations, called markers; neither of these extension points requires any code on behalf of the extension.
Another category of extension points is for overriding the default behavior of a component. For example, the Java development tools include a code formatter but also supply an extension point for third-party code formatters to be plugged in. The resources plug-in has an extension point that allows certain plug-ins to replace the implementation of basic file operations, such as moving and deletion.
Yet another category of extension points is used to group related elements in the user interface. For example, extension points for providing views, editors, and wizards to the UI allow the base UI plug-in to group common features, such as putting all import wizards into a single dialog, and to define a consistent way of presenting UI contributions from a wide variety of other plug-ins.
A feature is used to package a group of plug-ins together into a single installable and updtable unit.
Features have a manifest that provides basic information about the feature and its content. Content may include plug-ins, fragments and any other files that are important for the feature. A feature can also include other features. The delivery format for a feature is a JAR, but each included plug-in will be provided as a separate JAR.
Once you have created your plug-ins and fragments you can create a new feature by creating a New Feature Project.
You can also create Feature Patches in PDE. A feature patch is developed in the same fashion as a normal feature, but is used to edit an existing feature rather than create a new one.
A fragment is used to replace or extend the functionality of an existing plug-in. A common use for fragments is to put environment (operating system, architecture, etc.) specific code into fragments. Depending on the environment the plug-in is installed in the base plug-in code along with the correct fragment can be installed. Fragments are also ideal for shipping features like language or maintenance packs that typically trail the initial products for a few months.
When a fragment is detected by the platform and its parent plug-in is found, the fragment's libraries, extensions and extension points are "merged" with those of the parent plug-in.
While this merging mechanism is good from a runtime point of view, developers need to view fragments as separate entities while working on them.
PDE provides full support for fragment development. Fragments can be viewed as "limited plug-ins". They have all of the capability of regular plug-ins but have no concept of life-cycle. Fragments have no top-level class with "startup" and "shutdown" methods.
To create a fragment use the New Fragment Project wizard. Editing fragments is very similar to editing plug-ins.
A plug-in is used to group your code into a modular, extendable and sharable unit.
Plug-ins are modular as each plug-in contains some portion of code. The plug-in specifies other plug-ins (or java packages) it requires to be available to run and it also specifies the set of java packages it provides. An Eclipse based program or product will contain multiple plug-ins, which can be added, replaced or removed to alter the functionality of the program.
Plug-ins are extendable using extensions and extension points. A plug-in can provide one or more extension points so other plug-ins can add to the functionality of the plug-in. A plug-in may also provide extensions to connect to other plug-ins.
Plug-ins are sharable. A plug-in can be exported as a directory or as a jar which can be added to other applications. Plug-ins can be grouped into features which can be distributed and installed into applications.
Eclipse plug-ins are based on OSGi bundles. OSGi is used to manage the plug-ins in an Eclipse application. A plug-in must contain a manifest file with valid OSGi headers for plug-in name and version. Extensions and extension points functionality added by Eclipse in addition to OSGi. To use extensions you must provide a plugin.xml file. PDE provides a full featured project and editor for creating and editing these files.
An Eclipse based product is a stand-alone program built with the Eclipse platform. A product may optionally be packaged and delivered as one or more features, which are simply groupings of plug-ins that are managed as a single entity by the Eclipse update mechanisms.
Products include all the code and plug-ins needed to run them. This includes a Java runtime environment (JRE) and the Eclipse platform code. The plug-in code, JRE, and Eclipse platform are typically installed with a product-specific installation program. Product providers are free to use any installation tool or program that is appropriate for their needs.
Once installed, the user launches the product and is presented with an Eclipse workbench configured specifically for the purpose supported by the product, such as web development, C++ program development, or any other purpose. The platform makes it easy to configure labels, about dialogs, graphics, and splash screens, so that the user has no concept of a platform workbench, but instead views the workbench as the main window of the product itself.
PDE provides a product configuration file and associated editor to make it easy to create products in the correct format.
The Target Platform refers to the plug-ins which your workspace will be built and run against. It describes the platform that you are developing for. When developing with PDE, the target platform is used to:
- Compile - Plug-ins in the workspace are built against the target platform so you do not have to have everything in your workspace
- Launch - When using PDE's launchers you can choose the set of plug-ins you want to launch. By default the Eclipse Application Launcher will start with all plug-ins in the target, but will use workspace plug-ins instead when available
- Calculate Dependencies - PDE assists you in finding the plug-ins your plug-ins was include/require to compile correctly by looking at what is available in the target platform
- State - An OSGi state is created for the target platform so it can be used by other tooling. The state can also be viewed in detail using the Target Platform State View
- Other Tools - Other PDE tools use the target platform to determine their options, such as the import wizards
Whereas the target platform refers to your currently active bundles, a Target Definition is a way of determining the plug-ins to add to the state. You can have multiple target definitions, but only one definition can be selected as the target platform.
The target platform and your target definitions are managed on the Target Platform Preference Page. This page lists all target definitions that PDE has access to and displays which definition is being used as your current target platform. Target definitions can be created and edited here using the Target Definition Content Wizard. To make for easier sharing among a development team, targets can also be created and edited in the workspace as xml files with the extension ".target". These files can be edited using the target definition editor and can be created using the New Target Definition Wizard.
By default PDE provides a default target platform which simply points to the plug-ins in your currently running Eclipse instance (often referred to as your host). For Eclipse plug-in developers this might be all you need. RCP developers must be more careful managing their target as adding dependencies increases the size and complexity of their application. When creating a new target definition for RCP, consider using the RCP template (available with or without source).
For up to the minute target troubleshooting help see the Target Definitions Wiki Page.
Update Sites are used to organize and export features so they can be installed into Eclipse applications.
To create an update site you must develop a site.xml file and build the site. PDE provides an editor and project for creating sites. A site will contain one or more features organized into categories.
When the site is built, the included features (along with all plug-ins part of those features) will be exported into an installable form. The exported plug-ins and features will be put into two folders "plugins" and "features". Two other files, "content.xml" and "artifacts.xml" will also be generated and contain metadata for the exported files that make installing easier. These files, along with "site.xml", collectively form an Eclipse update site. To make the update site available to others you must make all these files available in a shared directory or web site.
Automated building an RCP application from a product definition file
PDE Build comes with infrastructure to build a complete RCP application from a product configuration file. Most of the setup necessary for such a build can be done through a few modifications to the template build.properties provided in PDE build. The following section focuses on setting up a simple product build assuming that all plug-ins and features (both to build and pre-built) referenced by the product file are already locally available on disk.
The first step in setting up a build is to create the directory in which the build will take place. This directory will be referred to as the build directory and will contain the plug-ins and features to build as well as all the generated artifacts. Next, copy your plug-ins and features respectively into "plugins" and "features" subdirectories. Your product configuration file is expected to be in one of these plugins/features.
The second step in setting up a build is to copy the template build.properties file from org.eclipse.pde.build/templates/headless-build to a new directory which will be the build configuration directory (also referred to as the configuration directory). Edit the copied build.properties file and set the following properties:
- product: the location of your product configuration file in the form "/<plugin or feature id>/path/to/.product"
- baseLocation: the location of an eclipse install containing all the pre-built features and plug-ins that your product requires in features/ and plugins/ subdirectories. The RCP delta pack (it is * available from the eclipse download page) is mandatory as it includes the org.eclipse.platform.launchers feature which contains the launchers and root files necessary for a product.
- buildDirectory: the directory the build will take place in. Set this to the full path of the build directory created previously.
- configs: list the configurations for which you want your product to be built. You can uncomment the configuration(s) provided (be careful of the line continuations).
- archivePrefix: the name of the directory of your product once installed on disk.
Overview of the directory structure
Running the build
To run the build you will use the org.elipse.ant.core.antRunner application. When invoking eclipse with this application to perform a build you need to set two arguments on the command line:
- -buildfile </path/to/productBuild.xml>: This is the path to the productBuild.xml provided by pde build. It is located in the org.eclipse.pde.build/scripts/productBuild directory. This is the build file that drives the whole product build process.
- -Dbuilder=</path/to/configuration folder>: This is the path to the build configuration folder.
Run the antRunner application using the following command:
java -jar eclipseInstall>/plugins/org.eclipse.equinox.launcher_version.jar -application org.eclipse.ant.core.antRunner <br />-buildfile eclipseInstall/plugins/org.eclipse.pde.build_version/scripts/productBuild/productBuild.xml <br />-Dbuilder=path to the build configuration folder
Behind the scenes this setup will generate a feature containing the plugins or features specified in your product configuration file. This generated feature is then used to drive a normal feature based headless build. If you require more customization of the build, ie fetching from a repository, see the Advanced PDE Build topics for more information.
PDE Build Advanced Topics
PDE Build Advanced Topics
PDE API Tooling
Setting up API Tooling
Configure existing plug-ins
This section explains how to enable your existing plug-ins for API analysis.
Select the project you want to convert.
- Right-click and select PDE Tools > API Tooling Setup...
- Once the API Tooling Setup wizard is open, check that the project is selected.
- If your project contains a file component.xml, you can uncheck the checkbox to preserve it after conversion.
- Click Next if you want to preview the changes, or Finish otherwise.
- Your plug-in is now converted to use API tooling.
Configure a new plug-in
This section explains how to enable a new plug-ins for API analysis.
- Click on File>New>Project...
- Select Plug-in Development>Plug-in Project and click Next.
- Fill the first page as you would do for any other plug-in and click Next.
- Check the option Enable API Analysis.
- Complete your Plug-in setup
- Click Finish.
Setting up a baseline
Once your plug-in is converted to use API tooling, you need to set up a baseline in order to get the compatibility analysis performed for your plug-in.
To create an API baseline do the following:
- Open the Plug-in Development > API Baselines preference page.
- Select the Add Baseline... button to open the API baseline wizard.
- Give a meaningful name for your baseline
- Click Browse... and select the root folder of the Eclipse SDK you want to choose as your baseline
- Click OK in the folder dialog
- Once the baseline is initialized, click Finish
- Click OK and you are all set. If your workspace contains some existing projects, you will be prompted for a rebuild.
Filters can be used to remove known or expected API problems that cannot be readily corrected. Problem filters can be created easily using the Create API Problem Filter quickfix.
Using the quickfix let's see how we can add a new filter.
The Problems view
- Open the Problem view.
- Select an API Tooling problem.
- Use Ctrl + 1 to trigger the quickfix from the problem view.
- Select Finish to create the new filter.
Editing the resource
- Open the resource the API problem exists in.
- Use Ctrl + 1 on the corresponding problem.
- One of the quickfix proposals will be the creation of a problem filter for the corresponding problem.
- Select it and the problem filter is added for you.
Once the problem filter has been created the corresponding resource is rebuilt and the problem is removed from the Problems view and any open editors.
If you want to remove an existing API filter, do the following steps:
- Select the project that has an existing API filter.
- Right-click on the project and select Properties.
- Go to Plug-in Development > API Problem Filters
- From the list of existing filters, select the one you want to remove
- Select Remove.
- Select OK or Apply.
Changing API Tooling options
The options can be changed per project or per workspace.
- First you need to open the preference page. Do one of the following according to the desired scope:
- for the project scope, right-click a project and select Properties. Then go to Plug-in Development > API Errors/Warnings
- for the workspace scope, go to the Plug-in Development > API Errors/Warnings preference page.
- Select the tab for which you want to modify an option:
- API Use: for options related to API usage (unsupported tags, API restrictions, API leaks)
- API Compatibility: for options related to compatibility issues. They are sorted per type of element
- Version Management: for options related to invalid, missing, malformed @since tags or incorrect plug-in versions)
- Analysis Options - for general options
- All options of a page can be reset to the default values by clicking on Restore Defaults.
- Use the buttons insider the Set All As group to modify all options of the page to a specific value.
Comparing to an API Baseline
Any API tooling enabled project in your workspace can be compared to any one of the API baselines set up in your workspace. In addition to selecting projects to compare to a baseline you can also select (or multi-select) any of the following within an API tools enabled project:
- source folders
- package fragments
- compilation units
NOTE: all selections must be made from the Package Explorer because the compare wizard works only for Java elements.
To compare to an API baseline do the following:
- Select the elements to compare using the criteria mentioned above.
- Select the API baseline to compare to in the Compare Wizard
- Click Finish and you are all set. Any results from the compare will be shown in the API Tooling view.
Export and Install into the Running Host
PDE provides several tools for launching plug-ins and features in your workspace. The Eclipse Application Launcher can be used to create a second running instance of Eclipse that runs the code you have in your workspace. This is commonly referred to as self-hosting. Self-hosting is a powerful debugging and testing tool. However it is sometimes necessary for code to be tested in your host, your currently running Eclipse instance. To test code in the host, you need to export and install into the running Eclipse instance.
To export plug-ins and features and install them into the host Eclipse do the following:
- Develop your plug-ins and features in the workspace
- Open the export wizard, either File > Export... > Plug-in Development > Deployable plug-ins and fragments or File > Export... > Plug-in Development > Deployable features
- Select your plug-ins or features to export and install
- Select the last option on the Destination tab Install into host. Repository. Then choose a directory to create the repository in
- Hit Finish. The export operation will run followed by the installation operation.
- If the operations completed succesfully, you will be prompted to restart. Choose to restart now
Your plug-ins will be installed and running after the restart. You can see what has been installed using the Installation Details button on the About Dialog (available by going to Help > About Eclipse SDK)
Tips and Tricks
Creating a Rich Client Application
The Creating a Rich Client Application cheat sheet will guide you through the individual steps to create a plug-in, define a plug-in based product, customize a product, export a Rich Client Platform (RCP) application and define a feature-based product using the Plug-in Development Environment (PDE).
Creating an Eclipse Plug-in
The Creating an Eclipse Plug-in cheat sheet will guide you through the individual steps to create a plug-in, a plug-in extension, a feature and an update site using the Plug-in Development Environment (PDE). It will also demonstrate how to install and uninstall a feature using Install/Update.
To clean or not to clean
When you create a new runtime workbench launch configuration, PDE presets the Program Arguments on the launch configuration to include a -clean argument. This -clean argument clears all runtime-cached data in your runtime workbench from one invocation to the next to ensure that all the changes made in your host workbench, e.g. new Java packages were added to a plug-in project, etc., are picked up when you launch a runtime workbench.
This clearing of the cache may hinder performance if your target platform contains a large number of plug-ins.
Therefore, if you're in a situation where your target platform has a large number of plug-ins and you're at a stage where you are not actively adding/removing packages from your plug-in projects, you could remove the -clean argument from the launch configuration to improve startup time.
For a quick start, PDE provides several template plug-ins that will generate a plug-in with one or more fully-working extensions. In addition, if at any point, you would like to add a new extension from the template list (without having to generate a plug-in), you could access these extension templates directly from the manifest editor. From the Extensions page of the editor, click Add.... In the wizard that comes up, select Extension Templates in the left pane and choose the template of choice in the right pane.
If you have ever looked at the list of plug-ins that your plug-in depends on and wondered why your plug-in needs a particular plug-in X, now you can easily find out why. The Compute Dependency Extent operation found on the context menu in several contexts (including manifest file Dependencies page and Dependencies view) performs a combined Java and plug-in search to find all Java types and extension points provided by plug-in X which are referenced by your plug-in. The results will be displayed in the Search view. When a type is selected in the Search results view, the References in MyPlugIn action in the context menu searches for the places in the plug-in where the selected type is referenced.
If the search returns 0 results, you should definitely remove plug-in X from your list of dependencies, as it is not being used at all, and it would just slow class loading.
The Compute Dependency Extent is also useful to check if you are using internal (non-API) classes from plug-in X, which might not be desirable.
Extending the Java Search Scope
Java Search is limited to projects in your workspace and external jars that these projects reference. If you would like to add more libraries from external plug-ins into the search: open the Plug-ins View, select a plug-in and choose Add to Java Search from the context menu. This is handy for remaining aware of other plug-ins that depend on ones you're working on.