About This Content
+ +June 2, 2006
+License
+ +The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise +indicated below, the Content is provided to you under the terms and conditions of the +Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available +at http://www.eclipse.org/legal/epl-v10.html. +For purposes of the EPL, "Program" will mean the Content.
+ +If you did not receive this Content directly from the Eclipse Foundation, the Content is +being redistributed by another party ("Redistributor") and different terms and conditions may +apply to your use of any object code in the Content. Check the Redistributor's license that was +provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise +indicated below, the terms and conditions of the EPL still apply to any source code in the Content +and such source code may be obtained at http://www.eclipse.org.
+ + + diff --git a/org.eclipse.pde.doc.user/apache_style.css b/org.eclipse.pde.doc.user/apache_style.css new file mode 100644 index 0000000000..da4400a490 --- /dev/null +++ b/org.eclipse.pde.doc.user/apache_style.css @@ -0,0 +1,70 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ +h2 { + font-size: 200%; + background-color: #ffffff; +} + +h3 { + font-size: 130%; + color: #ffffff; + background-color: #525D76; +} + +h4 { + color: #ffffff; + background-color: #828DA6; +} + +td { + background-color: #eeeeee; + color: #000000; +} + +/* first row */ +table tr:first-child td { + background-color: #cccccc; + color: #000000; +} + +/* or th as first row */ +table th { + background-color: #cccccc; + color: #000000; +} + +pre { + background-color: #efefef; +} + +/* code snippets in examples and tutorials */ +.code { + background: #EFEFEF; + margin-top: +} + +/* highlight console output */ +.output { + color: #FFFFFF; + background: #837A67; +} + +div.c4 {text-align: left;} +pre.c3 {margin-left: 40px} +span.c2 {color: #0000FF} +span.c1 {color: #008000} \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/api_contexts.xml b/org.eclipse.pde.doc.user/api_contexts.xml new file mode 100644 index 0000000000..d20303f55e --- /dev/null +++ b/org.eclipse.pde.doc.user/api_contexts.xml @@ -0,0 +1,135 @@ + + + +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.
+ +Related references
+Extensions (Plug-in Editor)+Extension Points (Plug-in Editor) + +
Related concepts
+Plug-in + + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/concepts/feature.htm b/org.eclipse.pde.doc.user/concepts/feature.htm new file mode 100644 index 0000000000..66d6f43895 --- /dev/null +++ b/org.eclipse.pde.doc.user/concepts/feature.htm @@ -0,0 +1,39 @@ + + + + + +Feature
+ +A Feature is used to package a group of plug-ins together into a single installable and updatable 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.
+ +Related references
+Feature Editor+New Feature Project
+New Feature Patch Project + +
Related concepts
+Plug-in+Fragment
+Product
+Update Site + + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/concepts/fragment.htm b/org.eclipse.pde.doc.user/concepts/fragment.htm new file mode 100644 index 0000000000..4e23d6e947 --- /dev/null +++ b/org.eclipse.pde.doc.user/concepts/fragment.htm @@ -0,0 +1,47 @@ + + + + + +
Fragment
+ +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.
+ +Related references
+Plug-in Editor+New Fragment + +
Related concepts
+Plug-in+Feature
+ + + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/concepts/plugin.htm b/org.eclipse.pde.doc.user/concepts/plugin.htm new file mode 100644 index 0000000000..81da9fe5fc --- /dev/null +++ b/org.eclipse.pde.doc.user/concepts/plugin.htm @@ -0,0 +1,36 @@ + + + + + +
Plug-in
+ +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.
+ +Eclipse plug-ins can also be packaged as a Java modular project ( Java 9 or later).
+ +Related references
+Plug-in Editor+New Plug-in Project + +
Related concepts
+Fragment+Feature
+ + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/concepts/product.htm b/org.eclipse.pde.doc.user/concepts/product.htm new file mode 100644 index 0000000000..e205fa8f09 --- /dev/null +++ b/org.eclipse.pde.doc.user/concepts/product.htm @@ -0,0 +1,48 @@ + + + + + +
Product
+ +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.
+ +Related references
+Product Editor+New Product Configuration + +
Related concepts
+Plug-in+Fragment
+Feature
+ + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/concepts/target.htm b/org.eclipse.pde.doc.user/concepts/target.htm new file mode 100755 index 0000000000..cd984b2df5 --- /dev/null +++ b/org.eclipse.pde.doc.user/concepts/target.htm @@ -0,0 +1,40 @@ + + + + + +
Target Platform
+ +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.
+ +Related references
+Target Platform Preference Page+Edit Target Definition Wizard
+Target Editor
+Eclipse Application Launcher
+Eclipse Application Launcher Plug-ins Tab + + + diff --git a/org.eclipse.pde.doc.user/concepts/update_site.htm b/org.eclipse.pde.doc.user/concepts/update_site.htm new file mode 100644 index 0000000000..86c9dee11e --- /dev/null +++ b/org.eclipse.pde.doc.user/concepts/update_site.htm @@ -0,0 +1,41 @@ + + + + + +
Update Site
+ +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 "plug-ins" 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.
+ +Related references
+Site Editor+New Update Site Project + +
Related concepts
+Feature+Plug-in
+ + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/contexts_PDE.xml b/org.eclipse.pde.doc.user/contexts_PDE.xml new file mode 100644 index 0000000000..71d4c57b75 --- /dev/null +++ b/org.eclipse.pde.doc.user/contexts_PDE.xml @@ -0,0 +1,1062 @@ + + +
Plug-in Development Environment Overview
+ +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 Tools - Tooling to assist API documentation and maintenance +
- Build - Ant based tools and scripts to automate build processes +
Discover the latest features in the What's New section.
+ + +PDE UI
+ +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:
+ + + +API Tools
+ +API Tools 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. +
- Javadoc
@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:
+-
+
- Setting up API Tools +
- Setting up a baseline +
- Changing options +
- Creating filters +
- Removing filters +
PDE Build
+ +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:
+-
+
- Automated building of RCP applications from product configurations +
- Automated building of features +
- Automated building of plug-ins +
- Generating Ant scripts from PDE +
- Generating Ant scripts from scripts +
- Building p2 repositories and products. +
- Builder Configuration Properties +
- Feature and Plug-in build properties +
Category Editor
+ +The Category Editor is a single page editor used to modify category definition files. These files provide a set of categories and specify features that belong to each category. When exporting, a category definition file can be provided so that the exported metadata adds the exported features to the correct category.
+ +Managing the Categories
+Using the site editor, you can create Categories and add features to it. A feature +can appear in more than one category.
+
To publish categories you can specify the category file when exporting a feature.
+ +Related references
+New Category Definition File+Feature Export + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/composite_cs_editor/editor.htm b/org.eclipse.pde.doc.user/guide/tools/editors/composite_cs_editor/editor.htm new file mode 100644 index 0000000000..164109d43f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/composite_cs_editor/editor.htm @@ -0,0 +1,85 @@ + + + + + +
Composite Cheat Sheet Editor
+ +About Cheat Sheets
+ ++ In general, cheat sheets help guide users through a complex set of instructions. + There are two types of cheat sheets: simple and composite. + Composite cheat sheets are used to organize and + present tasks represented by simple cheat sheets to achieve a larger goal. +
+ ++ You can view and run cheat sheets using the Cheat Sheet View. + To open a cheat sheet in this view, click Help > Cheat Sheets... +
+ +About This Editor
+ ++ The Composite Cheat Sheet Editor allows you to compose composite + cheat sheets and preview them in the Cheat Sheet View. + This editor also allows you to create simple cheat sheets on the fly. +
+ +Editor Pages
+ ++ This editor is comprised of the following pages: +
+ +-
+
- + Composite Cheat Sheet Page + +
Global Editor Actions
+ ++ This editor provides the following global actions: +
+ +-
+
- + Register Cheat Sheet Wizard + +
Relevant Links
+ +-
+
- Cheat sheet example:
+
+
Creating an Eclipse Plug-in
+
+
+ - + Cheat sheet documentation: + Cheat Sheets + +
- + Simple Cheat Sheet Editor + +
- + New Cheat Sheet Wizard + +
- + + Recommended Work Flow for Cheat Sheet Development + +
Composite Cheat Sheet Page
+ +About This Page
+ ++ This form page allows you to edit the structure, order and properties of cheat sheet elements. +
++ The structure and order of cheat sheet elements are edited in + the Content section. + This section occupies the entire left-hand portion of the editor area. +
++ The properties of cheat sheet elements are edited in the Definition sections. + These sections are activated in the right-hand portion of the editor area depending + on the type of cheat sheet element selected in the Content section. +
+ +Page Sections
+ ++ This page is comprised of the following sections: +
+ +-
+
- + Content Section + +
- + Title Section + +
- + Group Section + +
- + Task Section + +
- + Enclosing Text Section + +
Content Section
+ ++ This section allows you to do the following: +
+ +-
+
- + Visualize and edit the structure and order of the cheat sheet's + elements. + +
- + Activate the corresponding Definition section used to edit the + properties of a selected cheat sheet element. + +
- + Preview and test the edited cheat sheet within the + Cheat Sheet view. + +
+ This section is directly accessible through the Cheat Sheet form page. +
+ +Content Section Fields
+ ++ Use the cheat sheet element viewer field to do the following: +
+ +-
+
- + Visualize the structure and order of the cheat sheet's + title, groups and tasks + as they appear in the Cheat Sheet view. + +
- + Edit the structure and order of the cheat sheet's groups and tasks. + +
- + Activate the corresponding Definition section used to edit the + properties of a selected title, group or task. + +
+ This viewer contains the following nodes: +
+ +-
+
-
+
+ - Select the Root node, to activate the title Definition section.
+
+ -
+
+ - Select the Group node, to activate the group Definition section.
+
+ -
+
+ - Select the Task node, to activate the task Definition section.
+
+
+ 
+
Content Section Actions
+ ++ Click the Add Task button to add a new task to the + cheat sheet. + This action is available when a group or task node is selected. + If a task node is selected, the new task will be added + as the last child node of the task's parent group. + If a group node is selected, the new task will be added + as the last child node of that group. +
+ ++ Click the Add Group button to add a new group to the + cheat sheet. + This action is available when a group or task node is selected. + If a task node is selected, the new group will be added + as the last child node of the task's parent group. + If a group node is selected, the new group will be added + as the last child node of that group. + Note: In order to maintain cheat sheet validity, a new + group requires at least one child node. +
+ ++ Click the Remove button to remove a group or task. + This action is available when any of following nodes are selected: + task, group. + Note: In order to maintain cheat sheet validity, + neither the root node nor its immediate child group can be removed. +
+ ++ Click the Up button to move a group or task + up one position in order above their respective siblings. + This action is available when a group or task node is selected. +
+ ++ Click the Down button to move a group or task + down one position in order below their respective siblings. + This action is available when a group or task node is selected. +
+ ++ Click the Preview button to preview and test the saved or unsaved + contents of the edited cheat sheet in the Cheat Sheet view. + This convenient action allows you to observe how the edited cheat sheet + actually appears and operates within its deployed environment without having to + register the cheat sheet and launch another Eclipse runtime instance. +
+ + +Title Section
+ ++ This Definition section allows you to edit the title of the cheat sheet. + It is activated by selecting the root node in the Content section. +
+ +
+ 
+
Title Section Fields
+ ++ Edit the Name field to specify the cheat sheet title. +
+ + +Group Section
+ + ++ This Definition section allows you to edit the properties of a group. + It is activated by selecting a group node in the Content section. +
+ +
+ 
+
Group Section Fields
+ ++ Edit the Name field to specify the title of the group. +
+ ++ Select a value from the Type field to change + how the group is completed within the Cheat Sheet + view. The following selections are available: +
+ +-
+
- + Set: The group is complete when all of its children are completed. + +
- + Sequence: The group is complete when all of its children are completed in order. + +
- + Choice: The group is complete when any one of its children are completed. + +
+ Check the This group is optional field to make the + completion of the group and all of its child tasks optional + in the Cheat Sheet view. + A non-optional group includes a Go To 'Task' + action in the Cheat Sheet view to go to the group's first + child task. + An optional group includes a Skip this group of tasks + action in the Cheat Sheet view to skip the group and + all of its child tasks. +
+ + +Task Section
+ ++ This Definition section allows you to edit the properties of a task + and create simple cheat sheets on the fly. + It is activated by selecting a task node in the Content section. +
+ +
+ 
+
Task Section Fields
+ ++ Edit the Name field to specify the title of the task. +
+ ++ Edit the Path field to specify the relative path from the composite + cheat sheet file being edited to an existing simple cheat sheet file. + The use of an absolute path to an existing simple cheat sheet file is forbidden. + Also, the simple cheat sheet file must be contained within the same plug-in + project as the composite cheat sheet file being edited. + Forward slashes ('/') are used to separate file segments on all platforms. +
+ ++ Check the This task is optional field to make the + completion of the task optional in the Cheat Sheet view. + A non-optional task includes a Start working on this task + action in the Cheat Sheet view to go to the + simple cheat sheet referred to by the task. + An optional task includes a Skip this task + action in the Cheat Sheet view to skip the task. +
+ +Task Section Actions
+ ++ If the relative path specified in the Path + field refers to an existing simple cheat sheet file, clicking on the + Path hyperlink opens that cheat sheet in the + Simple Cheat Sheet Editor. + If the relative path specified in the Path + field refers to a non-existing simple cheat sheet file, clicking + on the Path hyperlink opens a streamlined + version of the New Cheat Sheet Wizard. + This version of the wizard can only create simple cheat sheets. + In the wizard, the File name field is automatically populated + with the simple cheat sheet file name from the Path + field (if specified). +
+ ++ Click the Browse button to open the + Cheat Sheet Selection dialog in order to select + an existing simple cheat sheet file. + The dialog presents a hierarchical view of all simple cheat + sheet files contained within the plug-in + project that contains the composite cheat sheet file being edited. + After a selection is made, the relative path + from the composite cheat sheet file to the + selected simple cheat sheet file is automatically computed and + entered into the Path field. +
+ +
+ 
+
Enclosing Text Section
+ ++ This section allows you to do the following: +
+ +-
+
- + Specify an introduction for a group or task. + +
- + Specify a conclusion for a group or task. + +
+ This section is accessible by selecting a group or task node + in the Content section. +
+ +
+ 
+
Enclosing Text Section Fields
+ ++ Edit the Introduction field to specify an introduction for a group or task. + The text may be formatted using valid Form Text Mark-up. + For instance, to bold text, enclose text with HTML-style bold tags: <b></b>. +
+ ++ Edit the Conclusion field to specify a conclusion for a group or task. + The text may be formatted using valid Form Text Mark-up. + For instance, to break text, use HTML-style break tags: <br/>. +
+ +Relevant Links
+ +-
+
- + Composite Cheat Sheet Editor + +
- + Simple Cheat Sheet Editor + +
- + New Cheat Sheet Wizard + +
- + + Form Text Mark-up + + +
Context Help Editor
+ ++Context-sensitive help is a mechanism that enables linking a user interface part with a specific help topic. When the user activates the associated user interface part, the help page is displayed in the dynamic help area. The user interface and the help pages are associated with each other in two ways: a static XML file or a dynamic context provider. To associate pages statically, a context help xml file must be created. The context help editor assists in the creation of these pages. +
++The Definition page of the editor provides a graphical view of the xml file, separated into two columns. The one on the left is titled Context Help and displays the xml elements in a tree format along with actions to add, move and remove them. The other column provides more detailed information about the element selected in the left column and enables editing of the details. +
++The Source page of the editor provides a textual view of the xml file. The xml can be edited directly and changes, if valid, will be reflected on the graphical Definition page. +
+-
+
- + Adding new help contexts + +
- + Adding help topics and commands + +
- + Remove, Up, Down commands + +
- + Registering the context help file + +
Adding new help contexts
+ +
+
+
+To add a new context, click the Add Context button. This will add a new context entry to the xml and it will be displayed in the tree on the Definition page. The new context will be selected, opening a detail section in the right column of the editor. In this detail section you can provide more detailed information about the context including: +
+-
+
- Help Context ID: ID that is passed to the UI element to associate the help +
- Description: Text that will be displayed to the user in the dynamic help to explain the basic function of the selected UI element. +
- Custom Page Title: By default the dynamic help displays the name of the selected UI element as the help title, entering text here will override the default. +
Adding help topics and commands
+ +Adding a context to the file will provide dynamic help with a basic description to display to the user. Typically you will want to provide additional links to related topics in the help system. To do this you must add topics and commands to the xml file. + +
+
+
+By clicking on the Add Topic button, you will add a new topic entry to the xml under one of the help contexts. A topic will appear to the user as a link. Once a new topic is created, you can select it to open the Topic Details section on the right column of the Definition page. In the detail section you can change the label that will be displayed to the user and the location of the file that will be linked. In most cases, the linked file will be an html page in the help system. You can use the Browse... button to search for a file to link. +
+ ++In addition to topics, you may also want to add a command. A command has the same appearance to the user as a topic. However, when the link is activated, a code command is executed instead of a file being opened. Commands can be used to open preference pages and execute other actions. +
+
+
+
+Clicking the Add Command button to add a new command. You can edit the details of commands in the same way that you edit topics. +
+ + +Remove, up, down Commands
++There are three additional buttons on the Definition page, which enable manipulating with the items order on the context list or with deleting the items. +
+
+
+
+These buttons are: +
+-
+
- Remove: Removes an item from the xml file +
- Up: Moves the selected items upwards one place in the tree +
- Down: Moves the selected items downwards one place in the in tree +
Registering the context help file
+ +For Eclipse to recognize the context help xml file as being a source for the dynamic help system, it must be registered via the org.eclipse.help.contexts extension point. The editor provides a way to register the context help file automatically. In the top righthand corner of the editor, there is a link called "Register this context help file". Clicking on this link will add the correct entry to the plugin.xml file. + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/dependencies.htm b/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/dependencies.htm new file mode 100644 index 0000000000..00905e44e9 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/dependencies.htm @@ -0,0 +1,36 @@ + + + + + +Feature Dependencies
+The Dependencies page lists all Required Features and Plug-ins that must be present in the product before the feature can be installed. If any of these pre-requisites are missing, the feature will not be installed.
+
The requirement can be based solely on plug-in IDs, or further constrained using expected versions and match rules.
+
Version to match: Optional version specification.
+Match Rule: Optional matching rule. Valid values and processing are as follows:
+
-
+
- If the 'Version to match' attribute is not specified, the 'Match Rule' attribute + (if specified) is ignored. +
- Equivalent - The dependency version must be at least at +the version specified, or at a higher service level (major and minor version +levels must equal the specified version). +
- Compatible - The dependency version must be at least at +the version specified, or at a higher service level or minor level (major +version level must equal the specified version). +
- Perfect - The dependency version must match exactly the +specified version. +
- Greater or Equal - The dependency version must be at least +at the version specified, or at a higher service, minor or major level. +
Feature Manifest Editor
+PDE provides a form-based multi-page feature manifest editor that manages and edits the feature.xml file.
+For details on the individual editor pages, refer to the following documents:
+-
+
- Feature Overview +
- Feature Information +
- Included Plug-ins +
- Included Features +
- Feature Dependencies +
- Feature Installation +
Included Features
+The Included Features section references all features nested inside your feature and their associated properties.
+ +Feature List
+The Included Features list enumerates all the features that are directly nested in your feature.
+
When your feature is built, all of its included features are recursively built and packaged as well.
+ +Included Feature Details
+
An included feature may be marked as optional using the The feature is optional option. Users may not choose to install optional features. However, if users do choose to install optional features, they may safely disable them later on. Please note that a missing optional feature is not treated as an error.
+An included feature can be updated by patches. By default, the installer searches for updates to an included feature at the update site for the parent feature; but, this setting can be overridden.
+If an included feature contains platform-specific code or resources, then environment conditions should be specified and associated with that feature.
+ + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/information.htm b/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/information.htm new file mode 100644 index 0000000000..ea2a83c16a --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/information.htm @@ -0,0 +1,41 @@ + + + + + +Feature Information
+The main purpose of the Feature Information page is to specify information that is required to install the feature.
+ +Feature Description
+A Feature Description is a brief component description.
+
Typically, a description is plain text and intended to be translated. Alternatively, you can provide the description in HTML format and point to it via a URL. The URL can be specified as absolute or relative. If a relative URL is specified, it is assumed to be relative to (and packaged in) the feature archive.
+ +Copyright Notice
+The feature Copyright Notice is typically provided as plain text and is intended to be translated.
+
Alternatively, you can provide the copyright notice in HTML format and point to it via a URL. The URL can be specified as absolute or relative. If a relative URL is specified, it is assumed to be relative to (and packaged in) the feature archive.
+ +License Agreement
+The License Agreement is a feature click-through license. It is typically simple text and is intended to be translated.
+The license is displayed in a standard dialog with Accept and Reject actions during the download and installation process.
+
Note that a click-through license must be specified for any feature that will be selected for installation or update within Eclipse. +When using nested features, only the nesting parent (i.e. the feature selected for installation or update) must have click-through license Text defined.
+Please note that the license text is required even if the Optional URL attribute is specified.
+ +Sites to Visit
+Sites to Visit specify the name and URL of sites to search for new features.
+
In general, a vendor can use Sites to Visit to reference its own site(s), or partner site(s) that offer complementary features.
+This data is simply used as a way to distribute new site URLs to the clients. Sites that belong to root features (at the top of the hierarchy) typically appear as Available Software Sites within the install wizard.
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/installation.htm b/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/installation.htm new file mode 100644 index 0000000000..fea0122b03 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/installation.htm @@ -0,0 +1,18 @@ + + + + + +Feature Installation
+The Installation page contains information that was used by the legacy Eclipse Update +Manager prior to Eclipse 3.4. The features on this page should be avoided when using newer versions of Eclipse. +
+ + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/overview.htm b/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/overview.htm new file mode 100644 index 0000000000..f2eab486b4 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/overview.htm @@ -0,0 +1,35 @@ + + + + + +Feature Overview
+The Overview page serves a dual purpose:
+-
+
- It contains two main sections that define important properties of the feature: General Information and Supported Environments. +
- It functions as a quick reference on how to define, export and publish a feature by providing the Feature Content, Exporting and Publishing sections. These sections provide hyperlinks that, when clicked, navigate to other pages or invoke commands. +
General Information
+
An ID is mandatory and must comply with the specifications.
+A Version is mandatory and must be of the form major.minor.micro.qualifier (e.g. 1.3.0).
+A Name is the translatable presentation name of the feature. This field is required.
+A Vendor is the translatable name of the feature vendor. This field is optional.
+A Branding Plug-in stores branding information for primary features. If not explicitly set, Eclipse will assume that the branding plug-in has the same identifier as the feature.
+The Update Site URL denotes a URL that is used by the installer when searching for feature updates.
+The Update Site Name is the human-readable label of the referenced update site.
+Supported Environments
+By default, your feature is treated as universally portable. You can add constraints by providing supported Operating Systems, Window Systems, Languages and/or System Architectures. This information will be used to ensure that your feature is not installed or shown in the context that does not match these constraints.
+
Included Plug-ins
+The Plug-ins and Fragments page lists all the plug-ins and fragments that should be packaged in the feature and specifies their properties.
+ +Plug-in List
+The Plug-ins and Fragments list enumerates all the plug-ins and fragments that are included directly in the feature.
+
Press the Add... button to browse the list of available plug-ins to add to the list.
+The preferred versioning scheme for referenced plug-ins is to give them a 0.0.0 version. This is a special value that will be replaced by the actual plug-in version when the feature is exported. This option is especially convenient when plug-in versions contain a qualifier segment.
+ +Plug-in Details
+Plug-in Details are used as guidelines to determine what, when and how to install the plug-ins included by a feature.
+
The Download Size and Installation Size are optional hints specified to enable useful user feedback about the feature being installed.
+The Unpack the plug-in archive after installation option determines whether a plug-in is to be unpacked (i.e. flattened) or left in a JAR after installation.
+If a plug-in or fragment contains platform-specific code, then environment conditions should be specified and associated with that plug-in or fragment.
+ + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/access_rules.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/access_rules.htm new file mode 100644 index 0000000000..07c41903cd --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/access_rules.htm @@ -0,0 +1,289 @@ + + + + + + + ++ Access Rules +
++ The Eclipse 3.1 runtime gives the plug-in developer the + option to control plug-in code visibility to downstream + plug-ins on a per-package basis. +
+ ++ A package may be classified as one of the following: +
+-
+
- Accessible + +
- Forbidden + +
- Internal + +
- Internal with friends + + +
+ PDE translates these runtime visibility rules into compiler + access restriction rules at compile time. As a result, a + violation of a visibility rule is flagged by the compiler as + a warning or an error - depending on the severity of that + violation. +
++ With this type of support at compile time, one is never + caught by surprise by runtime class loading errors and is + always aware of internal type references. +
++ Accessible Packages +
+ ++ Accessible packages are visible to downstream plug-ins + unconditionally. While API packages must clearly + fall in this category, it is completely up to the developer + to decide what other packages exported by the plug-in ought + to be given this level of visibility. +
++ In order to declare a package as accessible, you must list it + in the Exported Packages section on the Runtime + of the plug-in manifest editor and leave the default + visibility setting as-is. +
+ +
+ 
+
+ +
++ Forbidden Packages +
+ ++ You can hide a package from downstream plug-ins at all times + by excluding it from the list in the Exported + Packages section on the Runtime page of the + plug-in manifest editor. +
++ References to types from a forbidden package result + in class loading errors at runtime. +
+ ++ To avoid such unpleasant situations: +
+-
+
- The compiler will flag references to forbidden packages + with an error. + +
- Types from forbidden packages are NOT available as + proposals in the content assist. + +
+ + Notes: +
+-
+
- All plug-ins in the Eclipse SDK enumerate all their + packages in the Exported Packages section; + therefore, none of the packages in the SDK have forbidden + access. + +
- The severity level for forbidden references is set on the
+
+
+
+ Java > Compiler > Errors/Warnings >
+ Deprecated and restricted API preference page.
+
+ It is strongly recommended that the severity of a + forbidden reference is kept at error. +
+
+
+
+ 
+
+ Internal Packages +
++ Internal packages are packages that are not intended for use + by downstream plug-ins. These packages are + visible to downstream plug-ins by + + default. +
++ Internal packages are hidden from downstream plug-ins only + when Eclipse is launched in strict + mode (i.e. when you launch with the + -Dosgi.resolverMode=strict VM argument). +
++ + Internal packages must be listed in the Exported + Packages section on the Runtime page of the + plug-in manifest editor with the hidden option + selected. +
+
+ 
+
+ Two measures are taken to discourage downstream plug-ins from + referencing internal packages: +
+-
+
- The compiler flags references to internal packages with a + warning. + +
+ 
+
+
-
+
- Types from discouraged packages are available as content + assist proposals; but, with a lower priority. + +
+
+
+
+ The severity level for discouraged references can be set on
+ the
+
+ Java > Compiler > Errors/Warnings >
+ Deprecated and restricted API preference page.
+
+
+
+ Internal packages with friends +
++ It is important for a plug-in to be able to grant full access + to its internal packages to designated "friend" plug-ins. For + instance, the PDE code is split across multiple plug-ins, and + the org.eclipse.pde.ui plug-in should have full + access to org.eclipse.pde.core's internal packages. +
+ ++ In the example below, the the org.eclipse.pde.ui + friend plug-in has full access to the + org.eclipse.pde.internal.core.bundle package from + the org.eclipse.pde.core plug-in. +
+
+
+ 
+
+ The friends are free to reference any type from the + org.eclipse.pde.internal.core.bundle package with + the compiler's blessing. +
++ On the other hand, if any other plug-in references a type + from the org.eclipse.pde.internal.core.bundle + + package, the compiler flags the reference as a discouraged + reference as described in the previous section. +
++ How to enable access restrictions +
++ To take advantage of the PDE access restriction support, the + only requirement is that the plug-ins in question contain an + OSGi bundle MANIFEST.MF. PDE will take care of the + rest including the management of the plug-in classpath. +
++ + If the plug-in does not contain a MANIFEST.MF file, + that file can be created as follows: +
+-
+
- Open the plugin.xml in the plug-in manifest + editor. + +
- In the Plug-in Content section of the + Overview page, click on the 'create + an OSGi bundle manifest' link. + + +
+ 
+
+ Inspecting access rules +
++ You can inspect the access restriction rules imposed on each + classpath entry by PDE on the Java Build + Path property page of your plug-in project. +
+ +
+ 
+
Related references
+Plug-in Editor+Overview Page
+Dependencies Page
+Runtime Page
+Extensions Page
+Extension Points Page
+Build Page + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/build.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/build.htm new file mode 100644 index 0000000000..fe45837cee --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/build.htm @@ -0,0 +1,45 @@ + + + + + +
Plug-in Build
+The Build page contains all the information needed to build, package and export the plug-in. Although it appears as a page in the plug-in manifest editor, changes made to it are written by PDE to the plug-in's build.properties file. The build.properties file solely guides the build process.
+ +Custom Build
+The Custom Build option prevents the build.xml file from being overwritten with a generated build file. Use this option when +the plug-in provides a custom build.xml that is being manually updated.
+ +Runtime Information
+The Runtime Information section lists all the libraries that you want to build. For each library, you must list the source folder(s) that will be compiled into the library.
+
If your plug-in declares more than one library, order them correctly using the Up and Down button. This will ensure that they get compiled in the correct order.
+ +Binary and Source Builds
+
The Binary Build section is where you select all the files and folders that will make it into the packaged plug-in.
+The Source Build section has a specialized purpose and is not commonly used or needed by the general population. It is only needed when you need to ship source in separate plug-ins and features rather than in binary plug-ins. See the org.eclipse.pde.core.source extension point for details.
Extra Classpath Entries
+If you need extra libraries on the build path for your source code to compile, you can add these required JARs in the Extra Classpath Entries section.
+
Please note that this section should be used to add libraries that are not required to be on the plug-in runtime classpath.
+ +Related references
+Plug-in Editor+Overview Page
+Dependencies Page
+Runtime Page
+Extensions Page
+Extension Points Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/dependencies.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/dependencies.htm new file mode 100644 index 0000000000..ec4abdd4e0 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/dependencies.htm @@ -0,0 +1,60 @@ + + + + + +
Plug-in Dependencies
+The Dependencies page shows the dependencies that your plug-in has on other plug-ins. On this page, you must list all plug-ins that contribute code to your plug-in project and that are required to be on your project's classpath in order to compile. When you modify the list of dependencies and save the file, PDE will automatically update your classpath.
+ +Required Plug-ins
+The Required Plug-ins section specifies your plug-in project's dependencies on other plug-ins by explicitly enumerating these plug-ins. Your plug-in will not resolve or run at runtime if any of your plug-in dependencies are missing or unresolved.
+
Press the Add... button to browse the list of all plug-ins that your plug-in may make a dependency on.
+The order of the plug-ins in the list is important because it dictates the class loading order at runtime; therefore, use the Up and Down buttons to organize the list as appropriate.
+You can set several properties on each plug-in dependency by selecting a plug-in and clicking the Properties button:
+-
+
- You can make a plug-in dependency optional by selecting the Optional option. When this option is enabled, it indicates to the runtime that your plug-in should run even if an optional plug-in dependency is missing or not resolved. +
- You can select the Re-export this dependency option to re-export your dependency in order to make it automatically visible to any downstream plug-in that require it. Please note that you should only re-export a given plug-in dependency only if your plug-in exposes one ore more API's from that dependency. +
- You can also specify the Minimum Version and Maximum Version of the plug-in dependency. +
Imported Packages
+The Eclipse runtime provides the flexibility of specifying a dependency on a package without explicitly identifying its originating plug-in. These packages are enumerated in the Imported Packages section.
+
Press the Add... button to browse the list of packages available to your plug-in for importing. PDE filters out packages contributed by plug-ins that are already on your plug-in classpath.
+You can set several properties on each package dependency:
+-
+
- You can make the dependency optional by selecting the Optional option. When this option is enabled, this indicates to the runtime that your plug-in should run even if a package dependency is missing. +
- You can specify the Minimum Version and Maximum Version of the package you require. +
Automated Management of Dependencies
+The Automated Management of Dependencies section provides a new flexible workflow. This workflow allows you to code your plug-in first and then have PDE analyze your code and automatically generate the list of plug-in dependencies.
+
Press the Add... button to add plug-ins to the list. Consequently, this action will augment your development build path and your content assist scope accordingly.
+These dependencies do not get added to the MANIFEST.MF file immediately; however, you can start coding right away as if they were.
+At any time, you can click the add dependencies hyperlink to have PDE analyze your code and generate the correct dependencies in your MANIFEST.MF file via either the Require-Bundle or Import-Package headers.
+ + +Dependency Analysis
+The Dependency Analysis section contains several useful features that help you examine and optimize your plug-in dependencies to make your plug-in run better.
+
Since JARs from all the plug-ins listed as dependencies will be on your plug-in runtime classpath, it is very important not to list dependencies that are not required. Otherwise, class loading performance will be detrimentally affected. If you click the Find unused dependencies hyperlink, PDE will find unused and redundant entries in the list of required plug-ins and imported packages and offer to remove them.
+ +Related references
+Plug-in Editor+Overview Page
+Runtime Page
+Extensions Page
+Extension Points Page
+Build Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/editor.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/editor.htm new file mode 100644 index 0000000000..0c526582ef --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/editor.htm @@ -0,0 +1,48 @@ + + + + + +
Plug-in Manifest Editor
+PDE provides a single form-based multi-page plug-in manifest editor that manages all plug-in files: MANIFEST.MF, plugin.xml, fragment.xml and build.properties. The plug-in manifest editor is used as though a single file is being edited; while, PDE handles the task of writing the data to the different files on disk.
+For details on the individual editor pages, refer to the following documents:
+-
+
- Plug-in Overview +
- Plug-in Dependencies +
- Plug-in Runtime +
- Plug-in Extensions +
- Plug-in Extension Points +
- Plug-in Build +
Manifest Editor Presentation
+By default, the plug-in manifest editor shows information and tabs on extensions, extension points and Equinox-specific MANIFEST.MF headers and attributes. If you do not wish to use these Eclipse-specific features, you can filter out these pages from the editor on the Plug-in Development property page of your plug-in project via
+
+Properties > Plug-in Development
+ from the context menu of plug-in projects.
Relevant Links
+ + +Related references
+Overview Page+Dependencies Page
+Runtime Page
+Extensions Page
+Extension Points Page
+Build Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/extension_points.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/extension_points.htm new file mode 100644 index 0000000000..4930bc9e8c --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/extension_points.htm @@ -0,0 +1,33 @@ + + + + + +
Plug-in Extension Points
+Extension points define new function points for the platform that other plug-ins can plug into. The Extension Points page is the place to add, remove and edit extension points declared by your plug-in.
+
An extension point has three attributes:
+-
+
- ID - a required attribute whose value is a simple name +
- Name - a required attribute whose value is a translatable string +
- Schema - an optional attribute whose value is a relative path to the schema corresponding to this extension point +
Although the Schema attribute is optional, you are strongly encouraged to provide a schema; since, PDE utilizes it to assist other developers in using your extension point.
+ +Related references
+Plug-in Editor+Overview Page
+Dependencies Page
+Runtime Page
+Extensions Page
+Build Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/extensions.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/extensions.htm new file mode 100644 index 0000000000..d2a1eefa41 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/extensions.htm @@ -0,0 +1,36 @@ + + + + + +
Plug-in Extensions
+Extensions are the central mechanism for contributing behavior to the platform. Unless your plug-in is a documentation plug-in or a simple Java API library made available to other plug-ins, new behavior is contributed as an extension.
+The Extensions page is where you can add, remove and modify the extensions your plug-in contributes to the platform.
+ +All Extensions
+In the All Extensions section, press Add... to view all the available extension points that you can extend.
+
Each extension point comes with an XML schema specifying its grammar. When you select a new extension, PDE extracts the grammar for the corresponding extension point and populates the context menu of each element selected in the All Extensions viewer with a list of valid child elements that you can create.
+For each selected element in the body of an extension, PDE populates the Extension Element Details section with all the valid attributes for that element. Required attributes are denoted with an asterisk.
+When you hover your mouse over an attribute name, a tool tip box appears showing the description of that attribute.
+When an attribute expects the name of a Java class as a value (e.g. the class attribute above), clicking on the name of the attribute will open the Java file specified - if it exists. If the file does not exist, then clicking on the class link will bring up the JDT New Class wizard to create a new Java class on the fly.
+Some extension elements do not have attributes. Instead they require a description which can be specified in the Body Text section:
+
Related references
Plug-in Editor+New Extension Wizard
+Overview Page
+Dependencies Page
+Runtime Page
+Extension Points Page
+Build Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/new_extension_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/new_extension_wizard.htm new file mode 100644 index 0000000000..152ed22a48 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/new_extension_wizard.htm @@ -0,0 +1,34 @@ + + + + + +
New Extension
+The New Extension wizard allows you to add new extensions to your plugin.xml from the Extensions Editor. New extensions can be added by selecting an existing extension point or using a template wizard.
+ +From Extension Point
+
Select an extension point from the list of contributed points. By default Show only extension points from the required plug-ins is turned on so the list will only show points contributed by plug-ins in your project's required bundle list.
+ +From Extension Template
+
Select a template from the list and press Next to use a wizard to create a new extension.
+ +Related references
+Plug-in Editor+Overview Page
+Dependencies Page
+Runtime Page
+Extensions Page
+Extension Points Page
+Build Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/overview.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/overview.htm new file mode 100644 index 0000000000..f62aeb6ebb --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/overview.htm @@ -0,0 +1,50 @@ + + + + + +
Plug-in Overview
+The Overview page serves a dual purpose:
+-
+
- It contains two main sections that define important plug-in properties: General Information and Execution Environments. +
- It functions as a quick reference on how to develop, test and deploy plug-ins by providing the Plug-in Content, Extensions, Testing and Exporting sections. These sections provide hyperlinks that, when clicked, navigate to other pages or invoke commands. +
General Information
+
An ID is mandatory and must comply with the plugin.dtd.
+A Version is mandatory and must be of the form major.minor.micro.qualifier (e.g. 1.3.0).
+A Name is the translatable presentation name of the plug-in. This field is required.
+A Vendor is the translatable name of the plug-in vendor. This field is optional.
+A Platform filter is a valid LDAP string that must evaluate to true in a running system for the the plug-in to run. For example, the following filter indicates that the plug-in is designed to only run on platforms with a win32 windowing system: Eclipse-PlatformFilter: (ws=win32). If a user attempts to run Eclipse on a platform that does not meet this requirement, the plug-in will be silently ignored by the runtime.
+An Activator is a Java class that controls the plug-in's life cycle. It is only needed if you require work to be done on the startup or shutdown of your plug-in.
+ +Execution Environments
+A bundle execution environment specifies the minimum level of JRE required for the plug-in to run. If the JRE used to run Eclipse does not meet the requirement, the plug-in will not run.
+
Press the Add... button to browse a list of available execution environments and add one that is most suitable for your plug-in. For example, if you declare J2SE-1.4 as your plug-in's bundle execution environment, your plug-in will only run with a JRE version >= 1.4.
+If your plug-in can run in an execution environment that is not a proper subset of the execution environment specified (e.g. J2SE-1.4 and CDC-1.1/Foundation-1.1), both execution environments should be specified.
+During a plug-in export, the plug-in code is compiled against the JRE associated with the first execution environment listed in the MANIFEST.MF file . Click on the Configure JRE associations... link to open the
+
+Windows > Preferences... > Java > Installed JREs > Execution Environments
+
+ preference page for a list of OSGi execution environments and their corresponding list of compatible JREs installed on the system.
Whenever you update the list of execution environments for your plug-in, you should Update the classpath settings via the link to ensure you are compiling against the right JRE and have the settings that best match your first execution environment.
+ +Related references
+Plug-in Editor+Dependencies Page
+Runtime Page
+Extensions Page
+Extension Points Page
+Build Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/runtime.htm b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/runtime.htm new file mode 100644 index 0000000000..6b9fca0773 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/manifest_editor/runtime.htm @@ -0,0 +1,48 @@ + + + + + +
Plug-in Runtime
+The Runtime page shows all the packages that your plug-in makes visible to other plug-ins and the libraries and folders that constitute the plug-in runtime classpath.
+ +Exported Packages
+The Exported Packages section lists all packages that your plug-in intends to expose to downstream clients.
+
You can set a Version on each exported package when you press Properties.... The version is of the form major.minor.micro (e.g. 1.3.0).
+Press Add... to see the list of packages available for export that are not already in your list.
+PDE can calculate the uses directive, as defined in the OSGi Specification, for all of your publicly exported packages. Press the Calculate Uses button to begin. Because this process involves code introspection, this might be a long running operation.
+You can control the visibility of each package to downstream clients in the Package Visibility section. Refer to the Access Rules document for full details.
+When the visiblity of a package is changed the icon beside the package will change to reflect its status as follows:
+-
+
Visible to all downstream plug-ins (public)
+
Not visible to any downstream plug-ins (internal)
+
Visible to a specific list of downstream plug-ins (internal with friends)
+
Classpath
+The Classpath section lists all the locations the runtime will search when loading classes from this plug-in.
+
Since JAR'd plug-ins are the recommended format for Eclipse 3.1 and up built plug-ins, it is recommended to leave this section blank.
+Press New... to add the name of a library that has not been built yet.
+Press Add... to browse the current plug-in project and add an existing JAR or folder to the classpath.
+The order of the table entries dictate the class loading order; therefore, use the Up and Down buttons to organize your classpath accordingly.
+ +Related references
Plug-in Editor+Access Rules
+Overview Page
+Dependencies Page
+Extensions Page
+Extension Points Page
+Build Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/branding.htm b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/branding.htm new file mode 100644 index 0000000000..677bf2df61 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/branding.htm @@ -0,0 +1,32 @@ + + + + + +
Product Branding
+The Branding page gives the product its identity by customizing the window images, About dialog and the welcome experience.
+ +Window Images
+The Window Images section specifies the images associated with a product. If the images supplied by you do not match the size requirements, PDE flags a warning at the top of the page.
+
About Dialog
+The About Dialog is customiable by providing a custom image and text.
+
The About dialog text and image are also properties in the org.eclipse.core.runtime.products extension.
+ +Welcome Page
+It is recommended to ship a product with its own welcome page to introduce the features of the product to first-time users.
+
Providing a welcome page (Intro) requires the binding of the product to an org.eclipse.ui.intro extension.
+The Intro ID combo box is populated with existing Intro identifiers defined by plug-ins in the workspace and in the target.
+You may also create a new Intro on the fly by pressing the New.. button.
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/configuration.htm b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/configuration.htm new file mode 100644 index 0000000000..102911260d --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/configuration.htm @@ -0,0 +1,36 @@ + + + + + +Product Configuration
+The Configuration page defines information that builds the configuration file needed to run the product.
+ +Configuration File
+Upon startup, the runtime reads a configuration file named config.ini located in a configuration/ subdirectory of the configuration area of an Eclipse product. This file is a standard properties file that can configure many aspects of the runtime. For a full list of the supported properties, refer to the Eclipse runtime options document.
+
The Generate a default config.ini file is the default option and is recommended unless you have some very specific needs. When this option is selected, PDE generates a config.ini file with the following properties:
+-
+
- osgi.bundles - lists all the bundles that should be installed and optionally started once the system is up and running. This list is based on the osgi.bundles key found in the ${target_home}/configuration/config.ini file. (Note, the ${target_home} variable is the location of the target platform). +
- osgi.bundles.defaultStartLevel - denotes the default OSGi start level at which a bundle should start. The default value is set to 4. +
- eclipse.product - specifies the ID of the product to launch. +
- osgi.splashPath - specifies one or more locations of the splash screen. +
You also have the option to use an existing config.ini file which will be copied by PDE to your final product as-is.
+ +Start Levels
+In the start level section, you can list plug-ins to be automatically started or started with a specific start level.
+
Properties
+In the properties section, you can set configuration properties that will be added to any config.ini files generated by the editor. The properties can be qualified for a specific platform and/or OS architecture, or can apply to all configurations.
+
Product Contents
+The Contents page defines the content of the product.
+ +Content
+If the product is plugin-based, the Contents page shows a Plug-ins and Fragments section where you list all the plug-ins that will make up the product. This section also provides New Plugin... and New Fragment... buttons to enable you to create new plug-ins and fragments on the fly.
+
If the product is feature-based, the Contents page shows a Features section where you list all the features that will make up the product. This section also provides a New Feature... button to enable you to create new features on the fly.
+
Product Configuration Editor
+Building an Eclipse product using PDE is centered around a product configuration, a .product file. This file manages all aspects of a product definition from its constituent plug-ins to configuration files to branding.
+The product configuration is entirely managed by PDE to simplify Eclipse product development. Its format is internal and is not intended to be read by tools other than PDE.
+PDE provides a form-based multi-page editor to manage the product configuration.
+For details on the Product Configuration Editor, refer to the following documents:
+-
+
- Product Overview +
- Product Contents +
- Product Configuration +
- Product Launching +
- Product Splash +
- Product Branding +
- Product Licensing +
- Product Updates +
Product Launching
+The Launching page customizes the native launcher of your product and the launching arguments.
+ +Execution Environment
+The Execution Environment section allows you to specify an execution environment (EE) that the product runs on. The default JRE associated with the chosen EE can be bundles with the product if the option is turned on.
+
The JRE will be placed in the jre directory at the root of your product.
+ + +Program Launcher
+The Program Launcher section customizes the name and icon of the native launcher of the product.
+
To customize the name of the launcher, just enter the name in the Launcher Name field. If left unspecifed, the name will default to eclipse.
+Customizing the launcher icon varies per platform. The product editor indicates the platform requirements, and flags warnings at the top of the page if the supplied icons do not match the size or depth requirements.
+ +Launching Arguments
+The Launching Arguments section lets you specify the program and VM arguments that should be used for your product. These arguments are stored in a file named <launcher_name>.ini at the root of the product. PDE creates this file based on the values entered in this section. You can specify arguments for all Platforms, or choose a tab to specify arguments that apply only to a particular platform. You may use the combo box below the Platform tabs to specify arguments for a specific OS architecture. The Complete Arguments Preview text shows you what arguments will be used for the selected Platform and OS architecture, including arguments that apply to all platforms or architectures.
+
Product Licensing
+The Licensing page allows you to add a URL and license text for your product.
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/overview.htm b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/overview.htm new file mode 100644 index 0000000000..d563d2e207 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/overview.htm @@ -0,0 +1,42 @@ + + + + + +Product Overview
+The Overview page defines the product and provides hot links to test and export it.
+ +Product Definition
+A product is an org.eclipse.core.runtime.products extension. At minimum, it must have a name, an ID, a version and an application.
+
The product name is a translatable string that appears in the title bar of the application. It is defined as a property in the org.eclipse.core.runtime.products extension.
+The product identifier combo box is populated with the identifiers of all product extensions defined in the workspace and the target. You can select one of the defined products, or you can create a new product definition on the fly using the New... button.
+The product version is a string that is used to version your product file.
+A product must be associated with an application, which acts as the main entry point when the product is launched. An application is an org.eclipse.core.runtime.applications extension. The application combo box is populated with the identifiers of all application extensions defined in the workspace and the target.
+A product configuration can be plugin-based or feature-based. A plugin-based configuration is the default because it is simple and does not force you to understand concepts like features before building a product. A feature-based configuration is more powerful though, since it enables you to deliver a product that is updatable. That is, you can later publish patches or upgrades to your product on an update site and have your customers use the Eclipse installer to download and install these updates.
+ +Testing
+To test your product configuration, just click one of the hot links in the Testing section.
+
Similar hot links are also available in the plug-in manifest editor, but there is a noticeable difference in this instance. There is a Synchronize step.
+So why is a Synchronize needed? Remember that the product configuration is for PDE use only and is not interpreted nor read by the runtime. Some of the data that enter in this file (e.g. product ID, application, window images, about image, etc.) must be copied to the plugin.xml file of your branding plug-in for these changes to take real effect at runtime. That's what the synchronize action does. It makes sure your plugin.xml contains up-to-date data and in sync with the product configuration.
+If you use the hot link in this section, PDE does an implicit synchronization of files. If the product is launched via other means, e.g. a context menu launch shortcut, then automatic synchronization does not take place.
+ +Exporting
+To export an Eclipse product, you can invoke the Eclipse Product Export wizard via the hot link in the Exporting section.
+
To export a single product configuration to multiple platforms, you need to have the org.eclipse.equinox.executable feature installed in the target platform. It is available from the Eclipse project's p2 repository. The org.eclipse.equinox.executable feature contains all the different platform-specific fragments needed for all supported platforms.
+Once the org.eclipse.equinox.executable feature is in the target platform, PDE detects the presence of the org.eclipse.equinox.launchers feature and enables the cross-platform export mode.
+Note, to use the org.eclipse.equinox.executable feature, you have to ensure that the 'Build target platform based on the target's installed plug-ins' option remains unchecked in the Target Platform preference page.
+Note, the previously provided "Delta Pack" is no longer provided, as same functionality can be +achieved by using p2 repositories directly. For more information, see Cross-platform build. + + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/splash.htm b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/splash.htm new file mode 100644 index 0000000000..f15e7cb681 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/splash.htm @@ -0,0 +1,58 @@ + + +
+ + +Product Splash
+ +The Splash page provides the ability to customize your product with + a splash screen and a template or a progress bar and message. +
+ + + +Location
+The splash screen is typically located at the root of the + product-defining plug-in and must be called splash.bmp. +
+ +
Alternately, you may choose to place it at the root of any other plug-in in the + product (the name restriction stands). +
+ + + +Customization
+ +To customize the startup of a product, you can use either a splash screen + template or a progress bar and message. +
+ +
Splash screen templates contribute custom behavior to the splash screen that + appears during startup. The Template combo contains three templates + available for your convenience. During the export process the selected template's + required code will be added and a org.eclipse.ui.splashHandlers extension + will be created. Please be aware that you may only use a splash screen + template if your platform is built with 3.3 or higher. +
+ +Another option to customize your product is to use the integrated progress bar + in the Eclipse splash screen by specifying the co-ordinates of the + progress bar and progress message, + as well as the text color. The integrated progress data is specified using properties + in the org.eclipse.core.runtime.products extension. +
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/updates.htm b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/updates.htm new file mode 100755 index 0000000000..01b682231a --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/updates.htm @@ -0,0 +1,20 @@ + + + + + +Product Updates
+The Updates page defines information about how the product should update itself.
+ +Repositories
+The Repositories section allows you to add the URL's for any update repositories that should be used by the installed product. Buttons allow you to add, edit and remove the repositories for the product. +
Extension Point Schema Editor
+ +About Extension Point Schemas
+ ++ An extension point schema is an XML schema file that + defines a contract for extension points that extensions + must conform to in order to plug-in and extend the + platform. + + More specifically, an extension point schema specifies a formal grammar for an + extension point's elements and attributes. This grammar dictates the + structure, content and semantics of any contributed extension's XML mark-up. +
+ ++ Extension point schemas are used during plug-in development to do the following: +
+ +-
+
- + Validate extensions defined in workspace plug-ins. + +
- + Generate reference extension point documentation. + +
- + Assist the user in extension creation. + +
About This Editor
+ ++ The Extension Point Schema Editor allows you to do the following: +
+ +-
+
- + Create and edit an extension point schema's grammar. + +
- + Include and use the grammar defined by other shared extension point schemas. + +
- + Document an extension point schema's grammar. + +
- + Specify schema metadata used by PDE to automate common tasks. + +
- + Preview the extension point schema's reference document. + +
+ This editor abstracts the extension point schema's file mark-up away as an implementation detail that you do + not have to learn to use. +
+ +Editor Pages
+ ++ This editor is comprised of the following pages: +
+ +-
+
- + Schema Overview Page + +
- + Schema Definition Page + +
Global Editor Actions
+ ++ Click the Preview Reference Document hyperlink to + preview the reference document pertaining to the saved or unsaved contents of + the edited extension point schema. This action generates an HTML representation of the + schema and opens it in a browser. +
+ +
+ 
+
PDE XML Schema Support
+ ++ Extension point schemas are XML schemas. As a result, they are + written in XML and are able to take advantage of schema annotations + to improve ease of processing and readability. + However, extension point schemas only use a small subset + of XML schema features defined by the W3C XML Schema specification. +
++ Use of a small XML schema feature subset dramatically simplifies the structure + and syntax of extension point schemas while still addressing the required needs of the + extension point problem domain. + It also provides an aesthetic one-to-one mapping of the schema grammar to an + equivalent DTD grammar. +
+ ++ The main extension point schema limitations are as follows: +
+ +-
+
- + Only global element declarations are allowed. + +
- + Only local attribute declarations are allowed. + +
- + Only sequence and choice compositors are supported. + +
- + Only string and boolean attribute types are allowed. + +
- + Only the enumeration restriction is supported for + attributes of type string. + +
- + Only local element type declarations are allowed. + +
- + XML namespaces are not supported. + +
- + An element can be declared to specify either element + content or character content; but, not mixed content + (both element and character content). + +
Relevant Links
+ +-
+
- + New Extension Point Schema Wizard + +
- + + What is an extension point schema? + + +
- + Plug-in Manifest Editor + +
Schema Definition Page
+ +About This Page
+ ++ This form page allows you to edit the structure and + properties of schema objects that constitute the edited schema's + grammar. +
+ ++ The structure of schema objects are edited in + the Extension Point Elements section. + This section occupies the upper left-hand portion of the editor area. +
++ The properties of schema objects are edited in the + <schema-object> Details sections. + These sections are activated in the upper right-hand portion of the editor area depending + on the type of schema element selected in the Extension Point Elements section. +
+ +Page Sections
+ ++ This page is comprised of the following sections: +
+ +-
+
- + Extension Point Elements Section + +
- + Description Section + +
- + Element Details Section + +
- + Compositor Details Section + +
- + Element Reference Details Section + +
- + Attribute Details Section + +
Extension Point Elements Section
+ ++ This section allows you to do the following: +
+ +-
+
- + Visualize and edit the structure of schema objects that + constitute the edited schema's grammar. + +
- + Activate the corresponding <schema-object> Details section + used to edit the properties of a selected schema object. + +
+ This section is directly accessible through the Schema Definition form page. +
+ +Extension Point Elements Section Fields
+ ++ Use the extension point element viewer field to do the following: +
+ +-
+
- + Visualize and edit the structure of the + elements, attributes and compositors that + constitute the edited schema's grammar. + +
- + Activate the corresponding <schema-object> Details section + used to edit the properties of a selected element, attribute or + compositor. + +
+ This viewer contains the following nodes: +
+ ++ Elements: +
+ +-
+
-
+
+ - Select the Element node, to activate the Element Details section.
+
+ -
+
+ - Select the Element Reference node, to activate the Element Reference Details section.
+
+
+ Compositors: +
+ +-
+
-
+
+ - Select the Sequence Compositor node,
+ to activate the Compositor Details section.
+
+ -
+
+ - Select the Choice Compositor node,
+ to activate the Compositor Details section.
+
+
+ Attributes: +
+ +-
+
-
+
+ - Select the Required Attribute node, to activate the Attribute Details section.
+
+ -
+
+ - Select the Optional Attribute node, to activate the Attribute Details section.
+
+ -
+
+ - Select the Class Attribute node, to activate the Attribute Details section.
+
+ -
+
+ - Select the Resource Attribute node, to activate the Attribute Details section.
+
+
+ Example: The extension element specifies that a sequence + of one or more shortcut elements are allowed as its legal children. + An element reference is used to represent the shortcut element. + A Sequence compositor is used to represent a sequence of elements. +
+ +
+ 
+
+ Example: The shortcut element specifies that either a + description or category element is allowed as its legal + child. + Element references are used to represent the description + and category elements. + A Choice compositor is used to represent a choice of elements. + +
+ +
+ 
+
Extension Point Elements Section Actions
+ ++ Click the Add Element button to add a new global element declaration + to the extension point schema grammar. + This action is available when any node is selected. + Note: Element declaration order is not important +
+ ++ Click the Add Attribute button to add a new local attribute + declaration to a selected element in the extension point schema grammar. + This action is available for all selected element nodes + except for the extension element node. + The extension element node always has + the same attributes: id, name, point. + Note: Attribute declaration order is not important. +
+ ++ To delete a schema object from the extension point schema grammar, + right-click on a selected node and select Delete. + This action is available for all selected nodes except for + the extension element node. + For non-shared schemas, the extension + element node is the special root element used + to define the entry point to the edited schema's grammar. + Any extension + defined in the Plug-in Manifest Editor must use an + extension parent element to specify its XML + related mark-up. +
+ ++ To specify that an element's children is composed of a sequence or choice of other elements + in the extension point schema grammar, do the following: +
+ +-
+
- + Select and right-click the element node you wish to designate + as the parent element. + +
- + Select New > Compositor > Sequence to define a sequence of elements. + Select New > Compositor > Choice to define a choice of elements. + +
- + Select and right-click the new compositor node. + +
- + Select the element from the New > Reference + sub-menu that you wish to designate as a child of the parent element. + The Reference sub-menu is populated with all + the elements declared globally in the extension point schema grammar. + +
- + Repeat steps (3) and (4) to specify additional child elements. + If a Sequence compositor was specified, this amounts to + specifying additional elements in the sequence. + If a Choice compositor was specified, this amounts to + specifying additional element choices. + +
+ Note: To specify that an element is the child of another element, an intermediate + Sequence or Choice compositor must always be used + by the parent element. The compositor nodes are connector nodes; whereas, + the element reference nodes are leaf nodes. Therefore, + compositor nodes should always specify at least one child element reference + node. +
+ ++ Note: Sequence and Choice compositors + may be nested any number of times to create more complex grammars. +
+ ++ Note: A grammar must not contain self-referent cycles. + The most basic form of a prohibited cycle occurs when Element A requires + Element B as a child and Element B requires Element A as a child. +
+ ++ To specify that an element has no children and allows text to be + specified within its start and end XML tags (character content), + simply leave the element's structure as is by + not adding attributes, compositors and element references to it (element content). + Note: An element cannot specify mixed content + (both character content and element content). +
+ + +Description Section
+ ++ This section allows you to provide a brief description for any element, + attribute or compositor within the edited schema's grammar. +
+ ++ This section is directly accessible through the Schema Definition form page. +
+ +
+ 
+
Description Section Fields
+ ++ Edit the description text field to provide a brief description for + the current element, attribute or compositor + node selected in the Extension Point Elements section. + Valid HTML mark-up may be used within this field as needed. +
+ ++ Note: Updating an element reference description also updates the description + of the global element declaration it refers to and vice versa. +
+ + +Element Details Section
+ ++ This section allows you to edit the properties of an element. + There are two kinds of elements: extension element, non-extension element. + An extension element is the special root element declaration used + to define the entry point to the edited schema's grammar. + A non-extension element is a global element declaration used as a basic + structural building block within the edited schema's grammar. +
+ ++ This section is activated by selecting either a extension + element node or non-extension element node in the + Extension Point Elements section. +
+ ++ The Element Details section for an extension + element. +
+ +
+ 
+
+ The Element Details section for a non-extension element. +
+ +
+ 
+
Element Details Section Fields
+ ++ Edit the Name field to specify the element name. +
+ ++ Click either the true button or false button + within the Internal field to indicate whether the element + is internal or not. The Plug-in Manifest Editor will flag + any extension XML mark-up that is internal with a warning (by default). + This field is analogous to x-internal attribute on exported packages. +
+ ++ Click either the true button or false button + within the Deprecated field to indicate whether the element + is deprecated or not. The Plug-in Manifest Editor will flag + any extension XML mark-up that is deprecated with a warning (by default). + This field is analogous to Java's Javadoc @deprecated tag. +
+ ++ If an extension element is marked as deprecated, edit the + Replacement field to specify the non-deprecated + extension point the user should use in its place to achieve + the same functionality. +
+ ++ Select one of the element's defined attributes from the + Label Property field to specify the attribute value to + use as the element's label in the Plug-in Manifest Editor. + For instance, if a value is selected, the element's node label in the + All Extensions section of the + Extensions page in the Plug-in Manifest Editor will + be as follows: selected-attribute-value (element-name). + Otherwise, if no value is selected, the element's node label will be as follows: + (element-name). +
+ ++ Select one of the element's defined resource type attributes + from the Icon field to specify the + icon resource to use to represent the element's node in the + Plug-in Manifest Editor. + In order for the element's node icon to show up correctly in the + All Extensions section of the + Extensions page in the + Plug-in Manifest Editor, the following conditions + must be met: +
+ +-
+
- + The element must define a resource type attribute. + +
- + That attribute must be selected as the value of this field. + +
- + The contributed XML mark-up supplying the attribute value + must point to a valid icon resource file. + +
+ Click either the true button or false button + within the Translatable field to indicate whether the element's + character content is translatable or not. This field is only applicable for + elements that have no specified children (element content) or attributes and + allow text to be specified within its start and end XML tags (character content). + If an element's character content is marked as translatable, then PDE tools + can be used on contributed extension XML mark-up to externalize the content + into a properties file for multi-language support. +
+ ++ Use the read-only DTD approximation field to view + an approximate one-to-one mapping of the element schema grammar to the equivalent + element DTD grammar. A DTD (Document Type Definition) is + an easier to read, less-powerful alternative to XML Schema for + specifying an XML document's formal grammar. + The following notation is used to specify the DTD approximation: +
+ +-
+
- + element-name - Represents an element in the defined grammar. + +
- + EMPTY - Indicates that no element content or character + content is allowed (only attribute declarations). + +
- + #PCDATA - Indicates that only character content is + allowed (Parsed Character Data). + + +
- + () - Used to group an element's defined sequence and choice compositors. + +
- + | - Used to delimit element choices. Represents a logical or disjunction. + +
- + , - Used to delimit element sequences. Represents a logical and conjunction. + +
- + + - A qualifier used to indicate one or more instances are allowed. + +
- + * - A qualifier used to indicate zero or more instances are allowed. + +
Compositor Details Section
+ ++ This section allows you to edit the properties of a compositor. + There are two types of compositors: sequence compositor, choice compositor. + A sequence compositor allows you specify that an element's children is composed of a + sequence of other elements in the edited schema's grammar. + A choice compositor allows you specify a that an element's children is composed of a + choice of other elements in the edited schema's grammar. +
+ ++ This section is activated by selecting either a Sequence or + Choice node in the Extension Point Elements section. +
+ +
+ 
+
Compositor Details Section Fields
+ ++ Edit the Min Occurrences field to specify the minimum number + of occurrences this compositor of other elements and / or compositors is allowed + to appear in the contributed extension XML mark-up. This field's value is used + by PDE to validate multiplicity constraints within the + Plug-in Manifest Editor. + If Element A requires exactly one Element B or Element C as its child and it uses + a Choice compositor specifying 2 minimum occurrences, then any + 2 instances of Element B in combination with Element C must be defined in the contributed + extension XML mark-up in order to be valid. +
+ ++ Edit the Max Occurrences field to specify the maximum number + of occurrences this compositor of other elements and / or compositors is allowed + to appear in the contributed extension XML mark-up. This field's value is used + by PDE to validate multiplicity constraints within the + Plug-in Manifest Editor. + If Element A requires exactly one Element B or Element C as its child and it uses + a Choice compositor specifying 2 maximum occurrences, then no more than + 2 instances of Element B in combination with Element C can be defined in the contributed + extension XML mark-up to remain valid. +
+ ++ Check the Unbounded field to specify that + there is no constraint on the maximum number of allowed occurrences this + compositor may appear within the contributed extension XML mark-up. +
+ ++ Select a value from the Type field to specify whether this compositor is a + sequence or choice. +
+ ++ Use the read-only DTD approximation field to view + an approximate one-to-one mapping of the compositor schema grammar to the equivalent + compositor DTD grammar. The notation used to specify the DTD approximation + is described under the Element Details Section Fields heading in + this document. +
+ + +Element Reference Details Section
+ ++ This section allows you to edit the properties of an element reference. + An element reference is a reference to a global element declaration within + the edited schema's grammar. Element references are used by compositors + as atomic building blocks to define the grammar for global element declarations. +
+ ++ This section is activated by selecting an element reference + node in the Extension Point Elements section. +
+ +
+ 
+
Element Reference Details Section Fields
+ ++ Edit the Min Occurrences field to specify the minimum number + of occurrences this element is allowed + to appear in the contributed extension XML mark-up. This field's value is used + by PDE to validate multiplicity constraints within the + Plug-in Manifest Editor. + If Element A specifies 2 minimum occurrences, then + 2 instances of Element A must be defined in the contributed + extension XML mark-up in order to be valid. +
+ ++ Edit the Max Occurrences field to specify the maximum number + of occurrences this element is allowed + to appear in the contributed extension XML mark-up. This field's value is used + by PDE to validate multiplicity constraints within the + Plug-in Manifest Editor. + If Element A specifies 2 maximum occurrences, then no more than + 2 instances of Element A can be defined in the contributed + extension XML mark-up to remain valid. +
+ ++ Check the Unbounded field to specify that + there is no constraint on the maximum number of allowed occurrences this + element may appear within the contributed extension XML mark-up. +
+ ++ Use the read-only DTD approximation field to view + an approximate one-to-one mapping of the element schema grammar to the equivalent + element DTD grammar. The notation used to specify the DTD approximation + is described under the Element Details Section Fields heading in + this document. +
+ +Element Reference Details Section Actions
+ ++ Click the element-name hyperlink within the Reference + field to edit the properties of the global element declaration this local element + reference refers to. When this action is complete, the referenced + element node is selected in the + Extension Point Elements section and the corresponding + Element Details section is activated. +
+ + +Attribute Details Section
+ ++ This section allows you to edit the properties of an attribute. + Attributes are used to provide additional information about elements. +
+ ++ This section is activated by selecting either a required attribute, + optional attribute, class attribute or + resource attribute node + in the Extension Point Elements section. +
+ ++ The Attribute Details section for a required attribute of + type string that specifies an enumeration restriction. +
+ +
+ 
+
+ The Attribute Details section for an optional attribute of + type boolean that specifies a default value. +
+ +
+ 
+
+ The Attribute Details section for a class attribute + that indicates that the class represented by the attribute value + must extend the specified class and / or implement the specified interface.
+ +
+ 
+
+ The Attribute Details section for a resource attribute. +
+ +
+ 
+
Using the Schema Indentifier Attribute
+ +Extension point authors can define attributes that reference other attributes. This is accomplished by setting your extension point attributes as type identifier and choosing the attribute it references. An example of this would be the org.eclipse.ui.handlers extension point. The commandId attribute references commands defined in the org.eclipse.ui.commands extension point.
+ +
+
+ Extension developers contributing a handler can then select from all valid identifiers for the commandId attribute. Warnings are issued for identifiers that don't exist to prevent the common mistake of a misspelled identifier.
+ +Attribute Details Section Fields
+ ++ Edit the Name field to specify the attribute name. +
+ ++ Click either the true button or false button + within the Deprecated field to indicate whether the attribute + is deprecated or not. The Plug-in Manifest Editor will flag + any extension XML mark-up that is deprecated with a warning (by default). + This field is analogous to Java's Javadoc @deprecated tag. +
+ ++ Select a value from the Use field to indicate whether the + attribute must be specified on its defining element within contributed + extension XML mark-up. + The following selections are available: +
+ +-
+
- + optional - The attribute may be optionally specified on its defining element. + +
- + required - The attribute must be specified on its defining element. + +
- + default - The attribute may be optionally specified on its defining element. + If the attribute is not specified, then its value will assume the defined default value. + +
+ Edit the Default Value field to specify the default value + to use for an attribute when it is not specified on its defining element within contributed + extension XML mark-up. This field is only applicable when + the default value from the Use field is selected. +
+ ++ Select a value from the Type field to specify the attribute value type. + The following selections are available: +
+ +-
+
- + string - The attribute value can be any valid string. + +
- + boolean - The attribute value can be either true + or false (case insensitive). + +
- + java - The attribute value can be any fully-qualified class name + on the target platform's classpath (e.g. java.lang.String). + +
- + resource - The attribute value can be any project relative path to an + existing file or folder resource. + +
+ Click either the true button or false button + within the Translatable field to indicate whether the attributes's + value is translatable or not. This field is only applicable when + the string value from the Type field is selected. + If an attribute's value is marked as translatable, then PDE tools + can be used on contributed extension XML mark-up to externalize these values + into a properties file for multi-language support. +
+ ++ Use the Restrictions field to view + a list of string values the attribute is restricted to using + as its own value. If the field contains no values, then there + are no restrictions on the attribute value. + This field is only applicable when + the string value from the Type field is selected. + Note: An enumeration restriction on the string base type is used in + the edited schema's grammar to accomplish this functionality. +
+ ++ Edit the Extends field to specify a fully-qualified class name + on the target platform's classpath (e.g. org.eclipse.ui.part.EditorPart) that must + be sub-classed by the class specified as the attribute value. PDE will validate the + class attribute value in the contributed extension XML mark-up to ensure it + extends the super-class. + This field is only applicable when + the java value from the Type field is selected. +
+ ++ Edit the Implements field to specify a fully-qualified interface name + on the target platform's classpath (e.g. org.eclipse.ui.IEditorPart) that must be + implemented by the class specified as the attribute value. PDE will validate the + class attribute value in the contributed extension XML mark-up to ensure it + implements the interface. + This field is only applicable when + the java value from the Type field is selected. +
+ +Attribute Details Section Actions
+ ++ Click the Add... button in the Restrictions + field to open the New Restriction dialog in order to add a + new restriction to the attribute value. Once the dialog is completed, the + new restriction is added to the list of string values the + attribute is restricted to using as its own value. + This action is only available when + the string value from the Type field is selected. +
+ ++ Select a string value within the Restrictions + field and click the Remove button + to remove a restriction from the list of string values the + attribute is restricted to using as its own value. + This action is only available when + the string value from the Type field is selected. +
+ ++ If the value specified in the Extends field refers to + a fully-qualified class name on the target platform's classpath, then + clicking on the Extends hyperlink will open that class in + a new Java source editor. Otherwise, clicking on the Extends + hyperlink will open the New Java Class wizard allowing you + to create the new class. + This action is only available when + the java value from the Type field is selected. +
+ ++ If the value specified in the Implements field refers to + a fully-qualified interface name on the target platform's classpath, then + clicking on the Implements hyperlink will open that interface in + a new Java source editor. Otherwise, clicking on the Implements + hyperlink will open the New Java Class wizard allowing you + to create the new interface. + This action is only available when + the java value from the Type field is selected. +
+ ++ Click the Browse... button to open the + Select Type dialog in order to select an existing class on the + target platform's classpath to use as the value for the + Extends field. + This action is only available when + the java value from the Type field is selected. +
+ ++ Click the Browse... button to open the + Select Type dialog in order to select an existing interface on the + target platform's classpath to use as the value for the + Implements field. + This action is only available when + the java value from the Type field is selected. +
+ +Relevant Links
+ +-
+
- + Extension Point Schema Editor + +
- + New Extension Point Schema Wizard + +
- + Plug-in Manifest Editor + +
Schema Overview Page
+ +About This Page
+ ++ This form page allows you to identify and document an extension point schema. + It also allows you to include and use grammars defined by other shared extension point schemas. +
+ +Page Sections
+ ++ This page is comprised of the following sections: +
+ +-
+
- + General Information Section + +
- + Schema Inclusions Section + +
- + Documentation Section + +
General Information Section
+ ++ This section uniquely identifies the edited extension point schema. + The format of an extension point schema ID is the same as the + fully qualified ID of its corresponding extension point: + <plugin-id>.<point-id> +
+ +
+ 
+
General Information Section Fields
+ ++ Edit the Plug-in ID field to specify the qualifier portion + of the unique extension point schema ID. This field's value should match the + the ID of the plug-in that the schema's corresponding extension point is defined in. +
+ ++ Edit the Point ID field to specify the ID portion of the + unique extension point schema ID. This field's value should match the + ID used to define the schema's corresponding extension point. +
+ ++ Edit the Point Name field to specify a human-readable + name for the extension point schema. This field's value should match + the name used to define the schema's corresponding extension point. +
+ + +Schema Inclusions Section
+ ++ This section allows you to include and use the grammar from other shared + extension point schemas. +
+ +
+ 
+
Schema Inclusions Section Fields
+ ++ The viewer field lists the shared extension point schemas whose + grammars are included and used by the edited extension point schema. +
+ ++ Shared extension point schemas located in the same plug-in as the + edited extension point schema may be included. + These schemas are represented in the viewer by a relative path to + their file name: + <relative-path>/<schema-file-name> +
+ ++ Shared extension point schemas located in the another workspace + plug-in may be included. + These schemas are represented in the viewer by a special + absolute path to their file name: + schema://<defining-plugin-id>/<path>/<schema-file-name> +
+ +Schema Inclusions Section Actions
+ ++ Click the Add... button, to open the File Selection + dialog in order to include and use the grammar from an existing shared extension point + schema in the edited schema. + The dialog presents a filtered hierarchical view of all workspace extension point + schemas. If an extension point schema contained in a different plug-in than the + edited schema is selected, a special absolute path will be constructed and entered + into the viewer field. If an extension point schema contained in the same plug-in + as the edited schema is selected, a relative path from the edited schema to the + selected schema is computed and entered into the viewer field. +
+ ++ Click the Remove button, to remove the selected shared extension + point schema's grammar from inclusion and use by the edited extension point schema. + This action is available only when a schema is selected in the viewer field. +
+ ++ Double-click an extension point schema in the viewer field to open that schema + in a new Extension Point Schema Editor. +
+ + +Documentation Section
+ ++ This section allows you to document the edited extension point schema. + It's contents will be used to compose the edited extension point + schema's reference document. As a result, valid HTML mark-up may be used + in any of the section's fields. +
+ ++ This section contains the following tabs: +
+ +-
+
- + Description + +
- + Since + +
- + Examples + +
- + API Information + +
- + Supplied Implementation + +
- + Copyright + +
+ 
+
Documentation Section Fields
+ ++ Edit the Description tab's field to specify a detailed + description of the defining extension point for this edited schema. + Typically, this field is used to describe the extension point's + purpose, utility and associated concepts. +
+ ++ Edit the Since tab's field to specify the version of + Eclipse this edited schema was first added to. For example, + if this edited schema was first added to Eclipse 3.0, + the field's value should be 3.0. + The assumption is that the edited schema's grammar is API that + persists release to release once introduced and is maintained for backwards + compatibility. This field is analogous to Java's Javadoc + @since tag. +
+ ++ Edit the Examples tab's field to specify + a valid XML snippet of the extension that conforms to this edited + schema's grammar. Try to use an example that illustrates a typical + use case of the extension. +
+ ++ Edit the API Information tab's field to describe + the structure, content and semantics of the extension point's elements and attributes. +
+ ++ Edit the Supplied Implementation tab's field to + specify whether the plug-in that defines the extension point for + this edited schema also contributes extensions for it. This field + points the user to an actual extension implementation that they can + use as a template or reference for defining their own extensions. +
+ ++ Edit the Copyright tab's field to outline the exclusive legal + rights to reproduce, publish, sell, or distribute the edited schema. +
+ +Relevant Links
+ +-
+
- + Extension Point Schema Editor + +
- + Plug-in Manifest Editor + +
- + New Extension Point Schema Wizard + +
Command Composer Dialog
+ +About This Dialog
+ ++ This dialog allows you to browse, test and select new executable workbench + commands to add to a step or sub-step. The dialog also allows you to edit + applicable parameters for selected workbench commands. +
++ This dialog is accessible by clicking the Browse... button in the + Command section. +
+ +
+
+ Dialog Sections
+ ++ This dialog is comprised of the following sections: +
+ +| + Section + | ++ Description + | +
| + Commands Section + | ++ This section allows you to browse and filter executable workbench + commands by category. + | +
| + Command Details Section + | +
+ This section allows you to do the following:
+
+
|
+
Relevant Links
+ +-
+
- + Commands + +
- + Command Section + +
Simple Cheat Sheet Editor
+ +About Cheat Sheets
+ ++ In general, cheat sheets help guide users through a complex set of instructions. + There are two types of cheat sheets: simple and composite. + Simple cheat sheets are used to organize and present logical steps and sub-steps + to achieve a certain task. +
+ ++ You can view and run cheat sheets using the Cheat Sheet View. + To open a cheat sheet in this view, click Help > Cheat Sheets... +
+ +About This Editor
+ ++ The Simple Cheat Sheet Editor allows you to compose simple + cheat sheets and preview them in the Cheat Sheet View. + This editor also allows you to embed workbench commands and help document + links in your cheat sheets. +
+ +Editor Pages
+ ++ This editor is comprised of the following pages: +
+ +| + Page + | ++ Description + | +
| + Simple Cheat Sheet Page + | ++ A form page that allows you to edit the structure, order and properties of cheat sheet elements + | +
Global Editor Actions
+ ++ This editor provides the following global actions: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | +
| + Register this cheat sheet + | ++ Hyperlink + | ++ Register Cheat Sheet Wizard + | ++ This wizard allows you to register a simple or composite cheat sheet + with the Eclipse workbench to make it accessible through the + Help menu. + | +
Relevant Links
+ +-
+
- Cheat sheet example:
+
+ Creating an Eclipse Plug-in
+
+
+
- + Cheat sheet documentation: + Cheat Sheets + +
- + Composite Cheat Sheet Editor + +
- + New Cheat Sheet Wizard + +
- + + Recommended Work Flow for Cheat Sheet Development + +
- + Commands + +
Simple Cheat Sheet Page
+ +About This Page
+ ++ This form page allows you to edit the structure, order and properties of cheat sheet elements. +
++ The structure and order of cheat sheet elements are edited in + the Content section. + This section occupies the entire left-hand portion of the editor area. +
++ The properties of cheat sheet elements are edited in the Definition sections. + These sections are activated in the right-hand portion of the editor area depending + on the type of cheat sheet element selected in the Content section. +
+ +Cheat Sheet Elements
+ ++ A simple cheat sheet is composed of the following elements: +
+ +| + Element + | ++ Description + | ++ Parent(s) + | ++ Allowed Occurrences + | +
| + Root + | ++ The cheat sheet itself. + | ++ None + | ++ 1 + | +
| + Title + | ++ The title of the task being solved by the cheat sheet. + | ++ Root + | ++ 1 + | +
| + Introduction + | ++ The introduction of the task being solved by the cheat sheet. + | ++ Root + | ++ 1 + | +
| + Step + | ++ A step in the task being solved by the cheat sheet. + | ++ Root + | ++ 1 or more + | +
| + Sub-Step + | ++ A sub-step of a step in the task being solved by the cheat sheet. + | ++ Step + | ++ 0 or more + | +
| + Command + | ++ An executable workbench command that automates the work required by a step or sub-step. + | +
+ Step,
+ + Sub-Step + |
+ + 0 or 1 + | +
| + Help Document Link + | ++ An associated help link added to a step or introduction. + | +
+ Step,
+ + Introduction + |
+ + 0 or 1 + | +
| + Help Context ID + | ++ An associated help link added to a step or introduction. + | +
+ Step,
+ + Introduction + |
+ + 0 or 1 + | +
Page Sections
+ ++ This page is comprised of the following sections: +
+ +| + Section + | ++ Associated Element(s) + | ++ Description + | +
| + Content Section + | +
+ Title,
+ + Introduction, + + Step, + + Sub-Step + |
+
+ This section allows you to do the following:
+
|
+
| + Title Section + | ++ Title + | ++ This Definition section allows you to edit the title of the cheat sheet. + | +
| + Introduction Section + | ++ Introduction + | ++ This Definition section allows you to edit the introduction of the cheat sheet. + | +
| + Step Section + | ++ Step + | ++ This Definition section allows you to edit the properties of a step. + | +
| + Sub-Step Section + | ++ Sub-Step + | ++ This Definition section allows you to edit the properties of a sub-step. + | +
| + Command Section + | ++ Command + | +
+ This section allows you to do the following:
+
+
|
+
| + Help Section + | +
+ Help Document Link,
+ + Help Context ID + |
+
+ This collapsible section allows you to do the following:
+
+
|
+
Relevant Links
+ +-
+
- + Simple Cheat Sheet Editor + +
Command Details Section
+ +About This Section
+ ++ This section allows you to do the following: +
+ +-
+
- + Test an executable workbench command + +
- + Edit an executable workbench command's applicable parameters + +
- + Copy an executable workbench command's string representation to the clipboard. + +
+ This section is activated by selecting a command node in the Commands section. +
+ +
+
+ Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + Command ID + | ++ Text + | ++ Workbench Command ID + | ++ This non-editable field shows the workbench command ID. + | ++ N/A + | +
| + Command Parameter (0 or more) + | ++ Text or Combo Box + | ++ Command Parameter + | +
+ A workbench command may have 0 or more configurable parameters.
+ One input field is generated for each command parameter.
+ + + Enter applicable values into these fields to modify + the behavior of the workbench command accordingly. + |
+ + N/A + | +
+ An executable workbench command with parameters: +
+ +
+
+ + An executable workbench command without parameters: +
+ +
+
+ Section Actions
+ ++ This section provides the following actions: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | +
| + Execute + | ++ Hyperlink + | ++ Execute Workbench Command + | +
+ Click this link to execute the workbench command from within the
+ Command Composer Dialog.
+ + + Note: This action is not available for workbench commands that + cannot be executed from within a dialog. + |
+
| + Copy To Clipboard + | ++ Hyperlink + | ++ Copy Command String To Clipboard + | +
+ Click this link to copy an executable workbench command's
+ string representation to the clipboard.
+ + + The string representation can be used to directly embed workbench + commands into simple cheat sheets and user assistance documentation. + |
+
+
+ Relevant Links
+ +-
+
- + Commands + +
- + Command Composer Dialog + +
- + Commands Section + +
Command Section
+ +About This Section
+ ++ This section allows you to do the following: +
+ +-
+
- + Add an executable workbench command to a step or sub-step + +
- + Remove an executable workbench command from a step or sub-step + +
- + Edit the properties of an executable workbench command added to a step or sub-step + +
+ This section is accessible by selecting a step or sub-step node in the Content section. +
+ +
+
+ Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + Command + | ++ Combo Box + | ++ Workbench Command + | +
+ Select a recently added workbench command from this field to add a command to a step or sub-step.
+ Select <none> to remove a command from a step or sub-step.
+ + + Note: A command cannot be added to a step that contains sub-steps. + + + This field is globally populated and synchronized with all commands recently added + to all steps and sub-steps. + + + Use the Browse... button to select new workbench commands. + |
+ + No + | +
| + Parameters + | ++ Table + | ++ Workbench Command Parameters + | +
+ This non-editable field shows the applicable parameters for a workbench
+ command selected in the Command combo box.
+ + + Each row represents one command parameter or key-value pair. The first + column lists command parameter keys and the second column lists command + parameter values. + + + To edit the parameters of a selected workbench commands, click the + Browse... button. + |
+ + No + | +
+
+ Section Actions
+ ++ This section provides the following actions: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | +
| + Browse... + | ++ Button + | ++ Browse Workbench Commands + | +
+ Click this button to launch the
+ Command Composer Dialog.
+ + + This dialog allows you to browse, test and select new executable workbench + commands to add to a step or sub-step. The dialog also allows you to edit + applicable parameters for selected workbench commands. + |
+
Representation
+ ++ A step with a command is represented in the Cheat Sheet view as follows: +
+ +
+
+ + A sub-step with a command is represented in the Cheat Sheet view as follows: +
+ +
+
+ Relevant Links
+ +-
+
- + Commands + +
- + Command Composer Dialog + +
- + Content Section + +
- + Step Section + +
- + Sub-Step Section + +
Command Section
+ +About This Section
+ ++ This section allows you to browse and filter executable workbench + commands by category. It is accessible through the Command Composer Dialog. +
+ +Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + None + | ++ Text + | ++ Workbench Command Filter Field + | ++ Type a partial string in this field to filter the Workbench Command Viewer + categories and commands by matching occurrences of that string in their names. + | ++ N/A + | +
| + None + | ++ Tree Viewer + | ++ Workbench Command Viewer + | ++ Browse this field to select executable workbench commands. + All root nodes represent categories and all child nodes represent workbench commands. + | ++ N/A + | +
+
+ Relevant Links
+ +-
+
- + Commands + +
- + Command Composer Dialog + +
- + Command Details Section + +
Content Section
+ +About This Section
+ ++ This section allows you to do the following: +
+ +-
+
- + Visualize the structure and order of the cheat sheet's + title, introduction, steps and sub-steps + as they appear in the Cheat Sheet view. + +
- + Edit the structure and order of the cheat sheet's steps and sub-steps. + +
- + Activate the corresponding Definition section used to edit the + properties of a selected title, introduction, step or sub-step. + +
- + Preview and test the edited cheat sheet within the + Cheat Sheet view. + +
+ This section is accessible through the Cheat Sheet form page. +
+ +Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + None + | ++ Tree Viewer + | ++ Cheat Sheet Element Viewer + | +
+ Use this field this field to do the following:
+
|
+ + N/A + | +
Cheat Sheet Element Viewer
+ ++ This viewer contains the following nodes: +
+ +| + Node + | ++ Representation + | ++ Description + | +
+ 
+ |
+ + Root + | ++ Select this node, to activate the title Definition section. + | +
+ 
+ |
+ + Introduction + | ++ Select this node, to activate the introduction Definition section. + | +
+ 
+ |
+ + Step + | ++ Select this node, to activate the step Definition section. + | +
+ 
+ |
+ + Sub-Step + | ++ Select this node, to activate the sub-step Definition section. + | +
+
+ Section Actions
+ ++ This section provides the following actions: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | +
| + Add Step + | ++ Button + | ++ Add Step to Cheat Sheet + | +
+ Click this button to add a new step to the cheat sheet.
+ This action is available when any of following nodes are selected:
+ root, introduction, step.
+ + + If a step or introduction node is selected, the new step will be added + after the selected node. If the root node is selected, the + new step will be added as the last step of the cheat sheet. + |
+
| + Add Sub-Step + | ++ Button + | ++ Add Sub-Step to Step + | +
+ Click this button to add a new sub-step to a step.
+ This action is available when any of following nodes are selected:
+ step*, sub-step.
+ + + Note*: + Any step that either is optional or contains a command cannot + contain sub-steps. + + + If a sub-step node is selected, the new sub-step will be added after + the selected node. If a step node is selected, the new sub-step will + be added as the last sub-step of that step. + |
+
| + Remove + | ++ Button + | ++ Remove Cheat Sheet Element + | +
+ Click this button to remove a step or sub-step.
+ This action is available when any of following nodes are selected:
+ step, sub-step.
+ + + Note: In order to maintain cheat sheet validity, the following nodes + cannot be removed: root, introduction, step + (if it is the last remaining step in the cheat sheet). + |
+
| + Up + | ++ Button + | ++ Move Cheat Sheet Element Up + | ++ Click this button to move a step or sub-step up one position + in order above their respective siblings. + This action is available when any of following nodes are selected: + step, sub-step. + | +
| + Down + | ++ Button + | ++ Move Cheat Sheet Element Down + | ++ Click this button to move a step or sub-step down one position + in order below their respective siblings. + This action is available when any of following nodes are selected: + step, sub-step. + | +
| + Preview + | ++ Button + | ++ Preview Cheat Sheet + | +
+ Click this button to preview and test the saved or unsaved
+ contents of the edited cheat sheet in the Cheat Sheet view.
+ + + This convenient action allows you to observe how the edited cheat sheet + actually appears and operates within its deployed environment without having to + register the cheat sheet and launch another Eclipse runtime instance. + |
+
Representation
+ ++ A cheat sheet previewed in the Cheat Sheet view: +
+ +
+
+ Relevant Links
+ +-
+
- + Simple Cheat Sheet Page + +
- + Title Section + +
- + Introduction Section + +
- + Step Section + +
- + Sub-Step Section + +
Help Section
+ +About This Section
+ ++ This collapsible section allows you to do the following: +
+ +-
+
- + Add a help link to a step or introduction using either a help document link + or help context ID as input. + +
- + Remove a help link from a step or introduction. + +
- + Edit the help document link or help context + ID used as input to add a help link to a step or introduction. + +
+ This section is accessible by selecting a step or introduction node in the Content section. +
+ +
+
+ Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + Type + | ++ Combo Box + | ++ Help Link Type + | +
+ Select <none> to remove a help
+ link from a step or introduction.
+ Consequently, the Value input field
+ will no longer be visible.
+ + + Select Help Context ID to make the + Value input field visible right under + this field and ready to accept a help context ID as input. + + + Select Help Document Link to make the + Value input field visible right under + this field and ready to accept a help document link as input. + |
+ + No + | +
| + Value + | ++ Text + | ++ Help Document Link Value or Help Context ID Value + | +
+ If Help Context ID is selected in the
+ Type field, specify a valid help
+ context ID in this field to add a help link to a step
+ or introduction.
+ + + In the Cheat Sheet view, + clicking on a step or introduction's help link created + using a help context ID will open that help + context ID in the Help view. + + + The format of a valid help context ID is the following: + <plugin-id>.<help-context-id> + + + If Help Document Link is selected in the + Type field, specify a valid help + document link in this field to add a help link to a step + or introduction. + + + In the Cheat Sheet view, + clicking on a step or introduction's help link created + using a help document link will open that help + document link in the Help Infocenter. + + + The format of a valid help document link is the following: + /<plugin-id>/<path>/<html-file> + |
+ + No + | +
+ Example of a help link removed from a step or introduction. + Note: This section is collapsed by default when no help context ID or + help document link is specified. +
+ +
+
+ + Example of a help link added to a step or introduction defined using a help context ID as input. + Note: This section is expanded by default when a help context ID is specified. +
+ +
+
+ + Example of a help link added to a step or introduction defined using a help document link as input. + Note: This section is expanded by default when a help document link is specified. +
+ +
+
+ Representation
+ ++ An introduction with a help link and various steps with help links are + represented in the Cheat Sheet view as follows: +
+ +
+
+ + Note: A help link created using a help context ID is + indistinguishable from one created using a help document link + in the Cheat Sheet view. +
+ +Relevant Links
+ +-
+
- + Content Section + +
- + Step Section + +
- + Introduction Section + +
Introduction Section
+ +About This Section
+ ++ This Definition section allows you to edit the introduction of the cheat sheet. + It is activated by selecting the Introduction node in + the Content section. +
+ +
+
+ Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + Body + | ++ Text + | ++ Cheat Sheet Introduction + | +
+ Edit this field to specify the introduction of the cheat sheet.
+ + + The text may be formatted using bold and break tags: + To bold text, enclose with HTML-style bold tags: <b></b>. + To break text, use break tags: <br/>. + |
+ + Yes + | +
+
+ Representation
+ ++ The introduction is represented in the Cheat Sheet view as follows: +
+ +
+
+ Relevant Links
+ +-
+
- + Content Section + +
Step Section
+ +About This Section
+ ++ This Definition section allows you to edit the properties of a step. + It is activated by selecting a step node in the Content section. +
+ ++ Selection of a step without sub-steps: +
+ +
+
+ + Selection of a step with sub-steps: +
+ +
+
+ Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + Title + | ++ Text + | ++ Step Title + | ++ Edit this field to specify the title of the step. + | ++ Yes + | +
| + Body + | ++ Text + | ++ Step Body + | +
+ Edit this field to specify the instructional content of the step.
+ + + The text may be formatted using bold and break tags: + To bold text, enclose with HTML-style bold tags: <b></b>. + To break text, use HTML-style break tags: <br/>. + |
+ + Yes + | +
| + This step is optional + | ++ Checkbox + | ++ Optional Step + | +
+ Check this field to make the completion of this step in the Cheat Sheet
+ view optional.
+ + + A non-optional step includes a + Click when complete action in the Cheat Sheet + view to complete the step. An optional step includes a Click to skip + action in the Cheat Sheet view to skip the step. + + + Note: A step that contains sub-steps cannot be made optional. + |
+ + No + | +
+ Properties of a step without sub-steps: +
+ +
+
+ + Properties of a step with sub-steps: +
+ +
+
+ Representation
+ ++ A step without sub-steps is represented in the Cheat Sheet view as follows: +
+ +
+
+ + A step with sub-steps is represented in the Cheat Sheet view as follows: +
+ +
+
+ Relevant Links
+ +-
+
- + Content Section + +
- + Sub-Step Section + +
Sub-Step Section
+ +About This Section
+ ++ This Definition section allows you to edit the properties of a sub-step. + It is activated by selecting a sub-step node in the Content section. +
+ +
+
+ Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + Body + | ++ Text + | ++ Sub-Step Body + | ++ Edit this field to specify the instructional content of the sub-step. + | ++ Yes + | +
| + This sub-step is optional + | ++ Checkbox + | ++ Optional Sub-Step + | +
+ Check this field to make the completion of this sub-step in the Cheat Sheet
+ view optional.
+ + + A non-optional sub-step includes a + Click when complete action in the Cheat Sheet + view to complete the sub-step. An optional sub-step includes a Click to skip + action in the Cheat Sheet view to skip the sub-step. + |
+ + No + | +
+
+ Representation
+ ++ A sub-step is represented in the Cheat Sheet view as follows: +
+ +
+
+ Relevant Links
+ +-
+
- + Content Section + +
- + Step Section + +
Title Section
+ +About This Section
+ ++ This Definition section allows you to edit the title of the cheat sheet. + It is activated by selecting the root node in the Content section. +
+ +
+
+ Section Fields
+ ++ This section contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + Title + | ++ Text + | ++ Cheat Sheet Title + | ++ Edit this field to specify the cheat sheet title. + | ++ Yes + | +
+
+ Representation
+ ++ The title is represented in the Cheat Sheet view as follows: +
+ +
+
+ Relevant Links
+ +-
+
- + Content Section + +
Register Cheat Sheet Wizard
+ +About This Wizard
+ ++ This wizard allows you to register a simple or + composite cheat sheet with the Eclipse workbench + to make it accessible through the Help menu. +
+ ++ The underlying operation performed by this wizard involves generating + the XML-related mark-up for the Cheat Sheet Content + extension point (org.eclipse.ui.cheatsheets.cheatSheetContent) + and adding it to the plugin.xml file belonging to the plug-in project + the cheat sheet being registered is contained within. +
+ ++ A brief description and problem domain category may be + specified for the cheat sheet during registration. + This wizard will only register the cheat sheet once. + Subsequent uses of this wizard allow the user to update the + cheat sheet description and category values of the original registration. +
+ ++ To register the current cheat sheet being edited, click the + Register this cheat sheet + hyperlink in the title area of the Simple Cheat Sheet Editor or + Composite Cheat Sheet Editor. +
+ +
+
+ Wizard Fields
+ ++ This wizard contains the following fields: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | ++ Required + | +
| + Category + | ++ Combo Box + | ++ Problem Domain Category + | +
+ To categorize the cheat sheet being registered using an
+ existing problem domain category, select a value from this
+ field.
+ + + If an existing problem domain category is selected, the + registered cheat sheet will be placed as a node under that category + in the Cheat Sheet Selection dialog's tree + viewer. + + + If <none> is selected, the + registered cheat sheet will be placed as a node under the + Other category + in the Cheat Sheet Selection dialog's tree + viewer. + |
+ + No + | +
| + Description + | ++ Text + | ++ Brief Cheat Sheet Description + | +
+ Edit this field to specify a brief description for the
+ cheat sheet being registered.
+ + + If a description is specified, it will appear as a label under the + Cheat Sheet Selection dialog's tree + viewer when the registered cheat sheet node is selected. + |
+ + No + | +
+
+ Wizard Actions
+ ++ This wizard provides the following actions: +
+ +| + Label + | ++ Type + | ++ Name + | ++ Description + | +
| + New... + | ++ Button + | ++ Create New Category + | +
+ Click this button to create a new problem domain category.
+ + + In the resulting Create New Category dialog, + enter a category name in the Name field to + specify the problem domain the cheat sheet being registered + belongs to. + + + The new category will be added to the Category + combo box. + |
+
+
+ How To Access A Registered Cheat Sheet
+ ++ To access a registered cheat sheet within the Eclipse workbench, + perform the following steps: +
+ +-
+
- + Launch a new runtime Eclipse workbench*. + +
- + In the runtime Eclipse workbench, click + Help > Cheat Sheets... to open the + Cheat Sheet Selection dialog. + +
- + Within the dialog, select the following option: + Select a cheat sheet from the list + +
- + In the tree viewer, expand the problem domain category used + to categorize the registered cheat sheet. If one was not + specified, expand the Other category. + +
- + Select the registered cheat sheet + +
- + Click OK and the cheat sheet will be + opened in the Cheat Sheet view. + +
+ Note*: A registered cheat sheet is not + accessible through the Help menu in the (host) Eclipse + workbench being used to edit it. +
+ +
+
+ Relevant Links
+ +-
+
- + Simple Cheat Sheet Editor + +
- + Composite Cheat Sheet Editor + +
Site Information
+ +Site Description
+A site description may be as simple as a brief text description. Alternately, you may specify a URL pointing to an HTML file. The URL can be specified as absolute of relative. If relative, the URL is assumed to be relative to site.xml.
+
Site Mirrors
+An update site may point to the URL of a file listing update site mirror definitions. This URL can be absolute or relative to this site.
+
+Mirrors File
+The updates mirror file (the one specified in the Site Mirrors section above) +contains a list of mirror locations. Its format is defined by the following dtd: +
+<?xml encoding="ISO-8859-1"?>
+<!ELEMENT mirrors (mirror*))>
+<!ELEMENT mirror EMPTY>
+<!ATTLIST mirror
+
url
+CDATA #REQUIRED
+
label CDATA #REQUIRED
+
>
-
+
- <mirrors> - defines the available update site mirrors +
- <mirror> - defines a mirror site
+
-
+
- url - the URL of the mirror site +
- label - displayable label. Intended to be translated. +
+
Site Manifest Editor
+PDE provides a form-based multi-page site manifest editor that manages and builds a software site (repository) for p2.
+For details on the individual editor sections, refer to the following documents:
+-
+
- Site Map +
- Site Information +
Site Map
+The Site Map page of the site manifest editor lists, categorizes and builds the features hosted on the update site.
+ +Managing the Site
+Building an update site is a relatively simple task with the
+
To publish a feature on the site, you must first add it via the Add Feature... button.
+For easier browsing of the site, it is recommended to create categories and organize the features under those categories. A category has a name and a translatable label for display. A feature may appear in >= 0 categories. Categorization enables the installer to present a hierarchical view of features.
+Features are built recursively when you press Build All. This means that the features and all the plug-ins and fragments they include will be built in a single batch operation. The feature JARs end up in the features/ folder and the plug-in JARs are placed in the plugins/ folder of the update site project.
+If you are dealing with features that include other features, only the root feature needs to be listed, since the child features are automatically built.
+To build a single feature, select the feature and press the Build button..
+ +Feature Environments
+Features that do not carry such environment constraints are portable and can be installed on all platforms. If a feature has environment constraints that does not match the user's current platform, you can configure them to be filtered out.
+For faster filtering, feature environments should be associated with a feature entry in the site.xml.
+To copy feature environments from the feature.xml to the site.xml, press the Synchronize... button in the Managing the Site section.
+
Content Page
+ +The Content Page in the Target Definition Editor is used to view and edit the set of plug-ins to be included in the target definition when set as the active target platform. The definition must contain one or more locations containing plug-ins and the definition must be resolved to edit the content. Only the plug-ins that are checked on this page will be included in the target. There are multiple options available to filter and sort the list to quickly check what you require.
+ +This page edits the same information as the Content Tab on the Edit Target Wizard
+ +
+
+Select / Deselect will check or uncheck the selected plug-ins.
+ +Select All / Deselect All will check or uncheck all plug-ins in the target definition.
+ +Add Required takes the set of currently checked plug-ins and determines all plug-ins required by them. This will also include any implicit dependencies set on this target. The required plug-ins will be checked in the list.
+ +Use the Show options along with the filter text box at the top of the list to filter what is shown in the list. Showing plug-ins will show any non-source plug-ins in the target, while showing source bundles will display any source. Even if a plug-in is filtered from the list, it may be included in the target. You can see a count of included plug-ins underneath the list.
+ +The Group By option is used to organize the list into different groups. The options are:
+-
+
- None - No grouping, plug-ins sorted by name +
- File Path - Grouped by the directory path the plug-ins are stored in on the local file system +
- Location - Grouped by the locations set on the locations tab +
Managing Content with Features
+ +On the right hand side, you can choose between two different modes to manage the content of the target. By default targets +are managed using a list of plug-ins. Selecting Features will change your target contents to a list of features.
+ +
+
+You can select features in the same way as when managing by plug-ins. Add Required will select any features that the currently +selected features have in their include or require entries. If there are plug-ins in the target that do not belong to a +feature, they will be listed under the Other Plug-ins item and can be selected individually.
+ +Related references
Target Definition Editor+Definition Page (Target Definition Editor)
+Environment Page (Target Definition Editor)
+Source Page (Target Definition Editor)
+Edit Target Wizard + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/definition_page.htm b/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/definition_page.htm new file mode 100755 index 0000000000..ba43bef80d --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/definition_page.htm @@ -0,0 +1,34 @@ + + + + + +Definition Page
+ +The Definition Page in the Target Definition Editor is used to edit the most important settings in a target definition file. The Target Name is used to display your targets on the Target Platform Preference Page. The Locations section is used to add locations that contain plug-ins and works the same as the Location Tab on the Edit Target Wizard
+ +
+
+The locations in the target definition will be displayed in the list. Each type of location will have a different icon and text. If the target has been resolved the count of plug-ins will be displayed in blue (the number of plug-ins included from the content page and the total number of plug-ins found. If there are problems resolving the target, they will be displayed underneath the location with the problem. The Show Plug-in Content option can be turned on to display the included plug-ins underneath each location.
+ +Pressing Add will open the Add Location Wizard. It will provide a choice of location types to add. Selecting a location and pressing Edit will open a location type specific wizard to view and modify the location.
+ +Related references
+Target Definition Editor+Content Page (Target Definition Editor)
+Environment Page (Target Definition Editor)
+Source Page (Target Definition Editor)
+Edit Target Wizard + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/environment_page.htm b/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/environment_page.htm new file mode 100755 index 0000000000..c165cd0f5f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/environment_page.htm @@ -0,0 +1,40 @@ + + +
+ + +Environment Page
+ +The Enviroment Page in the Target Definition Editor is used to edit many settings in the definition affecting how the target will be compiled and run.
+ +
+
+The environment settings on this page can also be edited using the Environment Tab, Arguments Tab and Implicit Dependencies Tab on the Edit Target Wizard
+ +The Environment section has four settings that describe the system that this target is built for. If left blank, the settings for your current running environment are used. Changing these settings will affect how Software Site Locations resolve as well as how plug-ins are built and exported.
+ +You can specify a JRE or execution environment for this target definition in the Target JRE section. If you specify a specific JRE or EE here, when this target is set as the active target platform, your workspace default JRE will be changed.
+ +The Arguments section is used to set the default program and vm arguments for new PDE launch configurations.Pressing Variables will open the Variable Selection Wizard. You can browse through all known variables and get descriptions of what each does. Under the VM tab you can also press Import. This will open the Import Arguments Dialog. You can use it to import vm arguments used in the configuration data of any installation locations specified on the definition page.
+ +The Implicit Dependencies section is used to manage the implicit dependencies of the target. Any plug-in marked as an implicit dependency will always be added as a required plug-in when PDE determines requirements. Pressing Add will open the Implicit Dependencies Selection Dialog allowing you to select one or more plug-ins from your target platform to add as implicit dependencies.
+ +Related references
+Target Definition Editor+Definition Page (Target Definition Editor)
+Content Page (Target Definition Editor)
+Source Page (Target Definition Editor)
+Edit Target Wizard + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/source_page.htm b/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/source_page.htm new file mode 100644 index 0000000000..376016e0d8 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/source_page.htm @@ -0,0 +1,34 @@ + + + + + +Source Page
+ +The Source Page in the Target Definition Editor is used to edit the target definition directly through its source code. All of the changes made on other pages of the Editor are reflected here. Edits made to the source code are reflected on the other pages of the editor as well.
+ +
+
+Editing is made easier with completion assist suggestions for tags, unit ids and versions, and environment variables along with error diagnostics for solving syntax, formatting, and improper value errors.
+ +Ensuring the use of the newest IU versions is made easier with the "Update IU versions from repo" command found in the right-click context menu. This command will update the version tag value of all units within the target definition file
+ +Related references
+Target Definition Editor+Definition Page (Target Definition Editor)
+Content Page (Target Definition Editor)
+Environment Page (Target Definition Editor)
+Edit Target Wizard + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/target_editor.htm b/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/target_editor.htm new file mode 100755 index 0000000000..539469b941 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/target_editor.htm @@ -0,0 +1,45 @@ + + + + + +Target Definition Editor
+The Target Definition Editor is used to edit target definition files in the workspace, which should end with the extension ".target". Target definition files can be created using the New Target Definition Wizard or by moving them to the workspace on the Target Platform Preference Page.
+ +The editor consists of four pages:
+-
+
- Definition Page - Give your definition a descriptive name and provide the locations for plug-ins +
- Content Page - View the plug-ins available in your target and select a subset to include in the target platform +
- Environment Page - Modify other settings for your target defiition including target environment, JRE, arguments and implicit dependencies +
- Source Page - View and edit the source code of your target definition with assistance from completion-assist, error diagnostics, and an update command +
At the top of each of the three first pages in the editor there is a link Set as Target Platform. Activating this link will set this target definition as the active target platform. To see what your active target platform is, use the Target Platform Preference Page.
+ +Resolving Targets
+ +Before the contents of a target can be edited and before a target definition can be set as the active target platform it must be resolved. When a target definition is resolved, the definition's locations are searched for plug-ins. Depending on the type of locations in the target, this can involved searching a directory, reading the metadata for an installation, reading a feature, or downloading from a remote site. During resolution a background job will be run. When it completes the editor will be updated with any problems that occurred.
+ +For up to the minute target troubleshooting help see the Target Definitions Wiki Page.
+ +Related references
+Definition Page (Target Definition Editor)+Content Page (Target Definition Editor)
+Environment Page (Target Definition Editor)
+Source Page (Target Definition Editor)
+New Target Wizard
+Edit Target Wizard
+Move Target Wizard + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/editors/toc_editor/editor.htm b/org.eclipse.pde.doc.user/guide/tools/editors/toc_editor/editor.htm new file mode 100644 index 0000000000..fae1aee6ba --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/editors/toc_editor/editor.htm @@ -0,0 +1,55 @@ + + + + + +Table of Contents Editor
+ +About Tables of Contents
+ ++ Tables of contents allow you to organize your Eclipse product's contribution to on-line help. + A well-organized table of contents allows users to easily locate necessary documentation while working with an Eclipse product. + Users of Eclipse products can view installed products' contributions to help by clicking Help > Help Contents. +
+ +About This Editor
+ ++ The Table of Contents Editor allows you to create and + organize tables of contents and visualize their structures. + This editor also allows you to create new HTML pages and tables of contents, + and to locate existing ones in your workspace. +
+ +Editor Pages
+ ++ This editor is comprised of the following pages: +
+ +-
+
- + Table of Contents Page + +
Relevant Links
+ +-
+
- + Help System Documentation + +
- + New Table of Contents Wizard + +
Table of Contents Page
+About This Page
++ This page allows you to edit the structure and + properties of tables of contents. +
++ You can modify and visualize the structure and order of + elements in a table of contents using the + Table of Contents section. + This section occupies the left-hand portion of the + editor area. +
++ You can modify the properties of specific elements in the + Table of Contents by using the corresponding + Details sections. + These sections appear in the right-hand portion of the + editor area depending on the type of element selected + in the Table of Contents section. +
+ +Page Sections
++ This page is comprised of the following sections: +
+-
+
- Table of Contents Section +
- Book Details Section +
- Topic Details Section +
- Link Details Section +
- Anchor Details Section +
Table of Contents Section
++ This section allows you to do the following: +
+-
+
- + Visualize and modify the structure of a table of contents + via addition, removal and reorganization of its elements. + +
- + Activate the corresponding Details + section used to edit the properties of a specific element + in the table of contents. + +
- + Find and open existing documentation pages and tables + of contents linked from this table of contents. + +
+
+
+ Table of Contents Section Fields
++ The table of contents tree viewer field displays the + structure of the table of contents as it will appear + in the Help system. This tree viewer allows you to + modify the structure of the table of contents by + reorganizing existing elements or adding new ones + to the tree. +
++ This viewer contains the following kinds of elements: +
+-
+
-
+
+ The book element is the root element of a table of contents.
+ Select this element to activate the Book Details
+ section.
+
+ -
+
+ Topics serve as links to Help files, as well as containers for
+ other elements in the table of contents.
+ Select a topic to activate the Topic Details
+ section.
+
+ 
+ Links allow you to include elements from other tables of
+ contents in your table of contents.
+ Select a link to activate the Link Details
+ section.
+ 
+ Anchors allow other tables of contents to specify that their
+ elements will appear in your table of contents.
+ Select an anchor to activate the Anchor Details
+ section.
+
Table of Contents Section Actions
++ Click on the Add Topic, + Add Link or Add Anchor + buttons in order to add a new topic, link or anchor to the + table of contents. + These actions are available when any element is selected. + If the selected element is a book or topic element, + the new element will appear as the last child of the + selected element. + Otherwise, the element will appear immediately after the + selected element. +
++ You can also create topic elements by dragging HTML files + and dropping them on the desired location within your table + of contents. The newly added topic directs the user to the + dropped page. +
++ Similarly, you can create link elements by dragging XML files + representing tables of contents and dropping them on the + desired location within your table of contents. + The newly added link will reference the dropped table of + contents. +
++ Click the Remove button to remove an element + from the table of contents. + This action is available for all elements except the book + element. + Note that, in order to maintain the validity of a table of + contents, a topic cannot be removed if it is the only direct + child of the book element. +
++ Click the Up button to move an element up one + position with respect to its siblings. + This action is available for all elements except the book element. +
++ Click the Down button to move an element down + one position with respect to its siblings. + This action is available for all elements except the book element. +
++ You may also move elements within a table of contents by + dragging them and dropping them in the desired locations. +
++ To open the documentation file specified by a table of + contents or a topic, simply double-click on it. + To reveal the documentation file in a resource view, simply + right-click the element and select an option from the + Show In submenu. +
++ To open the table of contents specified by a link, simply + double-click on the link. + To reveal the table of contents in a resource view, simply + right-click the link and select an option from the + Show In submenu. +
+ + +Book Details Section
++ The Book Details section allows you to edit + the name, page location and anchor path of this table of + contents. +
+
+ Book Details Section Fields
++ Edit the Name field to specify the name + of the book.
++ Edit the Location field to specify the + location of a page associated with the book. + This page will appear when the user clicks on the book + element in the Help Contents window. + If no page is specified, a default Help page is automatically + generated by the Help system at runtime. +
++ The Anchor field allows you to specify if this + table of contents will be embedded within another table of + contents. + The anchor field takes the path to a table of contents + and the ID of an anchor contained in that table of contents, + separated by a '#' symbol. + When users view the referenced table of contents in the + Help Contents window, the contents of this + table will be displayed at the location of the specified + anchor. +
+Book Details Section Actions
++ If the path specified in the Location field + refers to an existing HTML page, then clicking on the + Location hyperlink will open the page in a + default editor. + If the path refers to a file that does not exist, or if the + path is empty, then clicking on the Location + hyperlink opens a New Page Wizard, which + allows you to create HTML pages. In the wizard, the + File name field is automatically populated + with the file name from the Location field + (if specified). If a valid folder path is specified in the + Location field, then this path is + automatically selected in the wizard as the location of the + new file. +
++ Click the Browse button to open the + Page Selection dialog, which allows you to + select an existing HTML page. + The dialog presents a hierarchical view of HTML pages + contained within your workspace. + After a selection is made, the relative path from the project + that contains the table of contents to the selected HTML page + is automatically entered into the Location + field. +
+ + +Topic Details Section
++ The Topic Details section allows you to edit + the name and page location of this topic. +
+
+ Topic Details Section Fields
++ Edit the Name field to specify the name of + the topic. +
++ Edit the Location field to specify the + location of a page associated with the topic. + This page will appear when the user clicks on the topic + element in the Help Contents window. + If no page is specified, a default Help page is automatically + generated by the Help system at runtime. +
+ +Topic Details Section Actions
++ If the path specified in the Location field + refers to an existing HTML page, then clicking on the + Location hyperlink will open the page in a + default editor. + If the path refers to a file that does not exist, or if the + path is empty, then clicking on the Location + hyperlink opens a New Page Wizard, which + allows you to create HTML pages. + In the wizard, the File name field is + automatically populated with the file name from the + Location field (if specified). + If a valid folder path is specified in the + Location field, then this path is + automatically selected in the wizard as the location of the + new file. +
++ Click the Browse button to open the + Page Selection dialog, which allows + you to select an existing HTML page. + The dialog presents a hierarchical view of HTML pages + contained within your workspace. + After a selection is made, the relative path from the + project that contains the table of contents to the + selected HTML page is automatically entered into the + Location field. +
+ + +Link Details Section
++ The Link Details section allows you to edit + the location of a linked table of contents file. +
+
+
+ Link Details Section Fields
++ Edit the Location field to specify the + location of a table of contents file to link. + The elements in the linked file will replace this link in + the table of contents when the user views the table of + contents in the Help Contents window. +
+ +Link Details Section Actions
++ If the path specified in the Location field + refers to an existing table of contents file, + then clicking on the Location hyperlink + will open the page in a default editor. + If the path refers to a file that does not exist, or if the + path is empty, then clicking on the Location + hyperlink opens a New Table of Contents Wizard, + which allows you to create a new table of contents. + In the wizard, the File name field is + automatically populated with the file name from the + Location field (if specified). + If a valid folder path is specified in the + Location field, then this path is + automatically selected in the wizard as the location of the + new file. +
++ Click the Browse button to open the + Table of Contents Selection dialog, which allows you to + select an existing table of contents. + The dialog presents a hierarchical view of tables of contents + contained within your workspace. + After a selection is made, the relative path from the project + to the selected table of contents is automatically entered + into the Location field. +
+ + +Anchor Details Section
++ The Anchor Details section allows you to + edit the identifier of this anchor. +
+
+
+ Anchor Details Section Fields
++ Edit the ID field to specify the identifier + of the anchor. +
+ +Relevant Links
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_features.htm b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_features.htm new file mode 100644 index 0000000000..1bcfa42768 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_features.htm @@ -0,0 +1,67 @@ + + + + + +Feature Export
+PDE provides a Feature Export wizard to export features and constituent plug-ins and fragments into a form that is suitable for deployment. The wizard shields you from Ant scripts and does not pollute your workspace with resources generated during the build operation. The wizard is available under
+
+File > Export... > Plug-in Development > Deployable features
+.
Feature Selection
+The wizard displays all the non-binary features found in the workspace.
+
Select the features that you want to export. If you find yourself exporting the same set of features over and over, you can press Working Set... to define a working set.
+Features are built recursively; therefore, in the case where one feature includes another feature, only the top-level feature needs to be selected in order to export them both. +
+ +Destination
+You can choose to export the features and their constituent plug-ins to a directory or to a ZIP archive. You can also choose to export the features in a runnable format and have them installed into your currently running Eclipse host.
+
If you choose to export to a Directory (the default), the features will be placed in a features/ subdirectory and the plug-ins will be placed in a plugins/ subdirectory of the chosen directory.
+If you choose to export to an Archive file, all of the features and plug-ins will be packaged into a single ZIP archive. Also, the root directory structure inside the ZIP starts with features/ and plugins/.
+If you choose to export and Install the features will be exported in a runnable format and a p2 repository will be generated. After the export completes, an installation operation will run to install the features. You will be prompted to restart Eclipse when the installation completes. To uninstall your features you must use the Installation Details button on the About Dialog (available by going to Help > About Eclipse SDK). For more details see Exporting and Installing into the Host
+ +Options
+
The Export source option results in the exporting of source code as well as binaries. There are two ways to package source with your exported feature. The Generated Source Bundles option will add the ant commands to the export to create separate source bundles for each of the exported plug-ins. For more information on source bundles see the PDE Build entry on Individual Source Bundles. The second option is to Include source in exported plug-ins. This option will package the source files in a src/ folder at the root of the JAR (if exporting in a JAR format). If the plug-in is packaged as a flat directory, the source code will be placed in a source ZIP inside the plug-in directory as a sibling to the library JAR.
+ +The Package as individual JAR archives option packages features and their constituent plug-ins as JARs. If the option is not selected, then the features are exported as flat directories, while their constituent plug-ins are packaged as specified in the feature.xml markup. Plug-in entries that are marked with unpack="false" in the feature.xml are exported as JARs; otherwise, they are exported as directories.
+There are two additional options available when packaging as individual JARs. The Generate metadata repository option allows you to also generate p2 metadata along with your exported feature. This allows the directory or archive you are exporting to, to be used as a repository that p2 can install and update from. This option must be turned on when exporting and installing into your running host. The Categorize repository allows the generated metadata repository to be organized by category.. A valid category xml file that includes data for the features being exported must be specified for categories to be created succesfully.
+ +The Qualifier replacement option enables you to substitute a value for the qualifier element in a plug-in's version or feature's version. The version must be in the following format: <major>.<minor>.<micro>.qualifier. For example: 3.3.0.qualifier. Normally, the qualifier represents a build date or identifier.
+ +The Save as Ant script option lets you save the settings of the export operation so that it can be re-executed at a later time without having to go through the wizard again. Like the export operation, the Ant task runs as an asynchronous job; therefore, it may not be suitable to incorporate it as a part of a larger Ant script.
+ +Allow binary cycles in target platform is an option that controls how the export operation deals with cycles in the dependency graph for a plug-in. PDE Build cannot compile if a cycle is detected. However, if a cycle only contains binary plug-ins from the target platform, turning on this option will allow PDE Build to continue.
+ +If the Use class files compiled in the workspace option is turned on, rather than compiling files as part of the export operation, the binary files in the workspace that were compiled by Eclipse are used. This should improve performance as it skips the compilation phase, but your workspace must have successfully compiled
+ +JAR Signing
+The JAR Signing tab is only visible when the Package as individual JAR archives option is selected on the Options tab.
+
To sign the JARs, you must be running Eclipse with a full JDK, rather than just a JRE.
+The Keystore location, Keypass, Alias and Password fields are all required for the signing operation.
+ +Java Web Start
+The Java Web Start tab is only available when the Directory option is selected on the Destination tab and the Package as individual JAR archives option is selected on the Options tab.
+
.
The Site URL and JRE version fields are both required.
+ +Related references
+Export Wizards+Plug-in Export Wizard + +
Related taskts
+Export and Install into the Running Host + + diff --git a/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_plugins.htm b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_plugins.htm new file mode 100644 index 0000000000..50e5c2e1d9 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_plugins.htm @@ -0,0 +1,58 @@ + + + + + +Plug-in Export
+PDE provides a Plug-in Export wizard to export plug-ins and fragments into a form that is suitable for deployment. The wizard shields you from Ant scripts and does not pollute your workspace with resources generated during the build operation. The wizard is available under
+
+File > Export... > Plug-in Development > Deployable plug-ins and fragments
+.
Plug-in Selection
+The wizard displays all the non-binary plug-ins found in the workspace.
+
Select the plug-ins that you want to export. If you find yourself exporting the same set of plug-ins over and over, you can press Working Set... to define a plug-in working set.
+ +Destination
+You can choose to export the plug-ins to a directory or to a ZIP archive. You can also choose to export the plug-ins in a runnable format and have them installed into your currently running Eclipse host.
+
If you choose to export to a Directory (the default), the plug-ins will be placed in a plugins/ subdirectory of the chosen directory.
+If you choose to export to an Archive File, all the plug-ins will be packaged in a single ZIP archive. The directory structure inside the ZIP also starts with plugins/ at its root.
+If you choose to export and Install the plug-ins will be exported in a runnable format and a p2 repository will be generated. After the export completes, an installation operation will run to install the plug-ins. You will be prompted to restart Eclipse when the installation completes. To uninstall your plug-ins you must use the Installation Details button on the About Dialog (available by going to Help > About Eclipse SDK). For more details see Exporting and Installing into the Host
+ +Options
+
The Export source option results in the exporting of source code as well as binaries. There are two ways to package source with your exported plug-in. The Generated Source Bundles option will add the ant commands to the export to create separate source bundles for each of the exported plug-ins. For more information on source bundles see the PDE Build entry on Individual Source Bundles. The second option is to Include source in exported plug-ins. This option will package the source files in a src/ folder at the root of the JAR (if exporting in a JAR format). If the plug-in is packaged as a flat directory, the source code will be placed in a source ZIP inside the plug-in directory as a sibling to the library JAR.
+ +The Package plug-ins as individual JAR archives option packages each plug-in as a JAR. This option is recommended for plug-ins whose code is stored at the root (i.e. plug-ins that have no MANIFEST.MF Bundle-ClassPath header or the header is of the form Bundle-ClassPath: .). Nested JARs are strongly discouraged as they hinder performance; since, the runtime will have to extract these JARs at runtime. Therefore, if the plug-in's code is packaged in a JAR, it is recommended to keep the deployed plug-in as a flat directory.
+ +The Qualifier replacement option enables you to substitute a value for the qualifier element in a plug-in's version. The plug-ins version must be in the following format: <major>.<minor>.<micro>.qualifier. For example: 3.3.0.qualifier. Normally, the qualifier represents a build date or identifier.
+ +The Save as Ant script option lets you save the settings of the export operation so that it can be re-executed at a later time without having to go through the wizard again. Like the export operation, the Ant task runs as an asynchronous job; therefore, it may not be suitable to incorporate it as a part of a larger Ant script.
+ +Allow binary cycles in target platform is an option that controls how the export operation deals with cycles in the dependency graph for a plug-in. PDE Build cannot compile if a cycle is detected. However, if a cycle only contains binary plug-ins from the target platform, turning on this option will allow PDE Build to continue.
+ +If the Use class files compiled in the workspace option is turned on, rather than compiling files as part of the export operation, the binary files in the workspace that were compiled by Eclipse are used. This should improve performance as it skips the compilation phase, but your workspace must have successfully compiled
+ +JAR Signing
+The JAR Signing tab is only available when the Package as individual JAR archives option is selected on the Options tab.
+
To sign the JARs, you must be running Eclipse with a full JDK, rather than just a JRE.
+The Keystore location, Keypass, Alias and Password fields are all required for the signing operation.
+ +Related references
+Export Wizards+Feature Export Wizard + +
Related tasks
+Export and Install into the Running Host + + diff --git a/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_product.htm b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_product.htm new file mode 100644 index 0000000000..09d3eabacb --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_product.htm @@ -0,0 +1,48 @@ + + + + + +Product Export
+PDE provides an Eclipse Product Export wizard to export an Eclipse product defined in a product configuration. The wizard shields you from Ant scripts and does not pollute your workspace with resources generated during the build operation. The wizard is available under
+
+File > Export... > Plug-in Development > Eclipse Product
+.
Product Configuration
+The Eclipse Product export wizard is centered around the product configuration, which encapsulates all the data that the wizard needs to build the plug-ins and features and generate all the configuration files that are necessary to run the product.
+The Browse... button lets you browse through all of the available .product files in the workspace and select the product configuration that will define the product's build process.
+The Root directory is the name of the top-level directory of the packaged product. It is set to eclipse by default; however, it can be changed to any name - including names with more than one segment. For example, if the root directory is set to rcp/product, then the product executable and the plugins/ directory will be placed in a rcp/product directory.
+ +Synchronization
+PDE uses the product configuration only to help create and customize the product. In order for certain types of data stored in the product configuration to take effect at runtime (e.g. window images, the About dialog image and text, etc.), corresponding properties must be written to the org.eclipse.core.runtime.products extension in the product's defining plug-in manifest file.
+The Synchronize before exporting option ensures that the plug-in manifest files are always up-to-date (the option is on by default).
+ +Destination
+The default option is to export a Directory. The product's Root directory is stored directly in the specified directory.
+When the option to export to an Archive file is selected, the product is packaged in a ZIP archive.
+ +Source Code
+The Include source code option results in the exporting of source code as well as binaries. If a plug-in is packaged as a JAR, the source code will be placed in a src/ folder at the root of the JAR. If the plug-in is packaged as a flat directory, the source code will be placed in a source ZIP inside the plug-in directory as a sibling to the library JAR.
+ +P2 Metadata
+The Generate metadata repository option allows you to also generate p2 metadata along with your exported feature. This does not create a p2-enabled product, just the metadata which can then be used to install using p2.
+ +One-Click Cross-Platform Export
+The Export for multiple platforms option is only available when PDE detects that the org.eclipse.equinox.executable feature is installed in the target platform. When this option is selected, a second wizard page is available and displays a list of available platforms to export to. This list is compiled by navigating the directory structure of the installed org.eclipse.platform.launchers feature to retrieve the different platform combinations.
+
In a single operation, PDE generates a product for each selected platform and places it in a directory whose name is of the form <os>_<ws>_<arch>. The os variable represents the selected operating system. The ws variable represents the selected windowing system. And, the arch variable represents the selected processor architecture.
+ +Related references
+Export Wizards + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_target.htm b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_target.htm new file mode 100755 index 0000000000..8c5ce143bd --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_target.htm @@ -0,0 +1,34 @@ + + + + + +Target Export
+PDE provides the Export Target Definition wizard to export the contents of your current target platform to a directory. All plug-ins and features in your target
+will be copied to destination. The wizard is available in the Target Definition editor or by selecting
+
+
+File > Export... > Plug-in Development > Target definition
+.
+
+This wizard will export the current active target definition. The active target is set on the Target Platform preference page.
+ +A directory must be chosen as a destination. The directory will be created if it does not exist. Select Clear destination directory before exporting to +have the contents of the destination directory deleted before exporting the current target.
+ +Related references
+Export Wizards+Target Platform Preference Page
+Target Definition Editor + + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_wizards.htm b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_wizards.htm new file mode 100644 index 0000000000..ee527f4747 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_wizards.htm @@ -0,0 +1,29 @@ + + + + + +
Export Wizards
+PDE provides wizards that build, package and export plug-ins, fragments, features and products into a deployable format. The PDE export wizards are available under
+
+File > Export... > Plug-in Development
+ from the top level menu.
For details on individual export wizards, refer to the following documents:
+ +Related tasks
+Export and Install into the Running Host + + diff --git a/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_category.htm b/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_category.htm new file mode 100755 index 0000000000..32df95457f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_category.htm @@ -0,0 +1,27 @@ + + + + + +New Category Definition File
+ +This wizard allows you to create a new category file. These files provide a set of categories and specify features that belong to each category. When exporting, a category definition file can be provided so that the exported metadata adds the exported features to the correct category.
+ +The Category Definition wizard is available under
+
+ File > New > Other... > Plug-in Development > Category Definition from the top level menu.
Related references
+Category Editor+Feature Export + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_cheat_sheet.htm b/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_cheat_sheet.htm new file mode 100644 index 0000000000..120803fab5 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_cheat_sheet.htm @@ -0,0 +1,57 @@ + + + + + + +
New Cheat Sheet Wizard
+ +About Cheat Sheets
+ ++ In general, cheat sheets help guide users through a complex set of instructions. + There are two types of cheat sheets: simple and composite. + Simple cheat sheets are used to organize and present logical steps and sub-steps + to achieve a certain task. Composite cheat sheets are used to organize and + present tasks represented by simple cheat sheets to achieve a larger goal. +
+ +About This Wizard
+ ++ This wizard allows you to create a new simple or composite cheat sheet. + Upon completion of this wizard, a new cheat sheet will be created with basic + content and opened in either the Simple Cheat Sheet Editor or + Composite Cheat Sheet Editor. +
+ +
+ To start this wizard, click
+
+
+ File > New > Other... > User Assistance > Cheat Sheet
+ .
+
+ 
+
Relevant Links
+ +-
+
- + Simple Cheat Sheet Editor + +
- + Composite Cheat Sheet Editor + +
+ New Context Help Wizard +
++ About Context Help +
++ Context-sensitive help is a mechanism that enables linking a + user interface part with a specific help topic. When the user + activates the associated user interface part, the help page + is displayed in the dynamic help area. Users of Eclipse + products can view installed products' contributions to help + by clicking Help > Help Contents. +
+ ++ About This Wizard +
++ This wizard allows you to create a new context help. Upon + completion of this wizard, a new context help will be created + with basic content and opened in the Context Help + Editor. +
+
+ To start this wizard, click
+
+ File > New > Other... >
+ User Assistance > Context Help .
+
+
+ 
+
+ Relevant Links +
+-
+
- + Context + Help Editor + + +
New File Creation Wizards
+In addition to manifest files, several other types of files are needed in various aspects and at different stages of plug-in development:
+ +To help you create these files, PDE provides specialized New File creation wizards available via
+ File > New > Other... > Plug-in Development
+ from the top level menu.
Plug-in Development Files
+ +
-
+
- Category Definitions - specify categories to apply to features during export +
- Extension point schemas - specify the grammar of extension points +
- Product configurations - manage all the data needed to define, brand and build an Eclipse product +
- Target definitions - define all aspects of a target platform +
User Assistance Files
+ +
-
+
- Cheat Sheet - Create a cheat sheet tutorial for an Eclipse product +
- Context Help - Create a context help xml file to associate UI components to help documentation +
- Help Table of Contents - Create a Table of Contents for help documentation +
Product Configuration
+A product configuration defines and manages all aspects of an Eclipse product. This file is a development-time file supported by PDE only and is neither interpreted nor read by the runtime.
+The New Product Configuration wizard is available under
+ File > New > Other... > Plug-in Development > Product Configuration from the top level menu.
File Name and Location
+The only restriction is that the product configuration must have a .product file extension. The product configuration can be placed in any project and any folder. The flexibility in naming the file allows you to store multiple product configurations in the same folder.
+ +Initial File Content
+A product configuration can be initialized in one of three ways:
+-
+
- Create a configuration file with basic settings: This option should be chosen if you have not yet defined a product extension in your plug-in or if you are a novice who does not even know what a product is. With this option, you get a product configuration with minimal content which you can incrementally start to define. +
- Use an existing product: This option should be chosen if you have already defined an org.eclipse.core.runtime.products extension in one of your plug-in and you would like to build and package the product. PDE will use all the settings already defined in the product extension (e.g. product ID, application ID, window images, etc.) to pre-populate the product configuration. +
- Use a launch configuration: This option should be chosen if you already have a launch configuration that contains all the settings you want in your product (e.g. product ID, list of plug-ins, program and VM arguments, etc.). PDE will use all the launch configuration settings to pre-populate the product configuration. +
Extension Point Schema
+An extension point schema is an XML schema that defines a grammar that formally expresses elements, attributes, and types. This information can be used by tools to validate extensions or offer assistance during the creation of extensions.
+The New Extension Point Schema wizard is available under
+ File > New > Other... > Plug-in Development > Extension Point Schema from the top level menu.
Extension Point
+When you create the schema, you need to specify the Extension Point Name and fully qualified ID of the extension point that the schema is associated with (i.e. the concatenation of the Plug-in ID and Extension Point ID).
+ +Schema
+The Container field refers to an existing location in the workspace where the schema will be created.
+The Extension Point Schema field specifies the path to the schema within the specified container. The schema must have a .exsd file extension.
+Some schemas (e.g. a schema for an expression language) may be incorporated in other schemas. These schemas are designated as shared when the Create shared schema for inclusion option is selected.
+When checked, the Edit extension point schema when done option opens the newly created .exsd file in a specialized PDE schema editor.
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_target_definition.htm b/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_target_definition.htm new file mode 100644 index 0000000000..fb0bd9b62f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/file_wizards/new_target_definition.htm @@ -0,0 +1,35 @@ + + + + + + +Target Definition
+A target definition specifies all aspects of a target - including its location, constituent plug-ins and environment.
+The New Target Definition wizard is available under
+ File > New > Other... > Plug-in Development > Target Definition
+ from the top level menu.
File Name and Location
+The only restriction is that the target definition must have a .target file extension. The target definition can be placed in any project and any folder. The flexibility in naming the file allows you to store multiple target definitions in the same folder.
+ +Initial File Content
+A target definition can be initialized in one of four ways:
+-
+
- Nothing: This option creates an empty target definition. +
- Default: This option creates a minimal target definition with default settings for all sections. +
- Current Target: This option initializes the file with the settings of the current target platform as defined on the
+
+Window > Preferences... > Plug-in Development > Target Platform preference page.
+
- Template: This option creates a copy of an existing target definition. This option is particularly useful if you are creating a target definition that augments or slightly modifies an existing target. +
+ New Table of Contents Wizard +
++ About Tables of Contents +
++ Tables of contents allow you to organize your Eclipse + product's contribution to on-line help. A well-organized + table of contents allows users to easily locate necessary + documentation while working with an Eclipse product. Users of + Eclipse products can view installed products' contributions + to help by clicking Help > Help Contents. +
+ ++ About This Wizard +
++ This wizard allows you to create a new table of contents. + Upon completion of this wizard, a new table of contents will + be created with basic content and opened in the Table + of Contents Editor. +
+
+ To start this wizard, click
+
+ File > New > Other... >
+ User Assistance > Table of Contents .
+
+
+ 
+
+ Relevant Links +
+-
+
- + Table of + Contents Editor + + +
Feature Import
+PDE provides a Feature Import wizard to import features from the file system into the workspace. The wizard is available under
+File > Import... > Plug-in Development > Features from the top level menu.
Import Location
+By default, the location to import features from is the target platform as specified on the
+
+Window > Preferences... > Plug-in Development > Target Platform preference page.
The Target Platform... button is a shortcut that opens the Target Platform preference page for inspection or modification.
+If you choose to import features from an arbitrary location on the file system and you do not wish to change the location of the target platform in the preferences, uncheck the Choose from features in the target platform checkbox. Then, use the Browse... button to navigate and enter the directory of choice. +Finally, make sure to press the Reload button to refresh the dialog.
+ +Import Format and Destination
+When features are imported, a project is created in the workspace for each feature. The project name is the concatenation of the feature ID and "-feature".
+If PDE detects that your workspace is set up for feature-based self-hosting (as detailed in the Tips and Tricks section), the features will be imported into a features/ directory that is a sibling of the plugins/ directory where the workspace is located.
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/import_wizards/import_plugins.htm b/org.eclipse.pde.doc.user/guide/tools/import_wizards/import_plugins.htm new file mode 100644 index 0000000000..9d3e961b9e --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/import_wizards/import_plugins.htm @@ -0,0 +1,51 @@ + + + + + + +Plug-in Import
+PDE provides a Plug-in Import wizard to import plug-ins and fragments from the file system into the workspace. The wizard is available under
+File > Import... > Plug-in Development > Plug-ins from the top level menu.
Import Location
+The plug-ins can be imported from one of three locations.
+-
+
- The active target platform (as specified in the Preferences):
+By default, the location to import plug-ins from is the active target platform as specified on the
+
+Window > Preferences... > Plug-in Development > Target Platform preference page.
+
+
- Target definition: +You can select this option to import plug-ins from a different target definition. Use the drop-down box to select the target definition of choice. +The Target Definitions... button is a shortcut that opens the Target Platform preference page for inspection or modification. +
- Directory: +Select this option if you choose to import plug-ins from an arbitrary location on the file system and you do not wish to change the location of the target platform in the preferences. Then, use the Browse... button to navigate and enter the directory of choice. +
Plug-ins and Fragments to Import
+The Select from all plug-ins and fragments found at the specified location option takes you to a second wizard page that lets you browse all plug-ins and choose a subset to import.
+
The Import plug-ins and fragments required by existing workspace plug-ins option is useful when you are importing all pre-requisites for a plug-in that is not part of the target platform. This option takes you to a second wizard page that is simpler; but, provides less overall control over what gets imported.
+
Import Format
+When plug-ins are imported, a project is created in the workspace for each plug-in. The project has the same name as the ID of the plug-in being imported.
+As for the content of each project, it varies by import format:
+-
+
- Binary projects: The plug-in content is copied into the project. The binary code remains intact in a JAR; while, the manifest files and other resources are extracted to the project root. The advantage of binary projects is that they allow you to browse the code without the overhead of compiling the source code. +
- Binary projects with linked content: The plug-in content is not copied into the project. Instead, links are created in the project to map to the actual physical location of the JARs, files and folders on disk. The advantage of this type of import over a regular binary import is that it is faster to import; since, the operation only involves creating links. The disadvantage of this approach is that linked binary projects can become out of sync and have to be re-imported if the absolute path to these linked files are changed in the file system. +
- Projects with source folders: The source code for the plug-ins being imported gets extracted and placed in source folders. The advantage of this type of import is that you will be able to modify the imported source code. The disadvantage of this approach is that the code gets compiled and results in an overhead whose magnitude is proportional to the number and size of plug-ins imported. +
- Projects from a repository: The manifest file for plug-ins can specify a source repository location (such as a CVS server). Plug-ins containing this information can be imported as source directly from the repository. This provides a quick way to get editable source and create patches for plug-ins you are working with. +
Import Wizards
+PDE provides wizards that import plug-ins, fragments and features from the file system into the workpace. The PDE import wizards are available under
+File > Import... > Plug-in Development from the top level menu.
For details on individual import wizards, refer to the following documents:
+-
+
- Plug-in Import +
- Feature Import +
Arguments Tab
+You can easily test your plug-in under different conditions by customizing the launching program and VM arguments on the Arguments Tab.
+
Program and VM Arguments
+Program arguments are application-specific values that the application code expects and processes. For example, the -debug argument puts the platform in debug mode and enables tracing, while the -nl fr arguments launch the application in a French locale.
+VM arguments are typically values that change the behaviour of the Java Virtual Machine (JVM). For example, the -Xmx256M argument allows the Java heap to grow to 256MB.
+The Eclipse runtime is also configurable via many system properties which can be passed as VM arguments in the form: -DpropertyName=propertyValue. For example, -Dosgi.clean=true clears all data cached by the OSGi framework and the Eclipse runtime.
+For a list of the program and VM arguments supported by the Eclipse runtime, refer to the following documents:
+ +If you would like the same set of program and VM arguments to be used for all your launch configurations, it is recommended that you use the Launching Arguments setting when editing your Target Platform to create a template that gets propagated into all newly-created launch configurations.
+ +Working Directory
+The Working Directory specifies the directory in which the runtime Eclipse application executes (e.g. read and write files into the working directory, etc.). By default, the working directory is the root directory of the Eclipse installation; but, it can be configured by the user to be any writable directory they wish.
+ +Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/common.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/common.htm new file mode 100644 index 0000000000..87cfd29a12 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/common.htm @@ -0,0 +1,35 @@ + + + + + +
Common Tab
+The Common Tab is a tab that is available to all PDE and Java launch configurations. It defines general aspects of the launch configuration including storage location, console encoding, etc.
+
Storage Location
+A launch configuration is saved as an XML .launch file on disk. By default, this file is saved in the ${workspace_loc}/.metadata/.plugins/org.eclipse.debug.core/.launches directory, where ${workspace_loc} denotes the workspace location.
+If you want to share a launch configuration with team members, you have the option to save it as a Shared file in one of your workspace projects (in order to make it visible for version control).
+ +Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/configuration.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/configuration.htm new file mode 100644 index 0000000000..0b8061e76f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/configuration.htm @@ -0,0 +1,56 @@ + + + + + +
Configuration Tab
+The Configuration Tab is an advanced tab that lets you override the default configuration area location and the config.ini file content of the runtime Eclipse application you are testing.
+
Configuration Area
+Every Eclipse application instance has a unique configuration area which contains metadata, caches and configuration files read by the runtime on startup.
+Typically, the location of the configuration is not important; therefore, PDE generates a unique configuration area for every launch in its own metadata area. This configuration area is deleted when the launch configuration is deleted.
+If desired, a user can set the location of the configuration area. Variables in the directory path are supported; thus, allowing launch configurations to be sharable among team members.
+There is also an option to Clear the configuration area before launching, which is useful for testing how plug-ins cache data in that area.
+ +Configuration File
+Upon startup, the runtime reads a configuration file named config.ini located in a configuration/ subdirectory of the configuration area associated with the Eclipse application instance. This file is a standard properties file that can configure many aspects of the runtime. For a full list of the supported properties, refer to the Eclipse runtime options document.
+The Generate a config.ini file with default content is the default option and is recommended unless you have some very specific needs. When this option is selected, PDE generates a config.ini file with the following properties:
+-
+
- osgi.bundles - lists all the bundles that should be installed and optionally started once the system is up and running. This list is based on the osgi.bundles key found in the ${target_home}/configuration/config.ini file. (Note, the ${target_home} variable is the location of the target platform). +
- osgi.bundles.defaultStartLevel - denotes the default OSGi start level at which a bundle should start. The default value is set to 4 +
- osgi.configuration.cascaded - indicates whether this configuration is standalone or has a parent configuration to cascade up to. The default value is set to false. +
- osgi.framework - specifies the URL location of the org.eclipse.osgi plug-in +
- osgi.install.area - specifies the location of the target platform. +
- osgi.splashPath - specifies one or more locations of the splash screen. +
The Use an existing config.ini file as a template option takes an existing config.ini file and makes a copy of it. PDE neither adds nor removes properties from this file. However, PDE modifies the osgi.bundles and osgi.splashPath keys by substituting their generic bundle URL values with absolute paths that reflect the actual locations of the bundles on disk.
+ +Software Installation
+Use Support software installation in the launched application to create p2 metadata for the plug-ins +being launched and starts the application with a profile containing the metadata. If the launched application does +not include p2, this option has no effect. The contents of the profile are cleared and recreated on each launch, +but if the application is restarted the same profile is kept.
+ +Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_application_launcher.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_application_launcher.htm new file mode 100644 index 0000000000..af024628fe --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_application_launcher.htm @@ -0,0 +1,45 @@ + + + + + +
Eclipse Application Launcher
+PDE provides an Eclipse Application launcher which allows you to run and debug your plug-in by launching a separate Eclipse application. As with all other launchers in Eclipse (e.g. the Java Application and Java Applet launchers,...), the Eclipse Application launcher can be invoked via a shortcut and its launch configurations are centrally managed in the Launch Configuration Dialog.
+ +Launching via a Shortcut
+A quick way to test a plug-in is by launching a separate application via Eclipse Application launch shortcuts that are available as:
+-
+
- hot links in the Testing section of the plug-in manifest editor's Overview page +
- actions in the Run As > and Debug As > context menus of plug-in projects +
Launch shortcuts are context-sensitive. If the selected resource is a plug-in project or plug-in manifest editor that declares an application (an org.eclipse.core.runtime.applications extension) or a product (an org.eclipse.core.runtime.products extension), then PDE launches that application or product. The set of plug-ins PDE launches with is a minimal set made up of the selected plug-in and all its pre-requisites only. If the selected plug-in contains both a product extension and an application extension, the product extension takes precedence.
+If the selected plug-in does not contain either a product extension or an application extension, PDE launches the default product as defined in the eclipse.product key of the config.ini file that is located in the ${target_home}/configuration directory. ${target_home} refers to the location of the target platform as specified on the Windows > Preferences... > Plug-in Development > Target Platform preference page. If the default product is launched, the set of plug-ins used in the launch are all the workspace plug-ins and all the plug-ins that are checked on the Target Platform preference page. Target plug-ins whose ID conflict with the ID of a workspace plug-in are not included in the launch configuration.
+PDE creates a new Eclipse Application launch configuration and pre-configures it with reasonable defaults. This is done only when needed - not every time an Eclipse Application launch shortcut is invoked. PDE searches existing Eclipse Application launch configurations first and reuses one that is already associated with the product or application being launched. If there are multiple existing launch configurations associated with the product or application being launched, PDE displays a dialog containing all matching launch configurations and lets the user decide.
+ +Customizing a Launch Configuration
+If you require full control over how to launch your Eclipse application, you can create and customize a launch configuration in the Launch Configuration Dialog.
+The Launch Configuration Dialog can be invoked via Run > Run... or Debug > Debug... from the top level menu. A new Eclipse Application launch configuration can be created by double-clicking on the Eclipse Application node in the tree viewer to the left.
+An Eclipse Application launch configuration contains seven tabs allowing you to customize all aspects of the test launch. Refer to the following documents for more details:
+-
+
- Main Tab +
- Arguments Tab +
- Plug-ins Tab +
- Configuration Tab +
- Tracing Tab +
- Environment Tab +
- Common Tab +
- Prototype Tab +
Related references
+ JUnit Plug-in Test Launcher+ OSGi Framework Launcher + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_main.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_main.htm new file mode 100644 index 0000000000..0c556194f1 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/eclipse_main.htm @@ -0,0 +1,62 @@ + + + + + +
Main Tab
+The Main Tab allows you to customize important settings of the launch configuration, including the location of the runtime workspace, the program to run and the Java runtime environment in which the program will run.
+
Workspace Data
+The Workspace Data location is the directory on disk that will contain all the work and metadata (e.g. preferences, etc.) for the runtime Eclipse application. This location must, of course, be different than the location of your host workspace since you should be testing your plug-in in a sandbox.
+By default, the location of the runtime workspace is set by PDE to have a unique name based on the launch configuration name and to be a sibling of the host workspace directory. You can set the location of the runtime workspace to be anywhere you like as long as the location is writable. Variable names can be used in the path to the runtime workspace location, thus allowing launch configuration to be sharable among team members.
+The Clear option is useful if you want to test your plug-in in a fresh workspace or with a clean log file. This option is turned off by default, because Eclipse application workspaces typically contain useful data that does not need to be cleared from one launch to the next.
+The Ask for confirmation before clearing option prompts the user before deleting the runtime workspace data. This option is turned on by default to prevent accidental loss of data from the test workspace.
+ +Program To Run
+The Program to Run section is where you specify the product or application to test.
+The product combo box is populated with the IDs of all products (org.eclipse.core.runtime.products extensions) defined in the workspace and target plug-ins. The product ID that is initially selected is the default product as specified by the eclipse.product key in the config.ini file that is located in the ${target_home}/configuration directory. The ${target_home} variable refers to the location of the target platform as specified on the Windows > Preferences... > Plug-in Development > Target Platform preference page. In the Eclipse SDK, the default product ID is org.eclipse.sdk.ide.
+The application combo box is populated with the IDs of all applications (org.eclipse.core.runtime.applications extensions) defined in the workspace and target plug-ins. The application ID that is initially selected is the default application as specified by the eclipse.application key in the config.ini file that is located in the ${target_home}/configuration directory. In the Eclipse SDK, the default application ID is org.eclipse.ui.ide.workbench.
+The Run a product option is selected by default, because testing a product (a branded application) makes for a richer experience than testing a plain application.
+ +Java Executable
+The Java Executable option allows you to specify the executable to run the Eclipse Application with. The default executable can vary but it is shown in the UI. +
+Java Runtime Environment
+You can test your plug-in against the Java Runtime Environment (JRE) of your choice; furthermore, this runtime JRE does not necessarily have to be the same JRE (with associated SDK) utilized to compile the workspace plug-ins.
+The Runtime JRE combo box is populated with all the JREs listed on the Windows > Preferences.... > Java > Installed JREs preference page. You can dynamically add more JREs to the list of installed JREs by pressing the Installed JREs... button, which will open the Installed JREs preference page.
+ +Bootstrap Entries
+Launching the host Eclipse instance typically involves a native launcher executable, which in turn calls an org.eclipse.equinox.launcher.Main class to start the bootstrapping process. The Main class is located in the bundle named org.eclipse.equinox.launcher.
+Launching a runtime Eclipse application bypasses the native executable and calls the Main class directly, as you would run any regular Java application. Therefore, PDE computes the location of the Main class and implicitly adds it to the classpath of the launch configuration.
+Certain profilers require some native libraries to be on the classpath of the launch configuration as well. The Bootstrap Entries field allows you to specify and append such additional locations to the classpath.
+ + +For more information on running Eclipse, refer to the following documents:
+ + +Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/environment.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/environment.htm new file mode 100644 index 0000000000..bfa8256386 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/environment.htm @@ -0,0 +1,41 @@ + + + + + +
Environment Tab
+The Environment Tab is a tab that is common to all PDE and Java launch configurations. + It defines the environment variable values to use when running an application. By default, the environment + is inherited from the Eclipse runtime. You may opt to override the environment or append to it.
++ Variables specified in the tab always replace values in the underlying native environment. However, when + "Append environment to native environment" is selected the launched environment is seeded + with the native environment, after which variables in the tab replace (existing variables) + or augment the set of environment variables. When "Replace native environment with + specified environment" is selected, the launched environment is comprised only of the + variables specified in the tab. +
+
Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_args.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_args.htm new file mode 100644 index 0000000000..7d14257dd9 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_args.htm @@ -0,0 +1,43 @@ + + + + + +
Arguments Tab
+You can easily test your bundle under different conditions by customizing the launching program and VM arguments on the Arguments Tab.
+
Program and VM Arguments
+Program arguments are values that the Equinox OSGi Framework expects and processes. For example, the -console argument enables the OSGi console allowing you to execute many commands such as installing, starting and stopping bundles. The -console argument is added by default to all newly-created Equinox OSGi Framework launch configurations.
+VM arguments are typically values that change the behaviour of the Java Virtual Machine (JVM). For example, the -Xmx256M argument allows the Java heap to grow to 256MB.
+The Equinox OSGi Framework is also configurable via many system properties which can be passed as VM arguments in the form: -DpropertyName=propertyValue. For example, -Dosgi.clean=true clears all data cached by the OSGi framework.
+For a list of the program and VM arguments supported by the Equinox OSGi Framework, refer to the following documents:
+ +If you would like the same set of program and VM arguments to be used for all your launch configurations, it is recommended that you use the Launching Arguments setting when editing your Target Platform to create a template that gets propagated into all newly-created launch configurations.
+ +Working Directory
+The Working Directory specifies the directory in which the Equinox OSGi Framework executes (e.g. read and write files into the working directory, etc.). By default, the working directory is the root directory of the Eclipse installation; but, it can be configured by the user to be any writable directory they wish.
+ +Related references
+ OSGi Framework Launcher+ Eclipse Application Launcher
+ JUnit Plug-in Test Launcher
+ Bundles Tab
+ Arguments Tab
+ Settings Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_launcher.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_launcher.htm new file mode 100644 index 0000000000..47c9714d7b --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_launcher.htm @@ -0,0 +1,42 @@ + + + + + +
OSGi Framework Launcher
+PDE provides an OSGi Framework launcher, which allows you to launch an OSGi framework and test or debug your OSGi bundle. As with all other launchers in Eclipse (e.g. the Java Application and Java Applet launchers,...), the OSGi Framework launcher can be invoked via a shortcut, and its launch configurations are centrally managed in the Launch Configuration Dialog.
+Note that in Eclipse, the words plug-in and bundle are used interchangeably. A plug-in is a bundle and a bundle is a plug-in.
+ +Launching via a Shortcut
+A quick way to test a bundle is by launching an OSGi Framework via Run As > OSGi Framework from the context menu of a plug-in project. To launch in debug mode, choose Debug As > OSGi Framework from the context menu of the plug-in project.
+When a shortcut is used, PDE searches for existing OSGI Framework launch configurations and creates a new launch configuration only if none were found. If a single launch configuration is found, it is used. If multiple configurations are found, PDE presents a selection dialog containing all existing OSGi Framework launch configurations and prompts the user to choose one. If a new OSGi Framework launch configuration is created, PDE will use the default
+ OSGi Framework which is specified on the
+ OSGi Frameworks preference page.
+
Customizing a Launch Configuration
+In order to have full control over launching an OSGi Framework, you can create and customize a launch configuration in the Launch Configuration Dialog.
+The Launch Configuration Dialog can be invoked via Run > Run... or Debug > Debug... from the top level menu. A new OSGi Framework launch configuration can be created by double-clicking on the OSGi Framework node in the tree viewer to the left.
+An OSGi Framework launch configuration contains six tabs allowing you to customize all aspects of the test launch. Please refer to the following documents for more details:
+- Bundles Tab +
- Arguments Tab +
- Settings Tab +
- Tracing Tab +
- Environment Tab +
- Common Tab +
- Prototype Tab +
Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_plugins.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_plugins.htm new file mode 100644 index 0000000000..969a97089e --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_plugins.htm @@ -0,0 +1,44 @@ + + + + + +
Bundles Tab
+The Bundles Tab allows you to select the bundles and their start level, which consequently allows you to customize the osgi.bundles and osgi.bundles.defaultStartLevel system properties that the launch configuration will run with.
+
Default Start Level
+A start level is a positive integer that denotes the default OSGi start level at which a bundle will run. The default start level, which is assigned to all selected bundles, is initially set to 4. This master setting can be changed directly to modify the start level of bundles en masse, or it can be overridden on a per-bundle basis.
+ +Default Start Status
+The start status indicates to the framework whether a bundle should be marked as active after it gets installed. If set to true (the default), a bundle will always be started when the framework is launched. The Default Auto-Start is a master setting that is applied to all selected bundles en masse, but it can be overridden on a per-bundle basis.
+ +Bundle Selection
+Bundles that are to be installed by the framework upon startup must be explicitly checked on this page. By default, a bundle will be assigned the default start level and the default start status, but these values can be overridden on a per-bundle basis by selecting the bundle and editing the start level and status in-place.
+There are several buttons available to help you select bundles including an Add Required Bundles button. The Add Required Bundles button should be used often to ensure the subset of bundles you have selected is complete.
+Please note that if a workspace bundle has the same ID as a target bundle, the workspace bundle overrides its target counterpart. This behavior can be overridden by deselecting a workspace bundle and selecting its target counterpart.
+ +Validate Bundles
+The Validate Bundles functionality, which can be invoked via the button located at the bottom right corner of the Bundles tab, analyzes the selected set of bundles to find launching startup problems. For instance, missing dependencies, unsatisfied execution environments, incompatible platform filters are a few of the potential problems that may prevent your bundle from running.
+By checking the Validate bundles automatically prior to launching option, PDE will run the Validate Bundle function prior to every launch. If problems are found, a dialog showing the error comes up for you to examine and you have the option to continue the launch without correcting the problems or canceling the launch to rectify the issues. Otherwise, if no problems are found, the launch proceeds as normal.
+ +Related references
+ OSGi Framework Launcher+ Eclipse Application Launcher
+ JUnit Plug-in Test Launcher
+ Bundles Tab
+ Arguments Tab
+ Settings Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_settings.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_settings.htm new file mode 100644 index 0000000000..164241b0e3 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/equinox_settings.htm @@ -0,0 +1,46 @@ + + + + + +
Settings Tab
+The Setting Tab allows you to customize the Java Runtime Environment (JRE) and configuration area settings of the launch configuration.
+
Java Executable
+The Java Executable option allows you to specify the executable to run the Equinox OSGi Framework with. The default executable can vary but it is shown in the UI.
+ +Java Runtime Environment
+You can test your bundle against the Java Runtime Environment (JRE) of your choice; furthermore, this runtime JRE does not necessarily have to be the same JRE (with associated SDK) utilized to compile the workspace bundles.
+The Runtime JRE combo box is populated with all the JREs listed on the Windows > Preferences.... > Java > Installed JREs preference page. You can dynamically add more JREs to the list of installed JREs by pressing the Installed JREs... button, which will open the Installed JREs preference page.
+ +Bootstrap Entries
+By default, the only entry on the launch configuration classpath is the ${target_home}/plugins/org.eclipse.equinox.launcher JAR. The ${target_home}/plugins/org.eclipse.equinox.launcher JAR file houses the org.eclipse.equinox.launcher.Main class which contains the bootstrap code. The ${target_home} variable refers to the location of the target platform as specified on the Window > Preferences... > Plug-in Development > Target Platform preference page.
+The Bootstrap Entries field allows you to specify and append additional locations to the classpath, if required.
+ +Configuration Area
+Every Equinox OSGi Framework instance has a unique configuration area which contains metadata, caches and configuration files read by the framework and possibly other bundles.
+Typically, the location of the configuration is not important; therefore, PDE generates a unique configuration area for every launch in its own metadata area. This configuration area is deleted when the launch configuration is deleted.
+If desired, the user can set the location of the configuration area. Variables in the directory path are supported in order to facilitate shareable launch configurations among team members.
+You also have the option to Clear the configuration area before launching, which is useful for testing how bundles cache data in that area.
+ +Related references
+ OSGi Framework Launcher+ Eclipse Application Launcher
+ JUnit Plug-in Test Launcher
+ Bundles Tab
+ Arguments Tab
+ Settings Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/junit_launcher.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/junit_launcher.htm new file mode 100644 index 0000000000..97f214153a --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/junit_launcher.htm @@ -0,0 +1,45 @@ + + + + + +
JUnit Plug-in Test Launcher
+PDE provides JUnit support for testing plug-ins by contributing a JUnit Plug-in Test launcher to the SDK. As with all other launchers in Eclipse (e.g. the Java Application and Java Applet launchers,...), the JUnit Plug-in Test launcher can be invoked via a shortcut and its launch configurations are centrally managed in the Launch Configuration Dialog.
+ +UI Tests vs. Headless Tests
+When a JUnit Plug-in Test launch configuration is launched, a lightweight PDE application is the main entry point to the runtime Eclipse instance. If the application being tested by the user requires a user interface, the PDE application spawns the workbench for that application. Once the workbench is up, the test harness runs inside the workbench. After all tests are run, the PDE application closes the workbench and exits; thus, terminating the test run.
+If the tests being run do not require a user interface (i.e. headless mode), then the lightweight PDE application runs the test without launching a workbench. After all tests are run, the PDE application exits.
+Refer to the Main tab of the JUnit Plug-in Test launch configuration for details on how to run the different types of tests.
+ +Launching via a Shortcut
+A quick way to run a JUnit plug-in test is via the Run As > JUnit Plug-in Test from the context menu of a plug-in project. To launch in debug mode, choose Debug As > JUnit Plug-in Test from the context menu of the plug-in project. These actions are also available in the context menus of source folders, packages, source files and methods inside a plug-in project.
+When creating a new launch configuration via a shortcut, PDE examines the dependencies of the enclosing plug-in. If the plug-in requires the org.eclipse.swt plug-in directly or indirectly, then the launch configuration that is created is customized to run UI tests; otherwise, the launch configuration is customized to run headless tests.
+ +Customizing a Launch Configuration
+In order to have full control over launching a JUnit Plug-in Test, you can create and customize a launch configuration in the Launch Configuration Dialog.
+The Launch Configuration Dialog can be invoked via Run > Run... or Debug > Debug... from the top level menu. A new JUnit Plug-in Test launch configuration can be created by double-clicking on the JUnit Plug-in Test node in the tree viewer to the left.
+A JUnit Plug-in Test launch configuration contains eight tabs allowing you to customize all aspects of the test launch. Refer to the following documents for more details:
+-
+
- Test Tab +
- Main Tab +
- Plug-ins Tab +
- Arguments Tab +
- Configuration Tab +
- Tracing Tab +
- Environment Tab +
- Common Tab +
- Prototype Tab +
Related references
+ Eclipse Application Launcher+ OSGi Framework Launcher + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/junit_main.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/junit_main.htm new file mode 100644 index 0000000000..8d8dc6bef7 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/junit_main.htm @@ -0,0 +1,64 @@ + + + + + +
Main Tab
+The Main Tab allows you to customize important settings of the launch configuration, including the location of the runtime workspace, the program to run and the Java Runtime Environment (JRE).
+
Workspace Data
+The Workspace Data location is the directory on disk that will contain all the work and metadata (e.g. preferences, etc.) for the runtime Eclipse application you are testing. This location must, of course, be different than the location of your host workspace, since you should be testing your plug-in in a sandbox.
+By default, the location of the runtime workspace is set by PDE to have a unique name based on the launch configuration name and to be a sibling of the host workspace directory. You can specify any location for the runtime workspace provided that the new location is writable. Variable names can be used in the path to the runtime workspace location in order to make the launch configuration sharable among team members.
+The Clear and Workspace options are selected by default because it is recommended to do test runs within a fresh workspace.
+The Ask for confirmation before clearing option prompts the user before deleting the runtime workspace data. This option is turned off by default, because the workspaces for JUnit Plug-in Test runs are typically not valuable.
+Please note that the defaults for the Clear and Ask for confirmation before clearing options in this launch configuration are opposite to the defaults on the Main tab of a regular Eclipse Application launch configuration.
+ +Program To Run
+The Program to Run section is where you specify the product or application to test.
+The product combo box is populated with the IDs of all products (org.eclipse.core.runtime.products extensions) defined in the workspace and target plug-ins. The product ID that is initially selected is the default product as specified by the eclipse.product key in the config.ini file located in the ${target_home}/configuration directory. The ${target_home} variable refers to the location of the target platform as specified on the Windows > Preferences... > Plug-in Development > Target Platform preference page. In the Eclipse SDK, the default product ID is org.eclipse.sdk.ide.
+The application combo box is populated with the IDs of all applications (org.eclipse.core.runtime.applications extensions) defined in the workspace and target plug-ins. The application ID that is initially selected is the default application as specified by the eclipse.application key in the config.ini file that is located in the ${target_home}/configuration directory. In the Eclipse SDK, the default application ID is org.eclipse.ui.ide.workbench.
+Some tests neither require a user interface nor a workbench and can therefore be run in headless mode. The JUnit Plug-in Test launcher provides such a mode in the application combo box.
+
Java Executable
+The Java Executable option allows you to specify the executable to run the Eclipse Application with. The default executable can vary but it is shown in the UI.
+ +Java Runtime Environment
+You can test your plug-in against the JRE of your choice; furthermore, this runtime JRE does not necessarily have to be the same JRE (with associated SDK) utilized to compile the workspace plug-ins.
+The Runtime JRE combo box is populated with all the JREs listed on the Windows > Preferences.... > Java > Installed JREs preference page. You can dynamically add more JREs to the list of installed JREs by pressing the Installed JREs... button, which will open the Installed JREs preference page.
+ +Bootstrap Entries
+Launching the host Eclipse instance typically involves a native launcher executable, which in turn calls an org.eclipse.equinox.launcher.Main class to start the bootstrapping process. The Main class is located in the bundle named org.eclipse.equinox.launcher.
+Launching a runtime Eclipse application bypasses the native executable and calls the Main class directly, as you would run any regular Java application. Therefore, PDE computes the location of the Main class and implicitly adds it to the classpath of the launch configuration.
+Certain profilers require some native libraries to be on the classpath of the launch configuration as well. The Bootstrap Entries field allows you to specify and append such additional locations to the classpath.
+ + +For more information on running Eclipse, refer to the following documents:
+ + +Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/junit_test.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/junit_test.htm new file mode 100644 index 0000000000..7558101038 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/junit_test.htm @@ -0,0 +1,44 @@ + + + + + +
Test Tab
+The Test Tab specifies the tests to run and the level of JUnit test runner to use.
+
+
+Tests to Run
+The JUnit Plug-in Test launcher allows you to run single tests or collections of tests en masse.
+If the individual test option is chosen, you have to specify the fully-qualified test class name along with the name of the plug-in project where the class is located. The launcher can give you more granularity for single tests by allowing you to choose to run a single method from within a test class.
+You also have the option to run all tests housed within a container (project, package or a source folder). In addition to the convenience of running an arbitrary number of test cases with a single click, this option gives you the additional flexibility of not having to update the launch configuration every time you add a test class to your suite. The list of tests is dynamically recomputed prior to every launch based on the current contents of the container.
+ +Test Runner
+Eclipse provides two JUnit test runners:
+-
+
- JUnit 3: uses JUnit 3.8.1. This is the default test runner. +
- JUnit 4: uses JUnit 4.1.0 and is available only if you are running Eclipse with a JRE version that is greater than or equal to 1.5. +
Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/plugins.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/plugins.htm new file mode 100755 index 0000000000..abf07fb8ce --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/plugins.htm @@ -0,0 +1,44 @@ + + + + + +
Plug-ins Tab
+When testing your plug-in, you have the ability to manage and select the list of plug-ins that you want to launch with on the Plug-ins Tab of the launch configuration.
+
Launch Options
+The Launch with combo box allows you to configure the way the Eclipse Application is launched. The options are explained in more detail below.
+The all workspace and enabled external plug-ins option is the default setting. With this option, the runtime Eclipse application you are launching will be made up of all the workspace plug-ins and all the plug-ins that are explicitly checked on the Window > Preferences... > Plug-in Development > Target Platform preference page. This option requires little maintenance because the list of plug-ins is maintained by PDE and updated prior to every launch as plug-ins are created or deleted in the workspace. This option is recommended when the Program to Run setting on the Main tab of the launch configuration is set to the default product or default application of your target.
+The plug-ins selected below only option is typically used when you are testing an RCP application that uses a subset of the plug-ins from the workspace and target. This setting requires more maintenance than the other options, since you have to ensure that the list of selected plug-ins is up-to-date when you add or remove a plug-in from the workspace. Add Required Plug-ins should be used to ensure the subset of plug-ins you have selected is complete.
+The features selected below option can be used to launch an RCP application by specifying features. It also allows to specify the location from where the feature plug-ins should be picked - Workspace or External (Target Platform). The plug-in resolution is first find location. Thus, if a plug-in marked for Workspace is not found there, then it is searched in External location and vice-versa. Select Add Plug-ins... to add individual plug-ins to the launch configuration. Select Required will look for the dependent features of the presently selected features and add them also to the configuration. If there are many features, Select Features... can be used to find and select specific features.
+Feature-based configurations launch with plug-ins resolved from the selected features and any additional plug-ins as well as all required plug-ins. This means that a minimal set of features/plug-ins can be selected and still have a valid launch.
+
Please note that if a workspace plug-in has the same ID as a target plug-in, the workspace plug-in is used in place of its target counterpart. This behavior applies to all three plug-in selection options described above; however, you can override this option by choosing the third option, deselecting a workspace plug-in and selecting the target plug-in with the same ID.
+ +Validate Plug-ins
+Selecting Validate Plug-ins analyzes the selected set of plug-ins to find launching startup problems. For instance, missing dependencies, unsatisfied execution environments, incompatible platform filters are a few of the potential problems that may prevent your plug-in from running.
+By checking the Validate plug-ins automatically prior to launching option, PDE will run the Validate Plug-ins function prior to every launch. If problems are found, an error dialog will appear for you to examine and you can choose to either continue the launch without correcting the problems or cancel the launch to rectify the issues. Otherwise, if no problems are found, the launch proceeds as normal.
+ +Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/prototype.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/prototype.htm new file mode 100644 index 0000000000..0bda70adea --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/prototype.htm @@ -0,0 +1,95 @@ + + + + + +
Prototype Tab
+An Eclipse Launch Configuration can now be based on a prototype.
+
A prototype seeds attributes in its associated Eclipse Launch Configurations with the settings specified in the Prototype Tab. +
+Once an Eclipse Launch Configuration has been created, you can override any initial settings from the prototype. +You can also reset the settings of an Eclipse Launch Configuration with the ones from its prototype. +An Eclipse Launch Configuration maintains a link to its prototype, but is a complete stand-alone launch configuration than can be launched, exported, shared, etc. +
+
Create Prototype
+Create a prototype via the New Prototype menu item or the New Prototype button in the toolbar.
+Existing prototypes have a small P in the top right corner of their icon.
+
Delete Prototype
+Delete a prototype the same way you delete an Eclipse Launch Configuration:via the Delete menu item or the Delete button in the toolbar.
+
Edit Prototype
+The Prototype Tab allows you to select the attributes that will be applied to the linked Eclipse Launch Configurations.
+It also indicates the value of all attributes of the Eclipse Launch Configuration.
+
Link Launch Configuration to Prototype
+Link an Eclipse Launch Configuration to a prototype via the Link Prototype menu item.
+
The link action opens a dialog allowing to select the prototype to link with.
+
Unlink an Eclipse Launch Configuration to a prototype via the Unlink Prototype menu item.
+
You can also link and unlink via the Link... and Unlink... buttons in the Prototype Tab.
+The difference is then you have to use the Apply button to validate the actions.
+
Reset Launch Configuration with Prototype values
+You can reset the attributes of an Eclipse Launch Configuration via the Reset with Prototype values menu item.
+
You can also reset the attributes values via the Reset to Prototype button in the Prototype Tab.
+The difference is that you have to use the Apply button to validate the reset.
+
Enable Prototype mechanism for your own launch configurations
+Prototypes are already enabled for JDT and PDE launch configurations. +Others projects have to enable prototypes in org.eclipse.debug.core.launchConfigurationTypes extension point: +
+<extension + point="org.eclipse.debug.core.launchConfigurationTypes"> + <launchConfigurationType + allowPrototypes="true" + delegate="org.eclipse.jdt.launching.sourcelookup.advanced.AdvancedJavaLaunchDelegate" + delegateDescription="%localJavaApplicationDelegate.description" + delegateName="%eclipseJDTLauncher.name" + id="org.eclipse.jdt.launching.localJavaApplication" + migrationDelegate="org.eclipse.jdt.internal.launching.JavaMigrationDelegate" + modes="run, debug" + name="%localJavaApplication" + sourceLocatorId="org.eclipse.jdt.launching.sourceLocator.JavaSourceLookupDirector" + sourcePathComputerId="org.eclipse.jdt.launching.sourceLookup.javaSourcePathComputer"> + </launchConfigurationType> +</extension> ++and also implement
org.eclipse.debug.ui.AbstractLaunchConfigurationTab.initializeAttributes() for their specifics tabs.
+
+
+Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/launchers/tracing.htm b/org.eclipse.pde.doc.user/guide/tools/launchers/tracing.htm new file mode 100644 index 0000000000..0a8104dc72 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/launchers/tracing.htm @@ -0,0 +1,52 @@ + + + + + +
Tracing Tab
+The Tracing Tab allows you to put the platform in debug mode and enable tracing which results in debug statements printed to the console.
+
Tracing
+The platform provides a mechanism for tracking the activity of your plug-in at runtime. It allows you to use tracing flags that will cause tracing information to be printed to the console.
+These flags are defined in .options files. These properties files must be located at the root of a plug-in and must have the following syntax:
+-
+
- <plug-in ID>/debug = true/false (master switch) +
- <plug-in ID>/<tracing flag> = <value> +
For example, the org.eclipse.ui.ide plug-in selected above has a .options file that contains three key-value pairs:
+-
+
- org.eclipse.ui.ide/debug = true +
- org.eclipse.ui.ide/debug/gc = true +
- org.eclipse.ui.ide/debug/internalerror/openDialog = true +
In your code, to check if your plug-in is in debug mode (i.e. state of the master switch), you can check the return value of <Activator>.isDebugging(), where <Activator> is the class specified in the Bundle-Activator header of your plug-in's MANIFEST.MF file.
+Values for individual flag names can be obtained by calling Platform.getDebugOption(optionName).
+ +Enable Tracing
+When the Enable tracing for the selected plug-ins option is checked, PDE launches with the -debug <filename> program argument. The <filename> portion of the program argument is a properties file generated by PDE that contains both key-value pairs for the plug-ins you are tracing and the state of each tracing flag.
+Please note that toggling tracing flags on the Tracing tab does not result in the modification of the .options file. The tracing flag values are saved as metadata in the launch configuration itself and are copied into the master properties file that is passed to the runtime via the -debug argument.
+ +Related references
+ Eclipse Application Launcher+ JUnit Plug-in Test Launcher
+ OSGi Framework Launcher
+ Junit Launcher Test Tab
+ Main Tab
+ Arguments Tab
+ Plug-ins Tab
+ Configuration Tab
+ Tracing Tab
+ Environment Tab
+ Common Tab
+ Prototype Tab + + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/pde_actions/convert_projects.htm b/org.eclipse.pde.doc.user/guide/tools/pde_actions/convert_projects.htm new file mode 100644 index 0000000000..cc9e895b24 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/pde_actions/convert_projects.htm @@ -0,0 +1,37 @@ + + + + + + +
Converting Java Projects to Plug-in Projects
+ +PDE provides a Converting Java Projects to Plug-in Projects + wizard to quickly and easily utilize PDE capabilities from a Java Project. To + open this wizard right-click on a Java project, open the Configure + menu and select Convert to Plug-in Projects.... +
+During the conversion process, PDE will add its nature and builders to the project, + add the Plug-in Dependencies classpath container. Finally, PDE will create a MANIFEST.MF and + build.properties for the project if they do not already exist. If Enable API analysis + is selected, the API Tools project nature will be added to the project. +
+ +
Project Selection
+ +You may select any of the open projects in your workspace which are not already + PDE projects. + By default, the projects selected in the workspace are the projects + selected for conversion by the wizard. +
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/pde_actions/externalize_strings.htm b/org.eclipse.pde.doc.user/guide/tools/pde_actions/externalize_strings.htm new file mode 100644 index 0000000000..4d0f7b2fd3 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/pde_actions/externalize_strings.htm @@ -0,0 +1,62 @@ + + + + + + +Externalizing Strings
+ +PDE provides an Externalize Strings wizard to help + externalize strings in your Manifest and plugin.xml files. + Externalizing manifest files extracts translatable strings and stores + them in a properties file for multi-language support. + The wizard is available through the Plug-in Tools menu after right clicking + on a plug-in project's MANIFEST.MF or plugin.xml files. +
+ +File Selections
+ +
The Plug-ins with non-externalized strings table + displays all the plug-in related files in the workspace that contain + non-externalized strings. The files are grouped by project, and they + display the number of non-externalized strings in brackets. + You can select one or more files to externalize at one time. +
+ +The text in the Localization box will be + used to define the properties file in which the externalized + string keys should be stored. The file's name is created by + adding ".properties" to the localization value. +
+ + + +String Substitution
+ +
After selecting a file in the Plug-ins with non-externalized strings + table, the non-externalized strings will be displayed in the + Strings to be externalized table. + Since you may not want to externalize all the strings in the + file, you may choose which strings you wish to externalize by + checking or unchecking strings in the table. Click on the + Substitution Key column to change the key name. +
+ +To see the current string value in the table, select either the + Value or Substitution Key column of a string. + The strings location will be highlighted and displayed in the Source + display. +
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/pde_actions/organize_manifests.htm b/org.eclipse.pde.doc.user/guide/tools/pde_actions/organize_manifests.htm new file mode 100644 index 0000000000..5b64def1fa --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/pde_actions/organize_manifests.htm @@ -0,0 +1,106 @@ + + + + + + +Organizing Manifest Files
+ +PDE provides an Organize Manifests wizard to help ensure that + the information in your Manifest is up to date. + The wizard is available through the Plug-in Tools menu after right clicking + on a plug-in project's MANIFEST.MF or plugin.xml files. +
+ +
+
Export Package Options
+The Ensure that all packages appear in the MANIFEST.MF option + will add Export-Package declarations for any package in the project which is not + already exported. +
+ +The Mark as internal all packages that match the following filter + option can be used to modify the visibility of any Export-Package declarations in a + project's Manifest. The Package filter field should contain a + regular expression used to match the names of packages that should be marked internal. + Packages marked as internal will not be available for use by other bundles. + Refer to the Access Rules + document for more information on package visibility. +
+ +The Remove unresolved packages option will remove any Export-Package + entries which cannot be resolved. There are a variety of reasons why an exported package + cannot be resolved, but the most common reason is because it does not exist in the + project. +
+ +The Calculate 'uses' directive for public packages option will + handle the complicated computations for the 'uses' directive for any packages that + other bundles have access to. Since the computations are complex and require code + introspection, this operation may take more time than other organization operations. + This operation has been marked as a long-running operation. +
+ +Dependency Options
+ +The Handle unresolved dependencies option allows you to clean up + your Manifest by removing any unresolved dependencies. + A dependency may be unresolved for a variety of reasons, such as an optional plug-in + being missing from the current configuration. For this reason, you may elect to handle + unresolved dependencies by either removing them from the Manifest or + marking them as optional. +
+ +The Remove unused dependencies option can help you identify and + remove any unused dependencies currently defined in the Manifest. + Unused dependencies may require additional unnecessary bundles to be installed in a + runtime. This operation analyzes your project's code to check for references and + may take more time than other organization operations. This operation has been + marked as a long-running operation. +
+ +The Add required dependencies option inspects the project's + code to try to add additional dependencies which are not currently included in + the manifest. + This operation will only find new dependencies for bundles listed in the + Automated Management of Dependencies section of the + Dependencies page in + the Manifest Editor. + This examination may take more time than other organization operations and has + been marked as a long-running operation. +
+ +Miscellaneous Options
+ +The Remove unnecessary lazy activation headers option will + remove lazy activation headers if a Bundle-Activator is not defined. + If a bundle has nothing to contribute when it is started, a lazy activation + header is not necessary. +
+ +The Delete unnecessary plug-in manifest files option will + remove plugin.xml files if a plug-in doesn't contribute any extension or + extension points. +
+ +Internationalization Options
+ +The Prefix icon paths in plug-in extensions with a $nl$ segment + option will modify icon paths to allow fragments to contribute unique icons for + different locales. +
+ +The Remove unused keys from the plug-in's properties file + option will help find and remove unused keys in the plug-in's properties file. +
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/pde_actions/task_wizards.htm b/org.eclipse.pde.doc.user/guide/tools/pde_actions/task_wizards.htm new file mode 100644 index 0000000000..a07f334293 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/pde_actions/task_wizards.htm @@ -0,0 +1,32 @@ + + + + + + +Task Wizards
+ +PDE provides wizards that will help save you time configuring your workspace + and developing plug-ins. The PDE task wizards are available by selecting the + Plug-in Tools menu after right clicking on a plug-in project, + a MANIFEST.MF file or plugin.xml file. +
+ +
For details on individual task wizards, please refer to the following documents:
+-
+
- Converting Java Projects to Plug-in Projects +
- Externalizing Strings +
- Organizing Manifest Files +
- Updating Classpaths +
Updating Classpaths
+ +PDE provides an Update Classpath wizard that quickly + updates the classpaths of multiple projects. The update will change the + JRE and compiler settings to best match the first execution environment + specified in each project's Manifest. + The wizard is available under the Plug-in Tools menu after right clicking on a + Plug-in Project. +
+ +
Project Selection
+ +When updating classpaths, you may select any plug-in or fragment project + in your workspace. + All selected projects in your workspace will be selected in the + Update Classpath wizard by default. +
+ + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/compilers.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/compilers.htm new file mode 100644 index 0000000000..870936e325 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/compilers.htm @@ -0,0 +1,26 @@ + + + + + +Compilers Preferences
+PDE validates and flags potential problems on plug-in, feature and update site manifest files, as well as extension point schemas.
+Syntactic problems are flagged as errors, while the severity level for each potential semantic problem is customizable and can be set to Error, Warning or Ignore.
+For more information, refer to the following documents:
+-
+
- Plug-in Compiler Preferences +
- Extension Point Schema Compiler Preferences +
- Feature and Update Site Compiler Preferences +
Related references
+PDE Preferences + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/editors.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/editors.htm new file mode 100644 index 0000000000..6d1204fd7f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/editors.htm @@ -0,0 +1,37 @@ + + + + + +Editors Preferences
+Syntax coloring for the source pages that are embedded in PDE editors can be customized on the
+
+
+Window > Preferences... > Plug-in Development > Editors
+ preference page. A Preview pane is available to show the changes made before they are applied. Changes take effect on editors only after you press Apply or OK.
XML Highlighting Preference
+The XML Highlighting tab allows you to set the color and font for comments, constant strings, processing instructions, tags and text.
+To customize the font and color for each element, select the element in the the left viewer and make changes using the buttons located on the right. The Preview pane automatically updates to reflect the changes you make.
+This preference affects all plug-in development and user assistance editor source pages.
+
MANIFEST.MF Highlighting Preference
+The Manifest Highlighting tab allows you to specify the color and font for the assignment operators, attributes, directives, headers, reserved OSGi headers and attribute values.
+To customize the font and color for each element, select the element in the left viewer and make changes using the buttons located on the right. The Preview pane automatically updates to reflect the changes you make.
+The MANIFEST.MF source page of the plug-in editor is controlled by this preference.
+
Related references
+PDE Preferences + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/feature_compiler.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/feature_compiler.htm new file mode 100644 index 0000000000..7b8280f09f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/feature_compiler.htm @@ -0,0 +1,22 @@ + + + + + +Feature and Update Site Compiler Preferences
+Syntactic errors in feature.xml and site.xml files are flagged as errors by the PDE manifest compiler.
+Semantic problems such as references to a non-existent plug-in or feature are flagged with a Warning by default. The severity level of this problem can be raised to Error or lowered to Ignore.
+
Related references
+ PDE Compiler Preferences+ PDE Preferences + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/osgi_frameworks.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/osgi_frameworks.htm new file mode 100644 index 0000000000..d5b21db7ad --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/osgi_frameworks.htm @@ -0,0 +1,47 @@ + + + + + +
OSGi Frameworks Preferences
+ +You can configure the default OSGi Framework for new
+ OSGi Framework launchers
+ using the
+
+
+ Window > Preferences... > Plug-in Development > OSGi Frameworks preference page.
+
OSGi Framework Selection
+ +All available OSGi Frameworks are listed in the Installed OSGi Frameworks
+ table. To contribute an OSGi Framework, the plug-in containing the framework
+ implementation must contain an
+ org.eclipse.pde.ui.osgiFrameworks
+ extension.
+
To set a framework as the default for new + OSGi Framework launch + configurations, select the framework entry in the table and + click the Set as Default button. +
+ +Related references
+ PDE Preferences + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/plug_in_development.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/plug_in_development.htm new file mode 100644 index 0000000000..ca82530792 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/plug_in_development.htm @@ -0,0 +1,68 @@ + + + + + + +General Plug-in Development Preferences
+
General Settings
+Prompt before overwriting build.xml files while exporting - +When selected, a dialog will be opened before deleting your build.xml files when an export operation starts. +
+ +Update stale manifest files prior to launching - +This option only affects manifest files using automated management of dependencies. Prior to launching, the manifest files will be updated with any necessary dependency changes. This option is off by default as it decreases launch performance. +
+ +Prompt before deleting a target definition file - +When selected, a dialog will be opened before deleting a target definition file when a target definition is removed from the Target Platform preference page. +
+ +Include all plug-ins from target in Java workspace scope - +When selected, all the plug-ins from the active target platform will be added to the Java search scope. Adding plug-ins to the java search scope will allow the plug-in contents to show up when doing Java searches and using the Open Type Dialog. When this option is on, if any plug-in is removed from Java search, the preference will be turned off. +
+ +Show current target platform in status bar - +When selected, adds a new item to the window status bar displaying the name of the current target platform. The tooltip displayed when hovering over the text will display any errors in the target and double clicking on it will open the Target Platform preference page. +
+
Workspace plug-ins override target platform plug-ins with the same id - +When selected, workspace plug-ins override target platform plug-ins. If one or more versions of a plug-in is open in the workspace, then all plug-ins with the same plug-in id get removed from the target platform. When this option is off, all plug-in versions from workspace and target platform are being used. +
+ +Disable API analysis builder - +When selected, it disables API analysis builder totally. +
+ +Enable SWT reporting of non-disposed resources when creating a new launch configuration -
+Add -Dorg.eclipse.swt.graphics.Resource.reportNonDisposed=true to VM arguments when creating a new launch configuration.
+
Test plug-in detection
+If the regular expression specified here is not empty, it is applied to the plug-in project's name when creating a plug-in project or when using Update Classpath, and +if it matches, the source folders will be marked to contain test sources in the project's Java Build Path settings.
+The default value for this setting matches if the project's name ends with ".test" or ".tests" or if it contains ".tests."
A documentation of the regular expression syntax can be found in the Javadoc of java.util.regex.Pattern.
Plug-in presentation
+By default, whenever a plug-in or a feature is presented in the UI (i.e. in the outline view, Plug-ins view, editors, etc.), the label shows the plug-in or feature ID followed by the plug-in or feature version.
+The Plug-in presentation preference is a global setting that allows you to show an alternate label for plug-ins and features composed of the (translated) name of the plug-in or feature followed by the plug-in or feature version. Source plug-in are filtered from views by default. Selecting Show source plug-ins will make them visible in the UI.
+ +Workspace location for new Eclipse Application launch configurations
+When a new Eclipse Application launch configuration is created a workspace location is chosen for you. This preference allows a different default setting to be chosen. Selecting Use as workspace location will make whatever is written the default location. If Append launch configuration name to this location is selected the launch configuration name will be appended to the location.
+ +Workspace location for new JUnit Plug-in Test launch configurations
+When a new JUnit Plug-in Test launch configuration is created a workspace location is chosen for you. This preference allows a different default setting to be chosen. Selecting Use as workspace location will make whatever is written the default location. If Append launch configuration name to this location is selected the launch configuration name will be appended to the location.
+ +Related references
+ PDE Preferences + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/plugin_compiler.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/plugin_compiler.htm new file mode 100644 index 0000000000..a8e5521f91 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/plugin_compiler.htm @@ -0,0 +1,341 @@ + + + + + ++ Plug-in Compiler Preferences +
+ +
+ 
+
+ Syntactic errors in plugin.xml, fragment.xml and + MANIFEST.MF are all flagged as errors by the plug-in manifest + compiler. As for semantic problems in the plug-in manifests, the severity + for each problem category can be set to Error, Warning + or Ignore. +
+ + + + ++ Workspace vs. Project Settings +
+
+ The plug-in compiler preferences are set at a workspace level on the
+
+ Window >
+
+ Preferences... > Plug-in Development > Compilers
+ preference page and take effect on all plug-in projects in the workspace.
+
+ It is also possible to override the workspace-scope settings by having + compiler settings at the plug-in project level. To do so, select + Properties from the context menu of a plug-in project. + In the Properties dialog, project-level manifest + compiler settings can be customized on the Plug-in Development + > Plug-in Manifest Compiler preference page. +
+ +General Settings
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Required attributes not defined |
+ A required attribute in a plug-in file is missing |
+ Error |
+
Incompatible environment |
+ The plug-in's environment settings do not match the target platform's environment settings |
+ Warning |
+
Missing exported packages |
+ One or more packages in a java source folder are not included in the Export-Package manifest entry |
+ Ignore |
+
No automatic module name |
+ Automatic-Module-Name header (required for Java 9 compatibility) is not present in MANIFEST.MF. For details, see this link. |
+ Warning |
+
Build Settings
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Problems with 'source.<library>' entry |
+ Semantic problem with source entry |
+ Warning |
+
Problems with 'output.<library>' entry |
+ Semantic problem with output entry |
+ Warning |
+
Missing 'output.<library>' entry |
+ A source entry exists without matching output |
+ Ignore |
+
Problems with 'bin.includes' entry |
+ Semantic problem with binary includes entry |
+ Warning |
+
Problems with 'src.includes' entry |
+ Semantic problem with source includes entry |
+ Warning |
+
Missing or incompatible Java compliance properties |
+ Project has Java compliance settings without matching entry in build.properties |
+ Warning |
+
Missing project specific Java compiler settings |
+ Project has Java complier settings without matching entry in build.properties |
+ Ignore |
+
Missing or incorrect file encodings |
+ Project has file encoding settings without matching entry in build.properties |
+ Ignore |
+
Other problems with build.properties files |
+ Other problems not part of another setting |
+ Warning |
+
Versioning Settings
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Missing versions on required bundles |
+ A required bundle manifest entry does not have version restrictions |
+ Ignore |
+
Missing versions on exported packages |
+ An exported package manifest entry does not have a version specified |
+ Ignore |
+
Missing versions on imported packages |
+ An imported package manifest entry does not have version restrictions |
+ Ignore |
+
Bundle BREE lower than its dependencies |
+ At least one of the bundle's dependencies requires an execution environment that is higher than the bundle's current execution environment |
+ Warning |
+
Usage Settings
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Unresolved dependencies |
+ A plug-in dependency (required bundle or imported package) can not be found |
+ Error |
+
Unresolved extension points |
+ The provider for an extension point cannot be found |
+ Error |
+
Usage of internal extension points |
+ Providing an extension to an extension point that is marked as internal |
+ Warning |
+
Usage of deprecated atributes and elements |
+ Providing an extension that uses attributes or elements from an extension point that are marked as deprecated |
+ Warning |
+
Usage of non-externalized strings |
+ A plug-in is using a string that could be translated in plugin.properties |
+ Ignore |
+
Usage of service component without lazy activation policy |
+ Bundle manifest has a Service-Component without a Bundle-ActivationPolicy: lazy entry |
+ Warning |
+
References Settings
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Illegal elements |
+ Referencing an illegal element in an extension |
+ Warning |
+
Illegal atributes |
+ Referencing an illegal attribute in an extension |
+ Warning |
+
References to non-existent classes |
+ Referencing a class from an extension that does not exist in the project |
+ Warning |
+
References to discourage classes |
+ Referencing a class from an extension that has discouraged access warnings |
+ Warning |
+
References to non-existent resources |
+ References a resource from an extension that does not exist in the project |
+ Warning |
+
References to non-existent identifier attributes |
+ Referencing an identifier attribute that is not defined by a known extension |
+ Warning |
+
Non-obvious Problems
+The following is a brief explanation for some of the non-obvious + potential problems that are flagged by PDE: +
+-
+
+
-
+ + Non-negotiable Markers: ++ Some problems such as a missing plug-in ID, plug-in version, or + plug-in name render a plug-in invalid. Therefore, these problems are + flagged with a non-negotiable error marker and are not available for + configuration on this preference page. +
+
+
+
-
+ + Unresolved Dependencies: +An unresolved dependency is a dependency on a plug-in (in the + Require-Bundle MANIFEST.MF header) or on a + package (in the Import-Package MANIFEST.MF + header) where the plug-in or package in question does not exist. +
+
+
-
+ + Incompatible Environment: +A plug-in or fragment has an incompatible environment if it has + an Eclipse-PlatformFilter MANIFEST.MF header + whose value is not compatible with the current Target Environment + settings as they appear on the Plug-in Development > Target + Platform > Environment preference page. +
+
+
-
+ + Unresolved Extension Points: +An unresolved extension point is an extension point that does not + exist or whose contributing plug-in is unchecked on the Plug-in + Development > Target Platform preference page. Extensions + contributing to such an extension point are flagged. +
+
Related references
+ PDE Compiler Preferences+ PDE Preferences + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/preferences.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/preferences.htm new file mode 100644 index 0000000000..385f1dcc74 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/preferences.htm @@ -0,0 +1,32 @@ + + + + + +
Preferences
+PDE provides preference pages to allow the user to control many aspects of plug-in development including the target platform, editors and manifest compiler settings.
+The Plug-in Development preferences can be accessed via
+
+
+Window > Preferences... > Plug-in Development from the top level menu.
For details on plug-in development preferences, refer to the following documents:
+-
+
- General Plug-in Development Preferences +
- API Baselines +
- API Errors/Warnings +
- API Use Scans +
- Compiler Preferences +
- Editors Preferences +
- OSGi Frameworks Preferences +
- Target Platform Preferences +
Runtime Classpath
+When launching a runtime workbench, PDE must create the classpath for +your plug-ins. By default, all of your project's output folders will be placed on the classpath. This page allows you to +remove the output folders from the classpath.
+ +The selected folders will be added to the classpath. Deselect the folders you do not want included.
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/schema_compiler.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/schema_compiler.htm new file mode 100644 index 0000000000..8c30fd0854 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/schema_compiler.htm @@ -0,0 +1,28 @@ + + + + + +Extension Point Schema Compiler Preferences
+PDE validates extension point schemas and flags syntactic problems as errors. Optional features of the PDE schema builder include the real-time generation of reference documentation for schemas and the flagging of unmatched tags in the schema documentation.
+ +
HTML Document Generation Preference
+The HTML Document Generation preference gives the option to generate reference HTML documents from extension point schemas as soon as the schema is modified and saved. The location where the HTML documents are to be generated is customizable with the default location being a folder named doc at the root of the plug-in project.
+ +Unmatched Tags Preference
+The documentation portions of extension point schemas allow HTML tags. Missing closing tags for those HTML tags that require it may result in badly formatted HTML documentation. The PDE builder validates the documentation sections of extension schemas and flag unmatched tags with a Warning by default. The severity level of this problem can be raised to Error or lowered to Ignore.
+ +Related references
+ PDE Compiler Preferences+ PDE Preferences + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/preference_pages/target_platform.htm b/org.eclipse.pde.doc.user/guide/tools/preference_pages/target_platform.htm new file mode 100644 index 0000000000..2824054c5b --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/preference_pages/target_platform.htm @@ -0,0 +1,51 @@ + + + + + +
Target Platform Preferences
+The
+
+Window > Preferences... > Plug-in Development > Target Platform preference page allows you to manage a set of target definitions and select one as the active target platform. A target definition consists of a set of plug-ins and environment settings. The active target platform is used to build and launch your workspace plug-ins.
The preference page will list all known target definitions. Some target definitions will be saved with Eclipse preferences, but this page will also display target definitions found in the workspace and external definition files that have been opened in the workspace. Definitions in the workspace will have their workspace location displayed in brown next to the name. The target definition that is currently being used as the active target platform will be checked, marked "Active" and be bolded. Change the active target platform by checking a different target definition. Any changes made on this page, including editing of target definitions, will not be saved until OK or Apply is pressed.
+ +
The default target platform points to the Eclipse application you are currently running. It is marked with a special Eclipse icon. You can restore the default target platform at any time by pressing the Restore Defaults button.
+ +Reload can only be pressed if the active target platform is currently selected and hasn't been changed while the preference page is open. Pressing it will force the target definition to resolve, refreshing the contents of any directory locations and downloading any out of date plug-ins in site locations. It is helpful to reload if you have changed something in your target platform outside of Eclipse. Any problems with the target will be displayed in a dialog.
+ +Press Add to create a new target definition. The New Target Wizard will provide multiple options to create a new target.
+ +Press Edit to edit the selected target definition. This will open the Edit Target Wizard allowing you to edit all settings in the definition. You can also double click a target definition to edit it.
+ +Pressing Remove will delete the selected target definitions when OK or Apply is pressed. If you remove a target definition that is stored in your workspace, it will be deleted.
+ +Move allows you to move a target definition stored in the Eclipse preferences to the workspace. The Move Target Wizard will have you choose a location in your workspace and a file name ending in ".target". The new location will be displayed in grey beside the target name and will be applied when OK or Apply is pressed.
+ +
At the bottom of the page there is a Locations group. This table will display information about the currently selected target definition. It provides a quick way to see the contents of a target.
+ +For up to the minute target troubleshooting help see the Target Definitions Wiki Page.
+ +Related references
+PDE Preferences+New Target Wizard
+Edit Target Wizard
+Move Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/project_wizards/fragment_content.htm b/org.eclipse.pde.doc.user/guide/tools/project_wizards/fragment_content.htm new file mode 100644 index 0000000000..53d4b2894f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/project_wizards/fragment_content.htm @@ -0,0 +1,32 @@ + + + + + + +Fragment Content
+The Fragment Content wizard page allows you to customize the fragment properties and specify the fragment host.
+
Plug-in Properties
+A ID is mandatory and must comply with the plugin.dtd. It is recommended - but not mandatory - for the fragment ID to match the project name.
+A Version is mandatory and must be of the form major.minor.micro.qualifier (e.g. 1.3.0).
+A Name is the translatable presentation name of the fragment. This field is required.
+A Vendor is the translatable name of the fragment vendor. This field is optional.
+Execution Environment refers to the required execution environment (symbolic representation of a JRE) of your plug-in. This field is optional but recommended to be set.
+ +Host Plug-in
+A fragment must specify a host plug-in that it will add functionality to and the host version range that it requires.
+The host Plug-in ID must refer to the ID of a plug-in that already exists in the workspace or the target.
+The host Minimum Version and Maximum Version are of the form major.minor.micro.qualifier.
++
+
+ + diff --git a/org.eclipse.pde.doc.user/guide/tools/project_wizards/fragment_structure.htm b/org.eclipse.pde.doc.user/guide/tools/project_wizards/fragment_structure.htm new file mode 100644 index 0000000000..0b79642eea --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/project_wizards/fragment_structure.htm @@ -0,0 +1,37 @@ + + + + + + +
Fragment Project Structure
+The Project Structure wizard page allows you to specify the project name, location, settings and target.
+
Project Name
+When choosing a name for the fragment project, the reverse naming domain convention (e.g. com.example.abc) is recommended - but not enforced by PDE.
+ +Project Location
+The default location for the fragment project is a subdirectory nested inside the workspace location. To change the location, uncheck the Use default location checkbox and enter the location of your choice.
+ +Project Settings
+Whether or not a fragment project should be created as a Java project depends on whether the fragment will contribute code. Fragment projects that contribute code are housed inside a Java project. Other plug-ins, such as documentation plug-ins do not contribute code and can therefore be contained in simple projects.
+ +Eclipse vs. OSGi Framework
+The Eclipse vs. OSGi framework choice acts as pre-filter to determine what initial pages will be visible in the plug-in manifest editor when it opens.
+Since the extension registry is Eclipse-specific content, the Extensions and Extension Points pages of the manifest editor are visible only when the Eclipse version option is chosen.
+ +Equinox vs. Standard
+When targeting an OSGi framework, you have a choice between the Equinox and standard frameworks. The Equinox OSGi framework augments the MANIFEST.MF content with Eclipse-specific headers (e.g. Eclipse-LazyStart) and directives (e.g. x-friends). If you do not wish to use these Eclipse-specific headers and attributes, then choose the standard option.
+ +Working Sets
+For convenience, plug-in projects can easily be associated with working sets which are defined in the workbench.
+ + + diff --git a/org.eclipse.pde.doc.user/guide/tools/project_wizards/new_feature_patch.htm b/org.eclipse.pde.doc.user/guide/tools/project_wizards/new_feature_patch.htm new file mode 100644 index 0000000000..edc74df276 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/project_wizards/new_feature_patch.htm @@ -0,0 +1,37 @@ + + + + + + +Feature Patch
+The New Feature Patch creation wizard is available under
+ File > New > Project... > Plug-in Development > Feature Patch
+ from the top level menu.
Project Settings
+It is recommended to use the reverse domain naming convention (e.g. com.example.patch) for the Project name.
+The project Location field specifies the default location as a subdirectory nested inside the workspace location. The project location can be changed to any writable location by unchecking the Use default location checkbox and entering the location of choice.
+ +Feature Patch Properties
+A Patch ID is mandatory and must comply with the plugin.dtd.
+A Patch Name is the translatable presentation name of the patch. This field is required.
+A Patch Vendor is the translatable name of the patch vendor. This field is optional.
+ +Properties of Patched Feature
+The Feature ID, Feature Name and Feature Version of the feature being patched must be specified. These attributes must match those of a feature found in either the workspace or the target.
+ +Feature Patch Project Structure
+A feature patch has a standard feature project structure and can be edited using the PDE feature manifest editor.
+
Feature Project
+The New Feature Project creation wizard is available under
+ File > New > Project... > Plug-in Development > Feature Project
+ from the top level menu.
The creation of a feature project is a two-step process:
+-
+
- Define the feature properties +
- Select the plug-ins that make up the feature +
Feature Properties
+The Feature Properties wizard page allows you to specify the feature project name, location and main properties.
+
It is recommended to use the reverse domain naming convention (e.g. com.example.feature) for the project name.
+The project Location field specifies the default location as a subdirectory nested inside the workspace location. The project location can be changed to any writable location by unchecking the Use default location checkbox and entering the location of choice.
+A Feature ID is mandatory and must comply with the plugin.dtd.
+A Feature Version is mandatory and must be of the form major.minor.micro.qualifier (e.g. 1.3.0).
+A Feature Name is the translatable presentation name of the feature. This field is required.
+A Feature Vendor is the translatable name of the feature vendor. This field is optional.
+ +Plug-in Selection
+The Plug-in Selection wizard page lets you select the plug-ins and fragments that make up the feature content.
+
Feature Project Structure
+When a feature project is created, its manifest file will open in the PDE feature manifest editor and it will have the following structure:
+
Fragment Project
+The New Fragment Project creation wizard is available under
+ File > New > Project... > Plug-in Development > Fragment Project
+ from the top level menu.
The creation of a fragment project is a two-step process:
+ + +When a new fragment project is created, its manifest file will open in the PDE plug-in manifest editor and the project structure will be similar to the following:
+
If the fragment contributes extensions or extension points, the fragment project will have a fragment.xml file at its root.
+ + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/project_wizards/new_plugin_project.htm b/org.eclipse.pde.doc.user/guide/tools/project_wizards/new_plugin_project.htm new file mode 100644 index 0000000000..204dd5a43e --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/project_wizards/new_plugin_project.htm @@ -0,0 +1,28 @@ + + + + + + +Plug-in Project
+The New Plug-in Project creation wizard is available under
+ File > New > Project... > Plug-in Project from the top level menu.
The creation of a plug-in project is a three-step process:
+-
+
- Define the plug-in project structure +
- Specify the plug-in content +
- Add template extensions (optional) +
When the plug-in project is created, its manifest file will open in the PDE plug-in manifest editor and the project structure will be similar to the following:
+
New Project Creation Wizards
+During development, every plug-in, fragment, feature and update site is represented in the workspace by a single project. Each type of project is configured with special natures and builders to allow PDE to validate their manifest file(s).
+To help you create these projects, PDE provides new project creation wizards. These wizards are accessible via
+ File > New > Project... > Plug-in Development from the top level menu.
For details on individual wizards, refer to the following documents:
+-
+
- Plug-in Project +
- Plug-in from existing JAR archives +
- Fragment Project +
- Feature Project +
- Feature Patch +
- Update Site Project +
Update Site Project
+The New Update Site Project creation wizard is available under
+ File > New > Project... > Plug-in Development > Update Site Project
+ from the top level menu.
Project Settings
+The Project Name for the update site project can be any valid directory name.
+The project Location field specifies the default location as a subdirectory nested inside the workspace location. The project location can be changed to any writable location by unchecking the Use default location checkbox and entering the location of choice.
+ +Web Resources
+The Generate a web page listing all available features within the site option generates several web files that can provide an HTML index preview of the update site contents.
+The default location for the Web resources location is a web/ folder; but, this location can be overridden by the user.
+ +Update Site Project Structure
+When an update site project is created, its manifest file will open in the PDE site manifest editor. An Update site project has a site.xml file located at its root. If the option to create a web page is chosen in the wizard, the project will also contain a web/ folder and an index.html file located at its root.
+
Plug-in Content
+The Plug-in Content wizard page allows you to customize the plug-in data.
+
Plug-in Properties
+A ID is mandatory and must comply with the plugin.dtd. It is recommended - but not mandatory - for the plug-in ID to match the plug-in project name.
+A Version is mandatory and must be of the form major.minor.micro.qualifier (e.g. 1.3.0).
+A Name is the translatable presentation name of the plug-in. This field is required.
+A Vendor is the translatable name of the plug-in vendor. This field is optional.
+Execution Environment refers to the required execution environment (symbolic representation of a JRE) of your plug-in. This field is optional but recommended to be set.
+ +Plug-in Options
+An activator is a Java class that controls the plug-in's life cycle. It is only needed if you require to do work upon the startup or shutdown of your plug-in.
+The choice of whether the plug-in will make contributions to the UI affects the code generated for the activator:
+-
+
- If the plug-in is a UI plug-in, the activator class extends the org.eclipse.ui.plugin.AbstractUIPlugin class. +
- If the plug-in is headless (i.e. non-UI), the activator extends the org.eclipse.core.runtime.Plugin class. +
- If the plug-in is targeted for an OSGi framework, the activator implements the org.osgi.framework.BundleActivator interface. +
The choice of a UI vs. headless plug-in also controls what templates are available on the next wizard page.
+Adding API Analysis to the project will enable static analysis of API usage from the new project.
+ +Rich Client Application
+At a minimum, a rich client application requires a plug-in with an org.eclipse.core.runtime.applications extension. If branding is desired, an org.eclipse.core.runtime.products extension is required. By answering Yes to the question in the Rich Client Application section, you will be required to go to the Templates page where you can choose an RCP template that will generate all the required extensions.
++
+
+ + diff --git a/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_from_archives.htm b/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_from_archives.htm new file mode 100644 index 0000000000..68736425e8 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_from_archives.htm @@ -0,0 +1,56 @@ + + + + + + +
Plug-in From Existing JAR Archives
+The Plug-in from existing JAR archives wizard is available under
+ File > New > Project... > Plug-in Development > Plug-in from existing JAR archive
+ from the top level menu.
The creation of a plug-in project from existing JAR archives is a two-step process:
+-
+
- Select the JAR archives +
- Specify the plug-in properties +
JAR Selection
+The JAR Selection wizard page lists the JAR archives to be included in the plug-in.
+
The Add... button opens a dialog that lets you browse the workspace for JAR archives.
+The Add External... button opens a file dialog that lets you browse the file system for JAR archives.
+ +Plug-in Properties
+The Plug-in Properties wizard page allows you to specify the plug-in project settings, plug-in properties and target platform.
+
It is recommended to use the reverse domain naming convention (e.g. com.example.bundle) for the project name.
+The Location field specifies the default project location as a subdirectory nested inside the workspace location. The project location can be changed to any writable location by unchecking the Use default location checkbox and entering the location of choice.
+A Plug-in ID is mandatory and must comply with the plugin.dtd. It is recommended - but not mandatory - for the plug-in ID to match the project name.
+A Plug-in Version is mandatory and must be of the form major.minor.service (e.g. 1.3.0).
+A Plug-in Name is the translatable presentation name of the plug-in. This field is required.
+A Plug-in Vendor is the translatable name of the plug-in vendor. This field is optional.
+You can optionally use PDE to Analyze library contents and add dependencies. + PDE analyzes the contents of the libraries specified on the + Jar Selection page, looking for dependencies that may be + required by the plug-in project. These dependencies are then automatically + added to the Manifest. +
+ +Target Platform
+The Target Platform options are intended as a pre-filter that determines which pages of the manifest editor should be visible when the new plug-in project is created.
+For instance, the Extensions and Extension Points pages will be visible if the Eclipse version option is chosen but hidden if the an OSGi framework option is chosen.
+Also, the Package Visibility section in the Runtime page of the manifest editor will be hidden if the standard OSGi framework option is selected; since, this section offers Equinox-specific tooling.
+ +Unzipping JARs
+Whether the JARs should be zipped or unzipped depends on how you want to package the plug-in. If the plug-in is to be shipped as a single JAR - which is the recommended format as of Eclipse 3.1 - the individual JAR archives should be unzipped. If the plug-in is to be shipped as a flat directory, then the individual JAR archives should be left intact.
+ + + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_structure.htm b/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_structure.htm new file mode 100644 index 0000000000..7d6e6df75c --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_structure.htm @@ -0,0 +1,40 @@ + + + + + + +Plug-in Project Structure
+The Project Structure wizard page allows you to specify the project name, location, settings and target.
+
Project Name
+When choosing a name for the plug-in project, the reverse naming domain convention (e.g. com.example.abc) is recommended - but not enforced by PDE.
+ +Project Location
+The default location for the plug-in project is a subdirectory nested inside the workspace location. To change the location, uncheck the Use default location checkbox and enter the location of your choice.
+ +Project Settings
+Whether or not a plug-in project should be created as a Java project depends on whether the plug-in will contribute code. Most plug-ins do contribute code and should therefore be housed inside a Java project. Other plug-ins, such as documentation plug-ins do not contribute code and can therefore be contained in simple projects.
+ +Eclipse vs. OSGi Framework
+The Eclipse vs. OSGi framework choice controls the code generation options available on the Plug-in Content page as well as the list of templates available.
+Eclipse plug-ins are OSGi bundles that use the Eclipse extension registry. Most Eclipse plug-ins use this registry; since, it is available in the runtime layer. As a result, the Eclipse target is selected by default.
+If you do not intend to use the Eclipse extension registry, then you should use the OSGi framework option. If you select the OSGi framework option, you will not end up with dependencies on the runtime layer. Moreover, PDE will restrict the available templates and the code generated for you to the OSGi layer.
+ +Equinox vs. Standard
+When targeting an OSGi framework, you have a choice between the Equinox and standard frameworks. The Equinox OSGi framework augments the MANIFEST.MF content with Eclipse-specific headers (e.g. Eclipse-LazyStart, Eclipse-PlatformFilter) and directives (e.g. x-friends). If you do not wish to use these Eclipse-specific headers and attributes, then choose the standard option.
+ +Working Sets
+For convenience, plug-in projects can easily be associated with working sets which are defined in the workbench.
+ + + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_templates.htm b/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_templates.htm new file mode 100644 index 0000000000..e59e2ead3f --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/project_wizards/plugin_templates.htm @@ -0,0 +1,30 @@ + + + + + + +Templates
+PDE provides templates ranging in complexity and function for the platform's more popular extension points. Each template results in the generation of a fully-functional plug-in.
+The list of templates that you see on this wizard page varies depending on the choices you made on the Plug-in Structure and Plug-in Content wizard pages:
+-
+
- Java vs. simple project +
- UI vs. headless +
- Rich client application vs. regular plug-in +
Templates are customizable. For instance, the Plug-in with an editor template allows you to customize the XML editor name, class name, etc.
+
Contributing Templates
+To contribute templates to the New Plug-in Project creation wizard, refer to the org.eclipse.pde.ui.pluginContent extension point.
+ + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_arguments_tab.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_arguments_tab.htm new file mode 100755 index 0000000000..13efa1598d --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_arguments_tab.htm @@ -0,0 +1,37 @@ + + + + + +Arguments Tab
+ +The Arguments Tab in the Edit Target Wizard is used to set the default program and vm arguments for new PDE launch configurations. Arguments can also be edited on the Environment Page of the Target Editor.
+ +
+
+Pressing Variables will open the Variable Selection Wizard. You can browse through all known variables and get descriptions of what each does. Under the VM Arguments group you can also press Import. This will open the Import Arguments Dialog. You can use it to import vm arguments used in the configuration data of any installation locations you have added to your target definition.
+ +Related references
+Edit Target Wizard+Content Tab (Edit Target Wizard)
+Environment Tab (Edit Target Wizard)
+Arguments Tab (Edit Target Wizard)
+Implicit Dependencies Tab (Edit Target Wizard)
+Import Variables Dialog
+Target Platform Preference Page
+New Target Wizard
+Move Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_content_tab.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_content_tab.htm new file mode 100755 index 0000000000..95c389cce7 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_content_tab.htm @@ -0,0 +1,60 @@ + + + + + +Content Tab
+ +The Content Tab in the Edit Target Wizard is used to set a subset of plug-ins to include in the target platform. The tab displays a list of all plug-ins available in the target definition's locations. Only the plug-ins checked on this tab will be included. There are multiple ways to organize and filter the list. The target content can also be edited on the Content Page of the Target Editor.
+ +
Select / Deselect will check or uncheck the selected plug-ins.
+ +Select All / Deselect All will check or uncheck all plug-ins in the target definition.
+ +Add Required takes the set of currently checked plug-ins and determines all plug-ins required by them. This will also include any implicit dependencies set on this target. The required plug-ins will be checked in the list.
+ +Use the Show options along with the filter text box at the top of the list to filter what is shown in the list. Showing plug-ins will show any non-source plug-ins in the target, while showing source bundles will display any source. Even if a plug-in is filtered from the list, it may be included in the target. You can see a count of included plug-ins underneath the list.
+ +The Group By option is used to organize the list into different groups. The options are:
+-
+
- None - No grouping, plug-ins sorted by name +
- File Path - Grouped by the directory path the plug-ins are stored in on the local file system +
- Location - Grouped by the locations set on the locations tab +
Managing Content with Features
+ +On the right hand side, you can choose between two different modes to manage the content of the target. By default targets +are managed using a list of plug-ins. Selecting Features will change your target contents to a list of features.
+ +
You can select features in the same way as when managing by plug-ins. Add Required will select any features that the currently +selected features have in their include or require entries. If there are plug-ins in the target that do not belong to a +feature, they will be listed under the Other Plug-ins item and can be selected individually.
+ +Related references
+Edit Target Wizard+Locations Tab (Edit Target Wizard)
+Environment Tab (Edit Target Wizard)
+Arguments Tab (Edit Target Wizard)
+Implicit Dependencies Tab (Edit Target Wizard)
+Target Platform Preference Page
+New Target Wizard
+Move Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_environment_tab.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_environment_tab.htm new file mode 100755 index 0000000000..a6b2934b89 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_environment_tab.htm @@ -0,0 +1,38 @@ + + + + + +Environment Tab
+ +The Environment Tab in the Edit Target Wizard is used to set environment settings that affect how a target is compiled and run. The environment settings can also be edited on the Environment Page of the Target Editor.
+ +
+
+The Target Environment section has four settings that describe the system that this target is built for. If left blank, the settings for your current running environment are used. Changing these settings will affect how Software Site Locations resolve as well as how plug-ins are built and exported.
+ +You can specify a JRE or execution environment for this target definition in the Java Runtime Environment section. If you specify a specific JRE or EE here, when this target is set as the active target platform, your workspace default JRE will be changed.
+ +Related references
+Edit Target Wizard+Locations Tab (Edit Target Wizard)
+Content Tab (Edit Target Wizard)
+Arguments Tab (Edit Target Wizard)
+Implicit Dependencies Tab (Edit Target Wizard)
+Target Platform Preference Page
+New Target Wizard
+Move Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_implicit_tab.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_implicit_tab.htm new file mode 100755 index 0000000000..02dca28240 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_implicit_tab.htm @@ -0,0 +1,36 @@ + + + + + +Implicit Tab
+ +The Implicit Tab in the Edit Target Wizard is used to set the implicit dependencies of the target. Any plug-in marked as an implicit dependency will always be added as a required plug-in when PDE determines requirements. Implicit dependencies can also be edited on the Environment Page of the Target Editor.
+ +
+
+Pressing Add will open the Implicit Dependencies Selection Dialog allowing you to select one or more plug-ins from your target platform to add as implicit dependencies.
+ +Related references
+Edit Target Wizard+Locations Tab (Edit Target Wizard)
+Content Tab (Edit Target Wizard)
+Environment Tab (Edit Target Wizard)
+Arguments Tab (Edit Target Wizard)
+Target Platform Preference Page
+New Target Wizard
+Move Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_locations_tab.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_locations_tab.htm new file mode 100755 index 0000000000..8a16895f64 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_locations_tab.htm @@ -0,0 +1,45 @@ + + + + + +Locations Tab
+ +The Location Tab in the Edit Target Wizard is used to set the locations that provide the plug-ins included in the target definition. There are several types of locations, allowing for definitions to be constructed in different styles. Locations can also be edited on the Definition Page of the Target Editor.
+ +
+
+The locations in the target definition will be displayed in the list. Each type of location will have a different icon and text. If the target has been resolved the count of plug-ins will be displayed in blue (the number of plug-ins included from the Content Tab and the total number of plug-ins found. If there are problems resolving the target, they will be displayed underneath the location with the problem. The Show Plug-in Content option can be turned on to display the included plug-ins underneath each location.
+ +Pressing Add will open the Add Location Wizard. It will provide a choice of location types to add. Selecting a location and pressing Edit will open a location type specific wizard to view and modify the location.
+ +Related references
+Edit Target Wizard+Content Tab (Edit Target Wizard)
+Environment Tab (Edit Target Wizard)
+Arguments Tab (Edit Target Wizard)
+Implicit Dependencies Tab (Edit Target Wizard)
+Target Platform Preference Page
+Target Editor
+Add Location
+Directory Location
+Installation Location
+Add Feature Locations
+Edit Feature Location
+Software Site Location
+New Target Wizard
+Move Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_wizard.htm new file mode 100755 index 0000000000..2aa8b015ed --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/edit_target_wizard.htm @@ -0,0 +1,50 @@ + + + + + +Edit Target Wizard
+ +This wizard is used to edit Target Definitions. It is opened when a target definition on the Target Platform Preference Page is edited or a new definition is created. This wizard provides the same functionality as the Target Editor.
+ +
+
+The target definition can be given a name which will be used when displaying it on the Target Platform Preference Page. The other target settings are separated into tabs:
+-
+
- Locations - Provides the directories, installations and sites that will provide the plug-ins to include in the target +
- Content - Allows a subset of the plug-ins found in the locations to be included in the target. Numerous filtering options are provided for quick editing of the contents +
- Environment - Operating system, windowing system, execution environment and other environment settings that affect how your plug-ins are built and run +
- Arguments - Specify the default program and vm arguments to use when launching with this target +
- Implicit Dependencies - Add one or more plug-ins as implicit dependencies. In PDE, when there is an option to add required plug-ins (such as on the Content tab of this wizard), any plug-ins marked as implicit dependencies will always be treated as required +
Pressing Finish will save the changes to the target definition and close the wizard.
+ +Resolving Targets
+ +Before the contents of a target can be edited and before a target definition can be set as the active target platform it must be resolved. When a target definition is resolved, the definition's locations are searched for plug-ins. Depending on the type of locations in the target, this can involved searching a directory, reading the metadata for an installation, reading a feature, or downloading from a remote site. During resolution the Edit Target Wizard will become disabled and progress will be displayed. You can cancel the work, however you will not be able to edit the content of the target.
+ +For up to the minute target troubleshooting help see the Target Definitions Wiki Page.
+ +Related references
+Locations Tab (Edit Target Wizard)+Content Tab (Edit Target Wizard)
+Environment Tab (Edit Target Wizard)
+Arguments Tab (Edit Target Wizard)
+Implicit Dependencies Tab (Edit Target Wizard)
+Target Platform Preference Page
+New Target Wizard
+Move Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/implicit_plugin_selection_dialog.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/implicit_plugin_selection_dialog.htm new file mode 100755 index 0000000000..7ea8f652b2 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/implicit_plugin_selection_dialog.htm @@ -0,0 +1,27 @@ + + + + + +Implicit Dependencies Selection Dialog
+ +The Implicit Dependencies Selection Dialog allows you to browse through the plug-ins in your target and add one or more of them as implicit dependencies. This dialog is opened from the Implicit Dependencies Tab or the Environment Page.
+ +Related references
+Implicit Dependencies Tab (Edit Target Wizard)+Edit Target Wizard
+Environment Page (Target Editor)
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/import_arguments_dialog.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/import_arguments_dialog.htm new file mode 100755 index 0000000000..acfdb5da42 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/import_arguments_dialog.htm @@ -0,0 +1,31 @@ + + + + + +Import Arguments
+ +The Import Arguments dialog is used to copy the arguments used in installations in your target. Often, if you have an Eclipse installation in your target that requires certain vm arguments to launch, you will require the same arguments to launch. This dialog is accessed using the Arguments Tab or the Environment Page.
+ +
+
+To have any arguments available for import, you must have at least one installation in your Locations that uses vm arguments in its configuration.
+ +Related references
+Arguments Tab (Edit Target Wizard)+Edit Target Wizard
+Environment Page (Target Editor)
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/location_add_features_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_add_features_wizard.htm new file mode 100755 index 0000000000..0a9535733a --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_add_features_wizard.htm @@ -0,0 +1,40 @@ + + + + + +Add Feature Locations Wizard
+ +The Add Feature Locations Wizard is opened from the Add Location Wizard. Select a folder containing features (it can also contain a folder called "features"). All features found in the directory will be adde to the list. Check the features you want to add to your target. When Finish is pressed locations will be added to your target for each selected feature. The plug-ins in the features will be added to your target.
+ +
+
+When selecting a directory you can use the drop-down to see folders you have used previously. You can also use variables in the path such as $eclipse_home to make it easier to share your target definition.
+ +The option underneath the list to Use specific version of the features allows for more flexibility in the versions. When checked, the exact feature version as selected in the list will be added to the target and must always be available for the target to resolve correctly. By turning this option off, the target will use the most recent version of your feature that is found in the directory. If you change the contents of the directory the target can still resolve correctly as long as some version of the feature can be found.
+ +Once a feature has been added to the target, editing it will open the Edit Feature Location Wizard
+ +Related references
+Location Tab+Edit Target Wizard
+Definition Page
+Target Editor
+Add Location
+Directory Location
+Installation Location
+Edit Feature Location
+Software Site Location + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/location_add_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_add_wizard.htm new file mode 100755 index 0000000000..a0af73dc23 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_add_wizard.htm @@ -0,0 +1,44 @@ + + + + + +Add Location Wizard
+ +The Add Location Wizard is opened from the Location Tab or the Definition Page. It is used to add a new location to a target definition. On the first page you must select a type of location to add. Click once on a location type to select it and a description of that location type will be visible at the bottom of the wizard.
+ +
+
+By default four types of locations are available:
+-
+
- Software Site - Select software from an update site or p2 repository to add to the target. +
- Directory - Select a directory and all plug-ins found inside of it will be added. +
- Installation - Select the directory of an Eclipse installation or Eclipse based product. All plug-ins installed into the application will be added. +
- Features - Select one or more features from a directory and the plug-ins in those features will be added. +
- Target File - Select a target to be included inside the current target. +
Related references
+Location Tab+Edit Target Wizard
+Definition Page
+Target Editor
+Directory Location
+Installation Location
+Add Feature Locations
+Edit Feature Location
+Software Site Location +Target File Location + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_directory_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_directory_wizard.htm new file mode 100755 index 0000000000..132306efcd --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_directory_wizard.htm @@ -0,0 +1,38 @@ + + + + + +Directory Location Wizard
+ +The Directory Location Wizard is used to create and edit directory locations in target definitions. To create a new directory location use the Add Location Wizard available from the Location Tab or the Definition Page.
+ +Select a folder containing plug-ins (it can also contain a folder called "plugins"). All plug-ins found in the directory will be added to the target. When selecting a directory you can use the drop-down to see folders you have used previously. You can also use variables in the path such as $eclipse_home to make it easier to share your target definition.
+ +
+
+After selecting a directory, you can press Finish to add the location to your target or you can press Next to preview the location contents.
+ +Related references
+Location Tab+Edit Target Wizard
+Definition Page
+Target Editor
+Add Location
+Installation Location
+Add Feature Locations
+Edit Feature Location
+Software Site Location + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_feature_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_feature_wizard.htm new file mode 100755 index 0000000000..2a7c794aab --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_feature_wizard.htm @@ -0,0 +1,38 @@ + + + + + +Edit Feature Location Wizard
+ +The Edit Feature Location Wizard allows you to view the details of a feature location in your target definition. This wizard is opened from the Location Tab or the Definition Page.
+ +Feature ID is the identifying name of the feature.
+ +Feature Version is the version of the feature that is used. It may be unspecified, in which case the most recent version of the feature found in the directory is used.
+ +Location is the directory where the feature is found.
+ +Related references
+Location Tab+Edit Target Wizard
+Definition Page
+Target Editor
+Add Location
+Directory Location
+Installation Location
+Add Feature Locations
+Software Site Location + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_installation_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_installation_wizard.htm new file mode 100755 index 0000000000..e7cf5c4fa8 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_installation_wizard.htm @@ -0,0 +1,38 @@ + + + + + +Installation Location Wizard
+ +The Installation Location Wizard is used to create and edit installation locations in target definitions. To create a new installation location use the Add Location Wizard available from the Location Tab or the Definition Page.
+ +Select a folder containing an Eclipse installation or an Eclipse based products. If the installation uses a special configuration directory you can enter a specific location rather than use the default. When selecting a directory you can use the drop-down to see folders you have used previously. You can also use variables in the path such as $eclipse_home to make it easier to share your target definition.
+ +
+
+After selecting an installation directory, you can press Finish to add the location to your target or you can press Next to preview the location contents.
+ +Related references
+Location Tab+Edit Target Wizard
+Definition Page
+Target Editor
+Add Location
+Directory Location
+Add Feature Locations
+Edit Feature Location
+Software Site Location + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_site_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_site_wizard.htm new file mode 100755 index 0000000000..d38608f7bb --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_site_wizard.htm @@ -0,0 +1,50 @@ + + + + + +Software Site Location Wizard
+ +The Software Site Location Wizard is used to create and edit software site locations in target definitions. To create a new software site location use the Add Location Wizard available from the Location Tab or the Definition Page.
+ +
+
+Software Site Locations can point to software in a repository or update site. The site can be a remote url allowing for easy sharing. To start searching for software you must select a site. Use the drop-down to select a specific site or try using All Available Sites. You can also press Add or click the link to modify the available sites.
+ +If a single site is selected software will only be downloaded from that site. In addition, the site url will be stored in the target definition so it is available to others who open it.
+ +Once a site has been selected the software available from that site will be displayed in the list. Check one or more items to include in the target. To help you quickly find the software you are looking for, you can filter the list by typing in the filter text box, or change the options to Group by Category and Show Only the Latest Version. If you select an entry in the list, the details section will display more information about the software. Pressing Properties will display all information available about the selection.
+ +The Included Software options at the bottom of the wizard affect how the set of plug-ins to add to your target is determined. By default, all required software is included. This means that we find all plug-ins that are required by the software you selected. All of those plug-ins must be available at the site or sites you have selected. If any piece is missing, the target will fail to resolve and display an error explaining what requirement is missing. This is the recommended setting for most users because it will ensure that you get the complete set of plug-ins in your target. The environment settings of your target definition will be used when determining required plug-ins so that platform specific fragments will be included.
+ +The Include required software setting will search the site for any dependencies the selected items require. It is recommended that you leave this option on. If you are building a target that will not contain all dependencies or if the site is missing some required plug-ins, this option can be turned off. When off, any required plug-ins found at the site will be added, but no errors will be reported for missing items.
+ +If the option to include required software is turned off, the Include All Environments option will be available. Turning it on will result in all available environment specific plug-ins to be added to the target, rather than just the plug-ins that apply to your target's environment settings.
+ +The Include source if available option will search the software site for source for the content you have selected.
+ +Include configure phase is an advanced option to control whether the configure phase of the download operation will be run. The configure phase allows downloaded software to run additional operations. If this causes problems for your software site, this option can be turned off.
+ +Related references
+Location Tab+Edit Target Wizard
+Definition Page
+Target Editor
+Add Location
+Directory Location
+Installation Location
+Add Feature Locations
+Edit Feature Location
+ +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_target_reference_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_target_reference_wizard.htm new file mode 100755 index 0000000000..7b7306366d --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_edit_target_reference_wizard.htm @@ -0,0 +1,51 @@ + + + + + +Target File Location Wizard
+ +The Target File Location Wizard is used to create and edit references to other target locations in target definitions. +To create a new target file location use the Add Location Wizard available from the Location Tab or the Definition Page.
+ +You need to specify a valid URI for the target to include, this could be anything that could be converted to an URL later on and you can also use variables if desired. +Here are some examples on how it might be used: +
+-
+
- You could use a target from a remote location (e.g. github-repository using http-protocol) in your local IDE. +
- You could use a target deployed at a maven repository using the mvn:<groupid>:<artifactid>:<version> (this requires m2eclipse with PDE integration) +
- You could extend an existing local target +
- You could combine any of the above options +
+
+Press Finish to add the location to your target.
+ +
+
+Related references
+Location Tab+Edit Target Wizard
+Definition Page
+Target Editor
+Add Location
+Installation Location
+Directory Location
+Add Feature Locations
+Edit Feature Location
+Software Site Location + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/location_preview.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_preview.htm new file mode 100755 index 0000000000..bc62745e04 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/location_preview.htm @@ -0,0 +1,39 @@ + + + + + +Directory Location Wizard
+ +The Directory Location Wizard is used to create and edit directory locations in target definitions. To create a new directory location use the Add Location Wizard available from the Location Tab or the Definition Page.
+ +Select a folder containing plug-ins (it can also contain a folder called "plugins"). All plug-ins found in the directory will be added to the target. When selecting a directory you can use the drop-down to see folders you have used previously. You can also use variables in the path such as $eclipse_home to make it easier to share your target definition.
+ +
+
+After selecting a directory, you can press Finish to add the location to your target or you can press Next to preview the location contents.
+ +Related references
+Location Tab+Edit Target Wizard
+Definition Page
+Target Editor
+Add Location
+Directory Location
+Installation Location
+Add Feature Locations
+Edit Feature Location
+Software Site Location + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/move_target_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/move_target_wizard.htm new file mode 100755 index 0000000000..53d29a9b6a --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/move_target_wizard.htm @@ -0,0 +1,29 @@ + + + + + +Move Target Wizard
+ +This wizard moves a target definition stored in the Eclipse preferences to a file in the workspace. This wizard is accessed by pressing Move on the Target Platform Preference Page. You must choose a project or directory to create the file in and a filename. Target definition files must end in the file extension ".target".
+ +
+
+Related references
+Target Platform Preference Page+Edit Target Wizard
+New Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/target_shared/new_target_wizard.htm b/org.eclipse.pde.doc.user/guide/tools/target_shared/new_target_wizard.htm new file mode 100755 index 0000000000..eb805c5235 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/target_shared/new_target_wizard.htm @@ -0,0 +1,39 @@ + + + + + +New Target Wizard
+ +This wizard creates a new target definition that will be added to the Target Platform Preference Page. There are several options to initialize your target definition with data. The new target definition will be saved in the Eclipse preferences, to create a target definition in your workspace use the New Target Definition File Wizard.
+ +
+
+Four options are available to initialize your new target definition:
+-
+
- Nothing - Creates a target definition with no locations or other information set. +
- Default - Creates a target definition with the default settings. The default target uses the plug-ins, environment, and vm arguments of your currently running Eclipse application. +
- Current Target - Creates a target definition with all the same settings as your active target platform. +
- Template - Creates a target definition and copies settings from a contributed template via extension point. By default, two templates are available providing the basic setup for an RCP application.
+
After choosing an option press Next to open the Edit Target Wizard and finish creating the target definition.
+ +Related references
+Target Platform Preference Page+Edit Target Wizard
+Move Target Wizard
+Target Editor + +
Related concepts
+Target Definitions + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/views/image_browser_view.htm b/org.eclipse.pde.doc.user/guide/tools/views/image_browser_view.htm new file mode 100644 index 0000000000..1dceb093de --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/views/image_browser_view.htm @@ -0,0 +1,45 @@ + + + + + +Plug-in Image Browser
+The Plug-in Image Browser View shows information about images found inside plug-ins from your workspace or target platform.
+ +The view is available under
+
+Window > Show View > Other... > Plug-in Development > Plug-in Image Browser
+.
To view images, select a Source.
+-
+
- Target Platform - images from locations specified on +Window > Preferences > Plug-in Development > Target Platform preference page. +
- Running Application - images from plug-ins running in your current Eclipse installation. +
- Workspace - images from plug-in projects open in the workspace. +
By default the first 250 images will be loaded from the plug-ins and +displayed. Press Show More to display the next 250 images. To increase the +number of images displayed each time the button is pressed, change the Maximum images +setting. You can use the Show setting to filter the view to only display images of a +certain type such as icons or wizard banners.
+ +When an image is selected, information about the image will be displayed in the details section. +The reference url can easily be copied into extensions to reuse images from other plug-ins.
+ +Related references
+PDE Views+Target Platform Preference Page + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/views/plugin_dependencies.htm b/org.eclipse.pde.doc.user/guide/tools/views/plugin_dependencies.htm new file mode 100644 index 0000000000..ef0eb228f1 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/views/plugin_dependencies.htm @@ -0,0 +1,28 @@ + + + + + +
Plug-in Dependencies
+The Plug-in Dependencies view generates and displays caller and callee relationships from within the plug-in ecosystem defined. The view is available under
+
+Window > Show View > Other... > PDE > Plug-in Dependencies
+.
Callers
+The callers visualization shows all the plug-ins that require a certain plug-in. The visualization is available in both hierarchical and flat-table modes.
+
Callees
+The callees visualization shows all the plug-ins required by a certain plug-in. The visualization is available in both hierarchical and flat-table modes.
+
Plug-in Registry
+The Plug-in Registry view shows the state of all plug-ins in the running instance of Eclipse. The view is available under
+
+Window > Show View > Other... > Plug-in Development > Plug-in Registry
+.
State of the Plug-in
+For each plug-in in the running system, the view shows:
+-
+
- the plug-in ID and version +
- the plug-in state (e.g. active or inactive - Note: the active state is indicated by a green overlay icon) +
- the plug-in location +
- the plug-in runtime libraries +
- the plug-in dependencies +
- the plug-in extensions +
- the plug-in extension points it contributes +
- the plug-in services it consumes +
- the plug-in services it contributes +
Plug-in Filtering
+The Show Active Plug-ins Only menu item is a filter that removes all inactive plug-ins from the view. To re-add them, press the menu item again. This filtering action is also available from the view's toolbar drop down menu.
+ +The Show Extension Content Only menu item is a filter that only shows extension or extension points in the view. To show everything again, press the menu item again. This filtering action is also available from the view's toolbar drop down menu.
+ + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/views/plugins.htm b/org.eclipse.pde.doc.user/guide/tools/views/plugins.htm new file mode 100644 index 0000000000..3baf4fa654 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/views/plugins.htm @@ -0,0 +1,40 @@ + + + + + +Plug-ins
+The Plug-ins View shows a unified view of all the plug-ins you are developing in the workspace and the plug-ins that make up your target platform. The view is available under
+
+Window > Show View > Other... > Plug-in Development > Plug-ins
+.
Workspace Plug-ins
+A workspace plug-in is shown in the view with a yellow and blue project folder icon. Its contents are not shown because the view is not intended to duplicate the behaviour of the Navigator and Package Explorer views. Double-click on the plug-in to open its manifest file in the PDE plug-in manifest editor.
+ +Target Plug-ins
+A target plug-in is shown in the view with the regular blue and yellow plug-in icon (or purple and yellow, in the case of a fragment). If the plug-in is stored as a JAR, it is not expandable. Flat plug-ins, on the other hand, are expandable and you can browse their structure and content. Double-click on a plug-in JAR or one of the flat plug-in manifest files to open its manifest file in the PDE plug-in manifest editor.
+ +Actions
+Several useful actions are available from the context menu of selected plug-ins within the Plug-ins view:
+-
+
- Open Dependencies: opens the Plug-in Dependencies view to show hierarchical and tabular renderings of the selected plug-in's relationship to other plug-ins +
- Find References: finds all references to the selected plug-in by other plug-ins in the workspace and target platform and displayed the results in the Search view. +
- Importing: provides a quick way to import the selected plug-in into the workspace. +
- Add to Java Workspace Scope: adds the code found in the selected plug-in to the scope of the Java search engine without the need to import the plug-in. +
Filtering
+Several filters are available in the view's toolbar drop down menu to show and hide workspace and disabled target plug-ins.
+ + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/views/target_platform_state.htm b/org.eclipse.pde.doc.user/guide/tools/views/target_platform_state.htm new file mode 100755 index 0000000000..4bb27ec932 --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/views/target_platform_state.htm @@ -0,0 +1,35 @@ + + + + + +Target Platform State
+The Target Platform State View shows the current status of the resolver state in PDE.
+ +The view is available under
+
+Window > Show View > Other... > Plug-in Development > Target Platform State
+.
Any plug-ins displayed with a red X are currently unresolved. +Expand an unresolved plug-in to reveal the unsatisfied constraints which result in the unresolved status.
+When you open the children of a resolved plug-in, you will see its dependencies separated into imported packages and required bundles. +The child of each dependency is the plug-in which satisfies the particular dependency.
+
Related references
+Target Platform Preference Page+Target Editor + +
Related concepts
+Target Definitions + + + + diff --git a/org.eclipse.pde.doc.user/guide/tools/views/views.htm b/org.eclipse.pde.doc.user/guide/tools/views/views.htm new file mode 100644 index 0000000000..b3c18bb04c --- /dev/null +++ b/org.eclipse.pde.doc.user/guide/tools/views/views.htm @@ -0,0 +1,38 @@ + + + + + +Views
+PDE provides four views that help plug-in developers inspect different aspects of their development environment. These views can be opened via
+
+Window > Show View > Other... > Plug-in Development
+.
For detailed information on individual PDE views, refer to the following documents:
+-
+
- Plug-in Dependencies +
- Plug-in Image Browser +
- Plug-in Registry +
- Plug-ins +
- Target Platform State +
Plug-in Development Perspective
+The Plug-in Development perspective is designed to support efficient development and integration of plug-in projects.
+The perspective can be opened via
+
+Window > Open Perspective > Other... > Plug-in Development
+.
+Notices
++The material in this guide is Copyright (c) IBM Corporation and others 2000, 2020. +
++Terms and conditions regarding the use of this guide. +
+ + diff --git a/org.eclipse.pde.doc.user/pdeOptions.txt b/org.eclipse.pde.doc.user/pdeOptions.txt new file mode 100644 index 0000000000..513ddb1174 --- /dev/null +++ b/org.eclipse.pde.doc.user/pdeOptions.txt @@ -0,0 +1,117 @@ +-quiet +-encoding "UTF-8" +-charset "UTF-8" +-sourcepath "${eclipse.pde.build}/org.eclipse.pde.build/src +;${eclipse.pde.ui.apitools}/org.eclipse.pde.api.tools.annotations/src +;${eclipse.pde.ui.ui}/org.eclipse.pde.core/src +;${eclipse.pde.ui.ui}/org.eclipse.pde.launching/src +;${eclipse.pde.ui.ui}/org.eclipse.pde.ui/src" +-d reference/api +-classpath @rt@ +;${dependency.dir}/icu4j_*.jar +;${dependency.dir}/org.osgi.service.prefs_*.jar +;${dependency.dir}/org.osgi.service.event_*.jar +;${dependency.dir}/org.osgi.service.cm_*.jar +;${dependency.dir}/biz.aQute.bndlib_*.jar +;${eclipse.equinox.supplement}/${dot.classes} +;${eclipse.jdt.core}/org.eclipse.jdt.core/${dot.classes} +;${eclipse.jdt.debug}/org.eclipse.jdt.debug/jdi.jar +;${eclipse.jdt.debug}/org.eclipse.jdt.debug.ui/${dot.classes} +;${eclipse.jdt.debug}/org.eclipse.jdt.launching/${dot.classes} +;${eclipse.jdt.ui}/org.eclipse.jdt.junit/${dot.classes} +;${eclipse.jdt.ui}/org.eclipse.jdt.junit/junitsupport.jar +;${eclipse.jdt.ui}/org.eclipse.jdt.junit.core/${dot.classes} +;${eclipse.jdt.ui}/org.eclipse.jdt.ui/${dot.classes} +;${eclipse.pde.build}/org.eclipse.pde.build/${dot.classes} +;${eclipse.pde.ui.ui}/org.eclipse.pde.core/${dot.classes} +;${eclipse.pde.ui.ui}/org.eclipse.pde.launching/${dot.classes} +;${eclipse.pde.ui.ui}/org.eclipse.pde.ui/${dot.classes} +;${eclipse.platform.debug}/org.eclipse.core.variables/${dot.classes} +;${eclipse.platform.debug}/org.eclipse.debug.core/${dot.classes} +;${eclipse.platform.debug}/org.eclipse.debug.ui/${dot.classes} +;${eclipse.platform.resources.bundles}/org.eclipse.core.filesystem/${dot.classes} +;${eclipse.platform.resources.bundles}/org.eclipse.core.resources/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.core.boot/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.core.contenttype/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.core.jobs/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.core.runtime/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.core.runtime.content/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.core.runtime.jobs/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.core.runtime.preferences/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.e4.core.contexts/${dot.classes} +;${eclipse.platform.runtime.bundles}/org.eclipse.e4.core.services/${dot.classes} +;${eclipse.platform.swt.binaries.bundles}/org.eclipse.swt.win32.win32.x86_64/${dot.classes} +;${eclipse.platform.team.bundles}/org.eclipse.compare/${dot.classes} +;${eclipse.platform.team.bundles}/org.eclipse.compare.core/${dot.classes} +;${eclipse.platform.team.bundles}/org.eclipse.team.core/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.core.filebuffers/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.jface.text/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.search/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.text/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui.editors/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui.workbench.texteditor/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui.genericeditor/${dot.classes} +;${eclipse.platform.ua}/org.eclipse.help/${dot.classes} +;${eclipse.platform.ua}/org.eclipse.help.ui/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.core.commands/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.jface/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.e4.ui.ide/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui.forms/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui.ide/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui.views/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui.views.log/${dot.classes} +;${eclipse.platform.ui.bundles}/org.eclipse.ui.workbench/${dot.classes} +;${eclipse.platform.update}/org.eclipse.update.configurator/${dot.classes} +;${rt.equinox.bundles.bundles}/org.eclipse.equinox.common/${dot.classes} +;${rt.equinox.bundles.bundles}/org.eclipse.equinox.preferences/${dot.classes} +;${rt.equinox.bundles.bundles}/org.eclipse.equinox.registry/${dot.classes} +;${rt.equinox.framework.bundles}/org.eclipse.osgi/${dot.classes} +;${rt.equinox.framework.bundles}/org.eclipse.osgi.services/${dot.classes} +;${rt.equinox.framework.bundles}/org.eclipse.osgi.util/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.frameworkadmin/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.core/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.director/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.engine/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.garbagecollector/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.metadata/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.publisher.eclipse/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.repository/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.repository.tools/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.p2.touchpoint.eclipse/${dot.classes} +;${rt.equinox.p2.bundles}/org.eclipse.equinox.simpleconfigurator.manipulator/${dot.classes} + +-breakiterator +-use +-splitIndex + +-windowtitle "Eclipse PDE API Specification" +-doctitle "Eclipse PDE API Specification" +-header "Eclipse PDE2023-12 (4.30)" +-bottom "
Copyright (c) 2000, 2023 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs." +-link https://docs.oracle.com/en/java/javase/17/docs/api +-link https://docs.osgi.org/javadoc/osgi.core/8.0.0/ +-link https://docs.osgi.org/javadoc/osgi.enterprise/7.0.0/ +-linkoffline ./../../../org.eclipse.platform.doc.isv/reference/api ../org.eclipse.platform.doc.isv/reference/api +-linkoffline ./../../../org.eclipse.jdt.doc.isv/reference/api ../org.eclipse.jdt.doc.isv/reference/api +-tag 'noimplement:a:Restriction:' +-tag 'noextend:a:Restriction:' +-tag 'noreference:a:Restriction:' +-tag 'noinstantiate:a:Restriction:' +-tag 'nooverride:a:Restriction:' +-Xdoclint:reference,html,syntax +-Xmaxwarns 10000 +-Xmaxerrs 10000 + +org.eclipse.pde.api.tools.annotations +org.eclipse.pde.build +org.eclipse.pde.core +org.eclipse.pde.core.build +org.eclipse.pde.core.plugin +org.eclipse.pde.core.project +org.eclipse.pde.core.target +org.eclipse.pde.ui +org.eclipse.pde.ui.launcher +org.eclipse.pde.ui.target +org.eclipse.pde.ui.templates +org.eclipse.pde.launching diff --git a/org.eclipse.pde.doc.user/pde_basedirs.properties b/org.eclipse.pde.doc.user/pde_basedirs.properties new file mode 100644 index 0000000000..1558d3b055 --- /dev/null +++ b/org.eclipse.pde.doc.user/pde_basedirs.properties @@ -0,0 +1,23 @@ +dot.classes=@dot +dependency.dir=.. + +eclipse.pde.ui.apitools=.. +eclipse.pde.ui.ui=.. +eclipse.pde.build=.. +eclipse.jdt.core=.. +eclipse.jdt.debug=.. +eclipse.jdt.ui=.. +eclipse.platform.ant=.. +eclipse.platform.platform=.. +eclipse.platform.resources.bundles=.. +eclipse.platform.runtime.bundles=.. +eclipse.platform.swt.binaries.bundles=.. +eclipse.platform.swt.bundles=.. +eclipse.platform.team.bundles=.. +eclipse.platform.ui.bundles=.. +eclipse.platform.update=.. +rt.equinox.bundles.bundles=.. +rt.equinox.framework.bundles=.. +rt.equinox.p2.bundles=.. + +eclipse.equinox.supplement=../org.eclipse.equinox.supplement diff --git a/org.eclipse.pde.doc.user/plugin.properties b/org.eclipse.pde.doc.user/plugin.properties new file mode 100644 index 0000000000..45ea1494e1 --- /dev/null +++ b/org.eclipse.pde.doc.user/plugin.properties @@ -0,0 +1,12 @@ +############################################################################### +# Copyright (c) 2000, 2009 IBM Corporation and others. +# All rights reserved. This program and the accompanying materials +# are made available under the terms of the Eclipse Public License v1.0 +# which accompanies this distribution, and is available at +# http://www.eclipse.org/legal/epl-v10.html +# +# Contributors: +# IBM Corporation - initial API and implementation +############################################################################### +pluginName=PDE User Guide +providerName=Eclipse.org diff --git a/org.eclipse.pde.doc.user/plugin.xml b/org.eclipse.pde.doc.user/plugin.xml new file mode 100644 index 0000000000..b0b6dd824a --- /dev/null +++ b/org.eclipse.pde.doc.user/plugin.xml @@ -0,0 +1,75 @@ + + + + +
2023-12 (4.30) ]]>
PDE Tools
+Select the PDE Tools command to access helpful tools from the resulting fly-out menu.
+The menu can be found on:
+-
+
- Java Projects +
- Plug-in Projects +
- build.properties files +
- plugin.xml files +
- MANIFEST.MF files +
An example fly-out menu for the PDE Tools command. +
+
Related references
+API Tools Setup + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/actions/ref-apitooling-setup-action.htm b/org.eclipse.pde.doc.user/reference/api-tooling/actions/ref-apitooling-setup-action.htm new file mode 100644 index 0000000000..9f837ee5ad --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/actions/ref-apitooling-setup-action.htm @@ -0,0 +1,20 @@ + + + + + + + +API Tools Setup
+Select the API Tools Setup command [ 
] to start the API Setup wizard.
+
Related references
+API Tools Setup Wizard+PDE Tools Context Menu + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/actions/ref-compare-action.htm b/org.eclipse.pde.doc.user/reference/api-tooling/actions/ref-compare-action.htm new file mode 100644 index 0000000000..a00c3aa2a2 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/actions/ref-compare-action.htm @@ -0,0 +1,20 @@ + + + + + + + +
API Compare
+Select the Compare With > API Baseline... command to start the API Compare wizard.
++
Related references
+PDE Tools Context Menu+API Compare Wizard + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-ant-task.htm new file mode 100644 index 0000000000..89da9ca6c8 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-ant-task.htm @@ -0,0 +1,241 @@ + + + + + + + +
API Analysis Ant Task
+Purpose
+This task runs a complete API analysis of an API profile relative to a baseline - including API use, binary compatibility, and bundle version number validation. The profile is the current state of a product under development. The profile is compared to an API baseline for binary compatibility (usually the previous release of a product).
+The analysis does not include @since tag validation as all verification is performed on binary class files (source is not analyzed).
+ +Usage
+Description
+The name of the Ant task is: apitooling.analysis. To be used, the jar file apitooling-ant.jar has to be on the Ant
+classpath.
+<apitooling.analysis + baseline="..." + profile="..." + report="..." + filters="..." + excludelist="..." + includelist="..." + preferences="..." + debug="..." + eefile="..." + processunresolvedbundles="..." +/> ++
Parameters
+| Attribute | +Description | +Required | +
| baseline | +This attribute specifies the location of the reference baseline.
+ It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the +directory is which you can find the Eclipse executable. + The location is specified using an absolute path. + |
+Yes | +
| profile | +This attribute specifies the location of the current product or profile that you want to compare against the reference baseline.
+ +It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the +directory is which you can find the Eclipse executable. + The location is specified using an absolute path. + |
+Yes | +
| report | +Set the output location where the reports will be generated.
+ +Once the task is completed, reports are available in this directory using a structure similar to the filter root. A sub-folder is created +for each component that has problems to be reported. Each sub-folder contains a file called "report.xml". + A special folder called "allNonApiBundles" is also created in this folder which also contains a file called "report.xml". +This file lists all the bundles that are not using the API Tools nature. + There is also a "counts.xml" file created in the report directory that contains a summary of the problems found. + The location is specified using an absolute path. + |
+Yes | +
| filters | +Set the root directory of API filters to use during the analysis.
+ +The argument is the root directory of the .api_filters files that should be used to filter potential problems created by +the API Tools analysis. + The root is specified using an absolute path. + The root needs to contain the following structure: + + root + | + +-- component name (i.e. org.eclipse.jface) + | + +--- .api_filters ++ |
+No | +
| excludelist | +Set the exclude list location.
+ The exclude list location specifies a text file listing bundles to be excluded from the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, +all bundles are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example exclude list: + + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + org.eclipse.platform.doc.isv + org.eclipse.platform.doc.user + # NON-ECLIPSE BUNDLES + com.ibm.icu + com.jcraft.jsch + R:javax\..* + ... ++ |
+No | +
| includelist | +Set the include list location.
+ The include list location specifies a text file listing bundles to be included in the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, +all bundles are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example include list: + + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + R:org.eclipse.platform.doc.* + # NON-ECLIPSE BUNDLES + com.ibm.icu + com.jcraft.jsch + R:javax\..* + ... ++ |
+No | +
| preferences | +Set the preferences for the task.
+ +The preferences are used to configure problem severities. Problem severities have three possible values: Ignore, Warning, or Error. The set of problems detected is defined by corresponding problem preference keys in API tools. + The location is specified using an absolute path. If the given location doesn't exist, the preferences won't be set. + +Lines starting with '#' are ignored. The format of the preferences file looks like this: + + #Thu Nov 20 17:35:06 EST 2008 + ANNOTATION_ELEMENT_TYPE_ADDED_METHOD_WITHOUT_DEFAULT_VALUE=Ignore + ANNOTATION_ELEMENT_TYPE_CHANGED_TYPE_CONVERSION=Ignore + ANNOTATION_ELEMENT_TYPE_REMOVED_FIELD=Ignore + ANNOTATION_ELEMENT_TYPE_REMOVED_METHOD=Ignore + ANNOTATION_ELEMENT_TYPE_REMOVED_TYPE_MEMBER=Warning + API_COMPONENT_ELEMENT_TYPE_REMOVED_API_TYPE=Ignore + API_COMPONENT_ELEMENT_TYPE_REMOVED_TYPE=Ignore + CLASS_ELEMENT_TYPE_ADDED_METHOD=Error + CLASS_ELEMENT_TYPE_ADDED_RESTRICTIONS=Ignore + CLASS_ELEMENT_TYPE_ADDED_TYPE_PARAMETER=Ignore + CLASS_ELEMENT_TYPE_CHANGED_CONTRACTED_SUPERINTERFACES_SET=Ignore + ... ++The keys can be found in org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes. + |
+No | +
| debug | +Set the debug value.
+ The possible values are: true, false
+Default is false.
+ |
+No | +
| eefile | +Set the execution environment file to use.
+ By default, an execution environment file corresponding to a JavaSE-1.6 execution environment is used. + The format of the file is described in this wiki page. + The file is specified using an absolute path. + |
+No | +
| processunresolvedbundles | +Set whether bundles with resolver errors should be analyzed.
+ If set, bundles that have resolver errors (such as missing dependencies) will be included in the analysis. +The errors may affect the results so a list of resolver errors is included in the xml output and +warnings will be added to the html during report conversion. + The possible values are: true, false
+Default is true.
+ |
+No | +
Examples
+ ++ <apitooling.analysis + baseline="D:\eclipse\3.4.1\eclipse" + profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz" + report="D:\reports\xml" + filters="D:\filters" + excludelist="D:\exclude_list_external.txt" + preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs" + debug="true" + /> ++
This will run the task creating report.xml files inside the folder D:\reports\xml.
+It will use the exclude list and the .api_filter files located in D:\exclude_list_external.txt and
+D:\filters to reduce the number of problems to report.
Problem severities will be generated as specified by D:\tests_api\org.eclipse.pde.api.tools.prefs.
Since debug is enabled, some debug tracing will show up in the Ant console.
+ +Related references
+API Freeze Ant Task +File Generation Ant Task +
API Use Ant Task +
Analysis Report Conversion Ant Task +
API Freeze Report Conversion Ant Task +
API Use Report Conversion Ant Task +
API Deprecation Ant Task +
API Deprecation Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm new file mode 100644 index 0000000000..4480eb6808 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm @@ -0,0 +1,163 @@ + + + + + + + +
+ API Tools Analysis Report Conversion Ant Task +
++ Purpose +
+ +
+ This task converts XML reports created by the
+ apitooling.analysis Ant task into HTML files.
+
+ Usage +
++ Description +
+ +
+ The name of the Ant task is:
+ apitooling.analysis_reportconversion. To be
+ used, the jar file apitooling-ant.jar has to be
+ on the Ant classpath.
+
+<apitooling.analysis_reportconversion
+ xmlfiles="..."
+ htmlfiles="..."
+ debug="..."
+/>
+
+ + Parameters +
+ +| + Attribute + | ++ Description + | + ++ Required + | +
| + xmlfiles + | +
+
+ Set the location where the xml reports are
+ retrieved. + + The location is set using an absolute path. + |
+ + Yes + | +
| + htmlfiles + | +
+ Set the location where the html reports are
+ generated. + + If not set, the html files are created in the same folder + as the xml files. + + + The location is set using an absolute path. + |
+ + No + | +
| + debug + | + +
+ Set the debug value. + + The possible values are: true,
+ false+ Default is false.
+ |
+
+ + No + | +
+ Examples +
+
+ <apitooling.analysis_reportconversion
+ xmlfiles="D:\reports\xml"
+
+ htmlfiles="D:\reports\html"
+ debug="true"
+ />
+
+
+ This will create an index.html inside the folder
+ D:\reports\html. A report for each bundle will
+ be created inside a sub-folder of
+ D:\reports\html. Each sub-folder will contain a
+ report.html.
+
+ Since debug is enabled, some debug tracing will show up in + the Ant console. +
+Related references
+ Analysis Ant Task+ File Generation Ant + Task
+ API Use Ant Task
+ API Freeze Ant + Task
+ API Freeze + Report Conversion Ant Task
+ API Deprecation Ant + Task
+ API + Deprecation Report Conversion Ant Task
+ API Use Report + Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiconsumeruse-reportconversion-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiconsumeruse-reportconversion-ant-task.htm new file mode 100755 index 0000000000..92a2bae81b --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiconsumeruse-reportconversion-ant-task.htm @@ -0,0 +1,227 @@ + + + + + + + +
+ API Consumer Use Report Conversion Ant Task +
++ Purpose +
+ +
+ This task converts the XML report created by the
+ apitooling.apiuse Ant task into HTML files. The
+ HTML report organizes references by the bundle that consumes
+ the reference (i.e. contains the code that references the
+ api/type).
+
+ Usage +
++ Description +
+ +
+ The name of the Ant task is:
+ apitooling.apiconsumeruse_reportconversion. To
+ be used, the jar file apitooling-ant.jar has to
+ be on the Ant classpath.
+
+ <apitooling.apiconsumeruse_reportconversion
+ xmlfiles="..."
+ htmlfiles="..."
+ xsltfile="..."
+ filterpatterns="..."
+ tofilterpatterns="..."
+ debug="..."
+ />
+
+ + Parameters +
+| + + Attribute + | ++ Description + | ++ Required + + | +
| + xmlfiles + | +
+ This attribute specifies the location of the xml files to
+ convert. + + + The location is specified using an absolute path. + |
+ + Yes + | +
| + htmlfiles + | + +
+ This attribute specifies the location of the html files
+ to generate. + + The location is specified using an absolute path. + |
+ + Yes + | +
| + xsltfile + | +
+ This attribute specifies the location of an XSLT file to
+ be used to generate the reference details pages in a
+ desired ordering. + + A default XSLT file is available in the + apitooling-ant.jar JAR file.+ + + The location is specified using an absolute path. + |
+ + No + | +
| + filterpatterns + | + +
+ This attribute specifies a comma separated listing of
+ regular expression patterns used to prune references
+ from matching name patterns from the final
+ report. + + The pattern must be a well-formatted regular expression + as defined + here. + |
+
+ + No + | +
| + tofilterpatterns + | +
+ This attribute specifies a comma separated listing of
+ regular expression patterns used to prune references
+ to matching name patterns from the final
+ report. + + + The pattern must be a well-formatted regular expression + as defined + here. + |
+ + No + | +
| + debug + | +
+ Set the debug value. + + The possible values are: true,
+ false+ + Default is false.
+ |
+ + No + | +
+ Examples +
+ +
+ <apitooling.apiuse_reportconversion
+ xmlfiles="/eclipse/apiuse-both/XML"
+ htmlfiles="/eclipse/apiuse-both/HTML"
+ xsltfile="/eclipse/references.xsl"
+ debug="true"
+
+ />
+
+
+ This will run the task creating *.html files
+ inside the folder /eclipse/apiuse-both/HTML
+ corresponding to the folder structure of the XML file
+ location
+
+ + If debug is enabled, some debug tracing will show up in the + Ant console. +
+Related references
+ API Use Report + Conversion Ant Task+ Analysis Ant Task
+ File Generation Ant + Task
+ API Use Ant Task
+ API Freeze Ant + Task
+ API Deprecation Ant + Task
+ API + Deprecation Report Conversion Ant Task
+ Analysis + Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-ant-task.htm new file mode 100644 index 0000000000..0ac0f4b689 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-ant-task.htm @@ -0,0 +1,187 @@ + + + + + + + +
API Freeze Ant Task
+Purpose
+This task identifies APIs that have been added, modified, or removed relative to an API baseline. +This task is intended to validate no API changes occur after an API freeze.
+Usage
+Description
+The name of the Ant task is: apitooling.apifreeze. To be used, the jar file apitooling-ant.jar has to be on the Ant
+classpath.
+<apitooling.apifreeze + baseline="..." + profile="..." + report="..." + excludelist="..." + includelist="..." + debug="..." + eefile="..." + processunresolvedbundles="..." +/> ++
Parameters
+| Attribute | +Description | +Required | +
| baseline | +This attribute specifies the location of the reference baseline.
+ It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the +directory is which you can find the Eclipse executable. + The location is specified using an absolute path. + |
+Yes | +
| profile | +This attribute specifies the location of the current product or profile that you want to compare against the reference baseline.
+ +It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the +directory is which you can find the Eclipse executable. + The location is specified using an absolute path. + |
+Yes | +
| report | +Set the name of the report file to be generated.
+ It should be specified using an absolute path. + This must be a file location, not a directory. + |
+Yes | +
| excludelist | +Set the exclude list location.
+ The exclude list location specifies a text file listing bundles to be excluded from the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. In addition, this task supports listing members in the include +and exclude lists. The include list seeds the set of bundles and members to be analyzed (when omitted, +all bundles and members are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example exclude list: + +# ECLIPSE MEMBERS +org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object; +# ECLIPSE BUNDLES +org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_ERROR +org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_WARNING +org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_ELCL_COLLAPSEALL +# NON-ECLIPSE BUNDLES +com.ibm.icu +R:javax\..* +... ++ |
+No | +
| includelist | +Set the include list location.
+ The include list location specifies a text file listing bundles to be included in the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. In addition, this task supports listing members in the include +and exclude lists. The include list seeds the set of bundles and members to be analyzed (when omitted, +all bundles and members are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example include list: + +# ECLIPSE MEMBERS +org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object; +# ECLIPSE BUNDLES +org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_ERROR +org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_WARNING +org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_ELCL_COLLAPSEALL +# NON-ECLIPSE BUNDLES +com.ibm.icu +R:javax\..* +... ++ |
+No | +
| debug | +Set the debug value.
+ The possible values are: true, false
+Default is false.
+ |
+No | +
| eefile | +Set the execution environment file to use.
+ By default, an execution environment file corresponding to a JavaSE-1.6 execution environment is used. + The format of the file is described in this wiki page. + The file is specified using an absolute path. + |
+No | +
| processunresolvedbundles | +Set whether bundles with resolver errors should be analyzed.
+ If set, bundles that have resolver errors (such as missing dependencies) will be included in the analysis. +The errors may affect the results so a list of resolver errors is included in the xml output and +warnings will be added to the html during report conversion. + The possible values are: true, false
+Default is true.
+ |
+No | +
Examples
+ ++ <apitooling.apifreeze + baseline="D:\eclipse\3.4.1\eclipse" + profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz" + report="D:\report\report.xml" + excludelist="D:\exclude_list.txt" + debug="true" + /> ++
This will run the task creating report.xml inside the folder D:\report.
+It will use the exclude list D:\exclude_list_external.txt to reduce the number of problems to report.
Since debug is enabled, some debug tracing will show up in the Ant console.
+ +Related references
+Analysis Ant Task +File Generation Ant Task +
API Use Ant Task +
Analysis Report Conversion Ant Task +
API Freeze Report Conversion Ant Task +
API Deprecation Ant Task +
API Deprecation Report Conversion Ant Task +
API Use Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm new file mode 100644 index 0000000000..1a0464a470 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm @@ -0,0 +1,162 @@ + + + + + + + +
+ API Tools API Freeze Report Conversion Ant Task +
++ Purpose +
+ +
+ This task converts the XML report created by the
+ apitooling.apifreeze Ant task into an HTML file.
+
+ Usage +
++ Description +
+ +
+ The name of the Ant task is:
+ apitooling.apifreeze_reportconversion. To be
+ used, the jar file apitooling-ant.jar has to be
+ on the Ant classpath.
+
+<apitooling.apifreeze_reportconversion
+ xmlfile="..."
+ htmlfile="..."
+ debug="..."
+/>
+
+ + Parameters +
+ +| + Attribute + | ++ Description + | + ++ Required + | +
| + xmlfile + | +
+
+ This attribute specifies the location of the xml file to
+ convert. + + The location is specified using an absolute path. + This must be a file location, not a directory. + |
+ + Yes + | +
| + htmlfile + | +
+ This attribute specifies the location of the html file to
+ generate. + + If not set, the html file name is retrieved from the xml + file name by replacing ".xml" in ".html". + + + The location is specified using an absolute path. + This must be a file location, not a directory. + |
+ + No + | +
| + debug + | +
+ Set the debug value. + + The possible values are: true,
+ false+ + Default is false.
+ |
+ + No + | +
+ Examples +
+ +
+ <apitooling.apifreeze_reportconversion
+ xmlfile=="D:\report\report.xml"
+ debug="true"
+ />
+
+
+ This will run the task creating report.html
+
+ inside the folder D:\report as the htmlfile
+ attribute is not set.
+
+ Since debug is enabled, some debug tracing will show up in + the Ant console. +
+Related references
+ Analysis Ant Task+ File Generation Ant + Task
+ API Use Ant Task
+ AAPI Freeze Ant + Task
+ Analysis + Report Conversion Ant Task
+ API Deprecation Ant + Task
+ API + Deprecation Report Conversion Ant Task
+ API Use Report + Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-ant-task.htm new file mode 100755 index 0000000000..85b472dd79 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-ant-task.htm @@ -0,0 +1,347 @@ + + + + + + + +
+ API Use Migration Ant Task +
++ Purpose +
+ ++ This task takes a given API use scan and tries to re-resolve + it within a given candidate product release and reports any + unresolved references. +
++ Usage +
++ Description +
+
+
+ The name of the Ant task is:
+ apitooling.apimigration. To be used, the jar
+ file apitooling-ant.jar has to be on the Ant
+ classpath.
+
+ <apitooling.apimigration
+ candidate="..."
+ usescan="..."
+ scopepattern="..."
+ referencepattern="..."
+ excludelist="..."
+ includelist="..."
+ report="..."
+ debug="..."
+ />
+
+ + Parameters +
+| + Attribute + | ++ Description + | ++ Required + + | +
| + candidate + | +
+ This attribute specifies the product you want to use as
+ the migration candidate.
+ + It can be a .zip, .jar, .tgz, .tar.gz file, or a + directory that corresponds to the Eclipse installation + folder. This is the directory is which you can find the + Eclipse executable. + + + |
+ + Yes + | +
| + usescan + | +
+
+ This attribute specifies the product use scan you want to
+ compare to the migration candidate. + + The usescan is specified using an absolute path to the + root of the use scan. + |
+ + Yes + | +
| + scopepattern + | +
+ This attribute specifies the regular expression pattern
+ used to build the scope of elements to search for
+ references from in the product location. + + The pattern must be a well-formatted regular expression + as defined + here. + |
+
+ + No + | +
| + referencepattern + | +
+ Set the regular expression pattern used to build the
+ scope of elements to search for references to in the
+ product location. + + + The pattern must be a well-formatted regular expression + as defined + here. + |
+ + No + | +
| + excludelist + | +
+ Set the exclude list location. + + The exclude list location specifies a text file listing + bundles to be excluded from the analysis. By default all + bundles in the profile are analyzed. The include and + exclude list attributes can be used to selectively + include and exclude bundles. The include list seeds the + set of bundles to be analyzed (when omitted, all bundles + are included), and the exclude list is then applied. Each + line of the file specifies one of: +
+ The location is specified using an absolute path. + Following is an example exclude list: + +# EXCLUDED BUNDLES +R:org\.eclipse\..*\.doc\..* +... ++ |
+
+ + No + | +
| + includelist + | +
+ Set the include list location. + + + The include list location specifies a text file listing + bundles to be included in the analysis. By default all + bundles in the profile are analyzed. The include and + exclude list attributes can be used to selectively + include and exclude bundles. The include list seeds the + set of bundles to be analyzed (when omitted, all bundles + are included), and the exclude list is then applied. Each + line of the file specifies one of: +
+ The location is specified using an absolute path. + + Following is an example include list: + +# INCLUDED BUNDLES +R:org\.eclipse\..* +... ++ |
+ + No + | +
| + + report + | +
+ Set the output location where the reports will be
+ generated. + + Once the task is completed, reports are available in this + directory using a hierarchical structure. A sub-folder is + created for each component that has another bundle that + references it. Each sub-folder contains a file called + "[bundlename].xml". Within this folder is another + sub-folder (named "[referencing bundle name].xml") for + each bundle that references the bundle of the containing + folder. Inside the referencing bundle folder is one of + three sub-folders (API, PRIVATE or OTHER) which contain + type, method or field references of that kind. + + Two other special files are written into the report + directory, which are "not_searched.xml" and + "no_apidescription.xml" and they contain information + about bundles from the baseline that were not search for + usage information and those that did not have an + .api_description files in them, respectively. + + + The location is specified using an absolute path. + + For example: + + root + | + +-- "not_searched.xml" + +-- "no_apidescription.xml" + +-- bundle name with usage + | + +--referencing bundle name + | + +-- [API or PRIVATE or OTHER] + | + +--[type_ or method_ or field_]references.xml ++ |
+ + + Yes + | +
| + debug + | +
+ Set the debug value. + + + The possible values are: true,
+ false+ Default is false.
+ |
+ + No + | + +
+ Examples +
+
+ <apitooling.apimigration
+ candidate="/eclipse/sdk3.5"
+ usescan="/eclipse/scans/sdk3.4"
+
+ scopepattern=".*"
+ referencepattern="org\.eclipse.*"
+ excludelist="D:\exclude_list_external.txt"
+ report="/eclipse/apimigration/xml"
+ debug="true"
+
+ />
+
+
+ This will run the task creating *.xml files
+ inside the folder /eclipse/apimigration/xml. The
+ task will re-resolve all references in the
+ usescan location - defined by the regular
+ expression .* - against the candidate product
+ whose identifier begins with org.eclipse (defined by the
+ org\.eclipse.* regular expression). It will use
+ the exclude list file located in
+ D:\exclude_list_external.txt to reduce the
+ number of problems to report.
+
+ If debug is enabled, some debug tracing will show up in the + Ant console. +
+Related references
+ API Freeze Ant + Task+ File Generation Ant + Task
+ Analysis + Report Conversion Ant Task
+ API Freeze + Report Conversion Ant Task
+ API Deprecation Ant + Task
+ API + Deprecation Report Conversion Ant Task
+ API Use Report + Conversion Ant Task
+ API Use + Migration Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm new file mode 100755 index 0000000000..af359af31b --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm @@ -0,0 +1,228 @@ + + + + + + + +
+ API Use Migration Report Conversion Ant Task +
++ Purpose +
+ +
+ This task converts the XML report created by the
+ apitooling.apimigration Ant task into HTML
+ files.
+
+ Usage +
++ Description +
+ +
+ The name of the Ant task is:
+ apitooling.apimigration_reportconversion. To be
+ used, the jar file apitooling-ant.jar has to be
+ on the Ant classpath.
+
+<apitooling.apimigration_reportconversion
+ xmlfiles="..."
+ htmlfiles="..."
+ xsltfile="..."
+ filterpatterns="..."
+ tofilterpatterns="..."
+ debug="..."
+ />
+
+ + Parameters +
+| + + Attribute + | ++ Description + | ++ Required + + | +
| + xmlfiles + | +
+ This attribute specifies the location of the xml files to
+ convert. + + + The location is specified using an absolute path. + |
+ + Yes + | +
| + htmlfiles + | + +
+ This attribute specifies the location of the html files
+ to generate. + + The location is specified using an absolute path. + |
+ + Yes + | +
| + xsltfile + | +
+ This attribute specifies the location of an XSLT file to
+ be used to generate the reference details pages in a
+ desired ordering. + + A default XSLT file is available in the + apitooling-ant.jar JAR file.+ + + The location is specified using an absolute path. + |
+ + No + | +
| + filterpatterns + | + +
+ This attribute specifies a comma separated listing of
+ regular expression patterns used to prune references
+ from matching name patterns from the final
+ report. + + The patterns must be a well-formatted regular expression + as defined + here. + |
+
+ + No + | +
| + tofilterpatterns + | +
+ This attribute specifies a comma separated listing of
+ regular expression patterns used to prune references
+ to matching name patterns from the final
+ report. + + + The pattern must be a well-formatted regular expression + as defined + here. + |
+ + No + | +
| + debug + | +
+ Set the debug value. + + The possible values are: true,
+ false+ + Default is false.
+ |
+ + No + | +
+ Examples +
+ +
+ <apitooling.apimigration_reportconversion
+ xmlfiles="/eclipse/apimigration-both/XML"
+ htmlfiles="/eclipse/apimigration-both/HTML"
+ xsltfile="/eclipse/references.xsl"
+ debug="true"
+
+ />
+
+
+ This will run the task creating *.html files
+ inside the folder
+ /eclipse/apimigration-both/HTML corresponding to
+ the folder structure of the XML file location
+
+ + If debug is enabled, some debug tracing will show up in the + Ant console. +
+Related references
+ Analysis Ant Task+ File Generation Ant + Task
+ API Use Ant Task
+ API Use Report + Conversion Ant Task
+ API Use Migration Ant + Task
+ API Freeze Ant + Task
+ API Deprecation Ant + Task
+ API + Deprecation Report Conversion Ant Task
+ Analysis + Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-ant-task.htm new file mode 100644 index 0000000000..082f31d255 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-ant-task.htm @@ -0,0 +1,264 @@ + + + + + + + +
API Use Ant Task
+Purpose
+This task runs a complete search of a given baseline to create a report of API usage.
+The analysis does not include bundles that are not API Tools enabled.
+ +Usage
+Description
+The name of the Ant task is: apitooling.apiuse. To be used, the jar file apitooling-ant.jar has to be on the Ant
+classpath.
+<apitooling.apiuse + location="..." + scopepattern="..." + referencepattern="..." + report="..." + considerinternal="..." + considerapi="..." + considerillegaluse="..." + apipatterns="..." + internalpatterns="..." + archivepatterns="..." + excludelist="..." + includelist="..." + filters="..." + debug="..." +/> ++
Parameters
+| Attribute | +Description | +Required | +
| location | +
+ This attribute specifies the location of the current product you want to search for API usage.
+ + It can be a .zip, .jar, .tgz, .tar.gz file, or a directory containing a product or a collection of bundles. + + The location is specified using an absolute path. |
+ Yes | +
| scopepattern | +
+ This attribute specifies a regular expression pattern used to select what bundles in the location will be searched.
+
+ + For example, the following would only scan for API usage in Eclipse bundles: + org.eclipse.*+ + The pattern must be a well-formatted regular expression as + defined here. + |
+ No | +
| referencepattern | +
+ This attribute specifies a regular expression pattern used to filter the search results. Only API usage that references
+ a bundle matching the filter will be reported.
+ + For example, the following would only report usage that references code in JDT: + org.eclipse.jdt.*+ + The pattern must be a well-formatted regular expression as + defined here. + |
+ No | +
| report | +Set the output location where the reports will be generated.
+ + Once the task is completed, reports are available in this directory using a hierarchical structure. A sub-folder is created + for each component that has another bundle that references it. Each sub-folder contains a file called "[bundlename].xml". Within + this folder is another sub-folder (named "[referencing bundle name].xml") for each bundle that references the bundle of the containing folder. + Inside the referencing bundle folder is one of three sub-folders (API, PRIVATE or OTHER) which contain type, method or field references of that kind. + + Three other special files are written into the report directory, which are "counts.xml", "not_searched.xml" and "no_apidescription.xml" and they contain + information about the number of references found, bundles from the baseline that were not search for usage information and those that did not have an + .api_description files in them, respectively. + + The location is specified using an absolute path. + + For example: + + root + | + +-- "not_searched.xml" + +-- "no_apidescription.xml" + +-- "counts.xml" + +-- bundle name with usage + | + +--referencing bundle name + | + +-- [API or PRIVATE or OTHER] + | + +--[type_ or method_ or field_]references.xml ++ |
+ Yes | +
| considerinternal | +If internal references should be considered during the search.
+ Default is false. |
+ No | +
| considerapi | +If API references should be considered during the search.
+ Default is false. |
+ No | +
| considerillegaluse | +If illegal API use references should be considered during the search.
+ Default is false. |
+ No | +
| apipatterns | +A comma separated list of package name patterns (regular expressions) to consider as API packages.
+ By default API descriptions are used in the scanned bundles, but this can be used to + override or add API packages. |
+ No | +
| internalpatterns | +A comma separated list of package name patterns (regular expressions) to consider as private packages.
+ By default API descriptions are used in the scanned bundles, but this can be used to + override or add private packages. |
+ No | +
| archivepatterns | +A comma separated list of archive identifiers to ignore during the scan.
+ An archive identifier is of the form: [bundle id]:[path to archive]. |
+ No | +
| excludelist | +
+ Set the exclude list location.
+ The exclude list location specifies a text file listing bundles to be excluded from the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, +all bundles are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example exclude list: + +# EXCLUDED BUNDLES +R:org\.eclipse\..*\.doc\..* +... + |
+ No | +
| includelist | +
+ Set the include list location.
+ The include list location specifies a text file listing bundles to be included in the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, +all bundles are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example include list: + +# INCLUDED BUNDLES +R:org\.eclipse\..* +... ++ |
+ No | +
| filters | +Set the root directory of API filters to use during the use scan.
+ +The argument is the root directory of the .api_filters files that should be used to filter references. + +The .api_filters files specify specific problems to ignore during api analysis. During the use scan, the problem filters +will be converted to a list of references that will be filtered from the use scan results. + + The root is specified using an absolute path. + The root needs to contain the following structure: + + root + | + +-- component name (i.e. org.eclipse.jface) + | + +--- .api_filters ++ |
+No | +
| debug | +Set the debug value.
+ The possible values are: true, false
+ Default is false. |
+ No | +
Examples
++ <apitooling.apiuse + location="/eclipse/eclipse.tar.gz" + scopepattern=".*" + referencepattern="org\.eclipse.*" + report="/eclipse/apiuse-both/XML" + considerinternal="true" + considerapi="true" + considerillegaluse="true" + archivepatterns="org.eclipse.test.bundle:/libs/contributed.jar" + excludelist="D:\exclude_list_external.txt" + debug="true" + /> ++
This will run the task creating *.xml files inside the folder /eclipse/apiuse-both/XML.
+The task will search all bundles in the product location - defined by the regular expression .* - searching
+for all references to any bundles whose identifier begins with org.eclipse (defined by the org\.eclipse.* regular expression).
+It will use the exclude list file located in D:\exclude_list_external.txt to reduce the number of problems to report.
While scanning, any class files found in the /libs/contributed.jar archive inside org.eclipse.test.bundle will be ignored.
+If debug is enabled, some debug tracing will show up in the Ant console.
+ +Related references
+API Freeze Ant Task +File Generation Ant Task +
Analysis Report Conversion Ant Task +
API Freeze Report Conversion Ant Task +
API Deprecation Ant Task +
API Deprecation Report Conversion Ant Task +
API Use Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm new file mode 100644 index 0000000000..d3172fc9aa --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm @@ -0,0 +1,227 @@ + + + + + + + +
+ API Use Report Conversion Ant Task +
++ Purpose +
+ +
+ This task converts the XML report created by the
+ apitooling.apiuse Ant task into HTML files. The
+ HTML report will organize the references by the bundle that
+ produced them (i.e. the bundle that contains the api/type
+ being referenced).
+
+ Usage +
++ Description +
+ +
+ The name of the Ant task is:
+ apitooling.apiuse_reportconversion. To be used,
+ the jar file apitooling-ant.jar has to be on the
+ Ant classpath.
+
+<apitooling.apiuse_reportconversion
+ xmlfiles="..."
+ htmlfiles="..."
+ xsltfile="..."
+ filterpatterns="..."
+ tofilterpatterns="..."
+ debug="..."
+ />
+
+ + Parameters +
+| + + Attribute + | ++ Description + | ++ Required + + | +
| + xmlfiles + | +
+ This attribute specifies the location of the xml files to
+ convert. + + + The location is specified using an absolute path. + |
+ + Yes + | +
| + htmlfiles + | + +
+ This attribute specifies the location of the html files
+ to generate. + + The location is specified using an absolute path. + |
+ + Yes + | +
| + xsltfile + | +
+ This attribute specifies the location of an XSLT file to
+ be used to generate the reference details pages in a
+ desired ordering. + + A default XSLT file is available in the + apitooling-ant.jar JAR file.+ + + The location is specified using an absolute path. + |
+ + No + | +
| + filterpatterns + | + +
+ This attribute specifies a comma separated listing of
+ regular expression patterns used to prune references
+ from matching name patterns from the final
+ report. + + The pattern must be a well-formatted regular expression + as defined + here. + |
+
+ + No + | +
| + tofilterpatterns + | +
+ This attribute specifies a comma separated listing of
+ regular expression patterns used to prune references
+ to matching name patterns from the final
+ report. + + + The pattern must be a well-formatted regular expression + as defined + here. + |
+ + No + | +
| + debug + | +
+ Set the debug value. + + The possible values are: true,
+ false+ + Default is false.
+ |
+ + No + | +
+ Examples +
+ +
+ <apitooling.apiuse_reportconversion
+ xmlfiles="/eclipse/apiuse-both/XML"
+ htmlfiles="/eclipse/apiuse-both/HTML"
+ xsltfile="/eclipse/references.xsl"
+ debug="true"
+
+ />
+
+
+ This will run the task creating *.html files
+ inside the folder /eclipse/apiuse-both/HTML
+ corresponding to the folder structure of the XML file
+ location
+
+ + If debug is enabled, some debug tracing will show up in the + Ant console. +
+Related references
+ API + Consumer Use Report Conversion Ant Task+ Analysis Ant Task
+ File Generation Ant + Task
+ API Use Ant Task
+ API Freeze Ant + Task
+ API Deprecation Ant + Task
+ API + Deprecation Report Conversion Ant Task
+ Analysis + Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiusescan-problems-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiusescan-problems-ant-task.htm new file mode 100644 index 0000000000..4df397bab7 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiusescan-problems-ant-task.htm @@ -0,0 +1,185 @@ + + + + + + + +
API Use Scan Problems Ant Task
+Purpose
+This task resolves the API Use Scans in a profile relative to a baseline. It reports the references to the types, methods and fields which are now missing from the profile.
+Usage
+Description
+The name of the Ant task is: apitooling.apiusescanproblems. To be used, the jar file apitooling-ant.jar has to be on the Ant
+classpath.
+<apitooling.apiusescanproblems + profile="..." + report="..." + apiusescans="..." + excludelist="..." + includelist="..." + preferences="..." + debug="..." +/> ++
Parameters
+| Attribute | +Description | +Required | +
| profile | +This attribute specifies the location of the current product or profile that you want to resolved the API Use Scans against.
+ +It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the +directory is which you can find the Eclipse executable. + The location is specified using an absolute path. + |
+Yes | +
| report | +Set the output location where the reports will be generated.
+ +Once the task is completed, reports are available in this directory. A sub-folder is created +for each component that has problems to be reported. Each sub-folder contains a file called "report.xml". + The location is specified using an absolute path. + |
+Yes | +
| apiusescans | +This attribute specifies the comma-separated list of the locations of the API Use Scans that you want to check against the profile.
+ +It can be a .zip file or a directory that corresponds to the API Use Scan report. This is the directory is which you can find the XML folder in the Use Scan. + |
+Yes | +
| excludelist | +Set the exclude list location.
+ The exclude list location specifies a text file listing bundles to be excluded from the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, +all bundles are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example exclude list: + + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + org.eclipse.platform.doc.isv + org.eclipse.platform.doc.user + # NON-ECLIPSE BUNDLES + com.ibm.icu + com.jcraft.jsch + R:javax\..* + ... ++ |
+No | +
| includelist | +Set the include list location.
+ The include list location specifies a text file listing bundles to be included in the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, +all bundles are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example include list: + + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + R:org.eclipse.platform.doc.* + # NON-ECLIPSE BUNDLES + com.ibm.icu + com.jcraft.jsch + R:javax\..* + ... ++ |
+No | +
| preferences | +Set the preferences for the task.
+ +The preferences are used to configure problem severities. Problem severities have three possible values: Ignore, Warning, or Error. The set of problems detected is defined by corresponding problem preference keys in API tools. + The location is specified using an absolute path. If the given location doesn't exist, the preferences won't be set. + +Lines starting with '#' are ignored. The format of the preferences file looks like this: + + #Thu Nov 20 17:35:06 EST 2008 + API_USE_SCAN_TYPE_SEVERITY=Error + API_USE_SCAN_METHOD_SEVERITY=Error + API_USE_SCAN_FIELD_SEVERITY=Error ++The keys can be found in org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes. + |
+No | +
| debug | +Set the debug value.
+ The possible values are: true, false
+Default is false.
+ |
+No | +
Examples
+ ++ <apitooling.apiusescanproblems + profile="D:\eclipse\3.7\eclipse" + report="D:\reports\xml" + apiusescans="D:\APIUseScan\ProductOne,D:\APIUseScan\ProductTwo" + excludelist="D:\exclude_list_external.txt" + preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs" + debug="true" + /> ++
This will run the task creating report.xml files inside the folder D:\reports\xml. The types, methods and fields from the use scans
+will be resolved in the profile at D:\eclipse\3.7\eclipse and the missing ones will be reported.
+It will use the exclude list from the file D:\exclude_list_external.txt to reduce the number of bundles for which problems to report.
Problem severities will be generated as specified by D:\tests_api\org.eclipse.pde.api.tools.prefs.
Since debug is enabled, some debug tracing will show up in the Ant console.
+ +Related references
+API Analysis Ant Task +API Freeze Ant Task +
File Generation Ant Task +
API Use Ant Task +
Analysis Report Conversion Ant Task +
API Freeze Report Conversion Ant Task +
API Use Report Conversion Ant Task +
API Deprecation Ant Task +
API Deprecation Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiusescan-problems-reportconversion-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiusescan-problems-reportconversion-ant-task.htm new file mode 100644 index 0000000000..3f3bd1b7ce --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiusescan-problems-reportconversion-ant-task.htm @@ -0,0 +1,167 @@ + + + + + + + +
+ API Use Scan Problems Report Conversion Ant Task +
++ Purpose +
+ +
+ This task converts XML reports created by the
+ apitooling.apiusescanproblems Ant task into HTML
+ files.
+
+ Usage +
++ Description +
+ +
+ The name of the Ant task is:
+ apitooling.apiusescanproblem_reportconversion.
+ To be used, the jar file apitooling-ant.jar has
+ to be on the Ant classpath.
+
+<apitooling.apiusescanproblem_reportconversion
+ xmlfiles="..."
+ htmlfiles="..."
+ debug="..."
+/>
+
+ + Parameters +
+ +| + Attribute + | ++ Description + | + ++ Required + | +
| + xmlfiles + | +
+
+ Set the location where the xml reports are
+ retrieved. + + The location is set using an absolute path. + |
+ + Yes + | +
| + htmlfiles + | +
+ Set the location where the html reports are
+ generated. + + If not set, the html files are created in the same folder + as the xml files. + + + The location is set using an absolute path. + |
+ + No + | +
| + debug + | + +
+ Set the debug value. + + The possible values are: true,
+ false+ Default is false.
+ |
+
+ + No + | +
+ Examples +
+
+ <apitooling.analysis_reportconversion
+ xmlfiles="D:\reports\xml"
+
+ htmlfiles="D:\reports\html"
+ debug="true"
+ />
+
+
+ This will create an index.html inside the folder
+ D:\reports\html. A report for each bundle will
+ be created inside a sub-folder of
+ D:\reports\html. Each sub-folder will contain a
+ report.html.
+
+ Since debug is enabled, some debug tracing will show up in + the Ant console. +
+Related references
+ API Use Scan + Problems Ant Task+ Analysis Ant Task
+ File Generation Ant + Task
+ API Use Ant Task
+ API Freeze Ant + Task
+ API Freeze + Report Conversion Ant Task
+ API Deprecation Ant + Task
+ API + Deprecation Report Conversion Ant Task
+ API Use Report + Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/compare-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/compare-ant-task.htm new file mode 100644 index 0000000000..63e9b0c934 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/compare-ant-task.htm @@ -0,0 +1,202 @@ + + + + + + + +
Compare Ant Task
+Purpose
+This task runs a complete comparison of an API profile relative to a baseline.
+ +Usage
+Description
+The name of the Ant task is: apitooling.compare. To be used, the jar file apitooling-ant.jar has to be on the Ant
+classpath.
+<apitooling.compare + baseline="..." + profile="..." + report="..." + excludelist="..." + includelist="..." + components="..." + visibility="..." + debug="..." +/> ++
Parameters
+| Attribute | +Description | +Required | +
| baseline | +This attribute specifies the location of the reference baseline.
+ It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the +directory is which you can find the Eclipse executable. + The location is specified using an absolute path. + |
+Yes | +
| profile | +This attribute specifies the location of the current product or profile that you want to compare against the reference baseline.
+ +It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the +directory is which you can find the Eclipse executable. + The location is specified using an absolute path. + |
+Yes | +
| report | +Set the output location where the report will be generated.
+ +Once the task is completed, the report called "compare.xml" is available in this directory. + The location is specified using an absolute path. + |
+Yes | +
| excludelist | +Set the exclude list location.
+ The exclude list location specifies a text file listing bundles to be excluded from the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, +all bundles are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example exclude list: + + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + org.eclipse.platform.doc.isv + org.eclipse.platform.doc.user + # NON-ECLIPSE BUNDLES + com.ibm.icu + com.jcraft.jsch + javax.servlet + javax.servlet.jsp + # Exclude all pde bundles + R:org\.eclipse\.pde\..* + ... ++The exclude list can contain regular expressions if the line starts with "R:". + |
+No | +
| includelist | +Set the include list location.
+ The include list location specifies a text file listing bundles to be included in the analysis. +By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to +selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, +all bundles are included), and the exclude list is then applied. +Each line of the file specifies one of: +
The location is specified using an absolute path. + Following is an example include list: + + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + org.eclipse.platform.doc.isv + org.eclipse.platform.doc.user + # NON-ECLIPSE BUNDLES + com.ibm.icu + com.jcraft.jsch + javax.servlet + javax.servlet.jsp + # Exclude all pde bundles + R:org\.eclipse\.pde\..* + ... ++ |
+No | +
| debug | +Set the debug value.
+ The possible values are: true, false
+Default is false.
+ |
+No | +
| components | +Set the components' list location.
+ The components' list contains all the components' names that must be compared. +If omitted, all components from the given baseline are compared. + The location is specified using an absolute path. + The format of the components' list file looks like this: + + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + org.eclipse.platform.doc.isv + org.eclipse.platform.doc.user + # Include all pde bundles + R:org\.eclipse\.pde\..* + ... ++The components' list can contain regular expressions if the line starts with "R:". + |
+No | +
| visibility | +Set the visibility value.
+ The possible values are: API, ALL
+Default is API.
+ |
+No | +
Examples
+ ++ <apitooling.compare + baseline="D:\eclipse\3.4.1\eclipse" + profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz" + report="D:\reports\xml" + excludelist="D:\exclude_list_external.txt" + debug="true" + /> ++
This will run the task creating compare.xml files inside the folder D:\reports\xml.
+It will use the exclude list to reduce the number of problems to report.
Since debug is enabled, some debug tracing will show up in the Ant console.
+ +Related references
+API Freeze Ant Task +File Generation Ant Task +
API Use Ant Task +
Analysis Report Conversion Ant Task +
API Freeze Report Conversion Ant Task +
API Use Report Conversion Ant Task +
API Deprecation Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-ant-task.htm new file mode 100755 index 0000000000..5471f59b9a --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-ant-task.htm @@ -0,0 +1,342 @@ + + + + + + + +
+ API Deprecation Ant Task +
++ Purpose +
+ ++ This task runs a complete API analysis of an API profile + relative to a baseline - looking only for members (classes, + fields, methods) that have been deprecated / un-deprecated. + The profile is the current state of a product under + development. The profile is compared to an API baseline for + deprecation changes (usually the previous release of a + product). +
++ Usage +
++ Description +
+
+
+ The name of the Ant task is:
+ apitooling.apideprecation. To be used, the jar
+ file apitooling-ant.jar has to be on the Ant
+ classpath.
+
+<apitooling.apideprecation
+ baseline="..."
+ profile="..."
+ report="..."
+ excludelist="..."
+ includelist="..."
+ debug="..."
+ eefile="..."
+/>
+
+ + Parameters +
+| + Attribute + + | ++ Description + | ++ Required + | +
| + baseline + | +
+ This attribute specifies the location of the reference
+ baseline. + + It can be a .zip, .jar, .tgz, .tar.gz file, or a + directory that corresponds to the Eclipse installation + folder. This is the directory is which you can find the + Eclipse executable. + + + The location is specified using an absolute path. + |
+ + Yes + | +
| + profile + | + +
+ This attribute specifies the location of the current
+ product or profile that you want to compare against the
+ reference baseline. + + It can be a .zip, .jar, .tgz, .tar.gz file, or a + directory that corresponds to the Eclipse installation + folder. This is the directory is which you can find the + Eclipse executable. + + The location is specified using an absolute path. + |
+ + + Yes + | +
| + report + | +
+ Set the output location where the reports will be
+ generated. + + + Once the task is completed, reports are available in this + directory using a structure similar to the filter root. A + sub-folder is created for each component that has + problems to be reported. Each sub-folder contains a file + called "report.xml". + + A special folder called "allNonApiBundles" is also + created in this folder which also contains a file called + "report.xml". This file lists all the bundles that are + not using the API Tools nature. + + The location is specified using an absolute path. + |
+ + + Yes + | +
| + excludelist + | +
+ Set the exclude list location. + + + The exclude list location specifies a text file listing + bundles to be excluded from the analysis. By default all + bundles in the profile are analyzed. The include and + exclude list attributes can be used to selectively + include and exclude bundles. In addition, this task + supports listing members in the include and exclude + lists. The include list seeds the set of bundles and + members to be analyzed (when omitted, all bundles and + members are included), and the exclude list is then + applied. Each line of the file specifies one of: +
+ The location is specified using an absolute path. + Following is an example exclude list: + + # ECLIPSE MEMBERS + org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object; + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + org.eclipse.platform.doc.isv + org.eclipse.platform.doc.user + # NON-ECLIPSE BUNDLES + com.ibm.icu + com.jcraft.jsch + javax.servlet + javax.servlet.jsp + ... +The exclude list can contain regular expressions if the line +starts with "R:". + |
+ + No + | + +
| + | ||
| + includelist + | +
+
+ Set the include list location. + + The include list location specifies a text file listing + bundles to be included in the analysis. By default all + bundles in the profile are analyzed. The include and + exclude list attributes can be used to selectively + include and exclude bundles. In addition, this task + supports listing members in the include and exclude + lists. The include list seeds the set of bundles and + members to be analyzed (when omitted, all bundles and + members are included), and the exclude list is then + applied. Each line of the file specifies one of: +
+ The location is specified using an absolute path. + Following is an example include list: + + # ECLIPSE MEMBERS + org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object; + # DOC BUNDLES + org.eclipse.jdt.doc.isv + org.eclipse.jdt.doc.user + org.eclipse.pde.doc.user + org.eclipse.platform.doc.isv + org.eclipse.platform.doc.user + # NON-ECLIPSE BUNDLES + com.ibm.icu + com.jcraft.jsch + javax.servlet + javax.servlet.jsp + ... ++ |
+ + + No + | +
| + debug + | +
+ Set the debug value. + + + The possible values are: true,
+ false+ Default is false.
+ |
+ + No + | + +
| + eefile + | +
+ Set the execution environment file to use. + + By default, an execution environment file corresponding + to a JavaSE-1.6 execution environment is used. + + + The format of the file is described in this wiki page. + + The file is specified using an absolute path. + |
+ + No + | + +
+ Examples +
+
+ <apitooling.apideprecation
+ baseline="D:\eclipse\3.4.1\eclipse"
+ profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"
+
+ report="D:\reports\xml"
+ excludelist="D:\exclude_list_external.txt"
+ debug="true"
+ />
+
+
+
+ This will run the task creating report.xml files
+ inside the folder D:\reports\xml. It will use
+ the exclude list to reduce the number of problems to report.
+
+ Since debug is enabled, some debug tracing will show up in + the Ant console. +
+Related references
+ API Freeze Ant + Task+ File Generation Ant + Task
+ API Use Ant Task
+ Analysis + Report Conversion Ant Task
+ API Freeze + Report Conversion Ant Task
+ API Use Report + Conversion Ant Task
+ API + Deprecation Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm new file mode 100755 index 0000000000..87310ec037 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm @@ -0,0 +1,157 @@ + + + + + + + +
+ API Deprecation Report Conversion Ant Task +
++ Purpose +
+ +
+ This task converts the XML report created by the
+ apitooling.apideprecation Ant task into HTML
+ files.
+
+ Usage +
++ Description +
+ +
+ The name of the Ant task is:
+ apitooling.apideprecation_reportconversion. To
+ be used, the jar file apitooling-ant.jar has to
+ be on the Ant classpath.
+
+<apitooling.apideprecation_reportconversion
+ xmlfile="..."
+ htmlfile="..."
+ debug="..."
+/>
+
+ + Parameters +
+ +| + Attribute + | ++ Description + | + ++ Required + | +
| + xmlfile + | +
+
+ This attribute specifies the location of the xml file to
+ convert. + + The location is specified using an absolute path. + |
+ + Yes + | +
| + htmlfile + | +
+ This attribute specifies the location of the html file to
+ generate. + If omitted, the html file name will be the given xml file + name where the extension is replaced with html. + + The location is specified using an absolute path. + |
+
+ + No + | +
| + debug + | +
+ Set the debug value. + + + The possible values are: true,
+ false+ Default is false.
+ |
+ + No + | + +
+ Examples +
+
+ <apitooling.apideprecation_reportconversion
+ xmlfile="/eclipse/deprecation/deprecation.xml"
+ debug="true"
+
+ />
+
+
+ This will run the task creating the
+ deprecation.html file inside the folder
+ /eclipse/deprecation.
+
+ If debug is enabled, some debug tracing will show up in the + Ant console. +
+ +Related references
+ Analysis Ant Task+ File Generation Ant + Task
+ API Use Ant Task
+ API Freeze Ant + Task
+ API Deprecation Ant + Task
+ Analysis + Report Conversion Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/filegeneration-ant-task.htm b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/filegeneration-ant-task.htm new file mode 100644 index 0000000000..5359d9624e --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/filegeneration-ant-task.htm @@ -0,0 +1,290 @@ + + + + + + + +
+ API Tools File Generation Ant Task +
++ Purpose +
+ ++ This task runs to generate all files required by API Tools + inside a binary bundle. This task is run during the Eclipse + builds or during the bundle export for all projects that have + an API Tools nature. +
+
+ Right now, only the file called .api_description
+ is created.
+
+ Usage +
+ ++ Description +
+
+ The name of the Ant task is:
+ apitooling.apigeneration. To be used, the jar
+ file apitooling-ant.jar has to be on the Ant
+ classpath.
+
+<apitooling.apigeneration
+ projectname="..."
+ project="..."
+ binary="..."
+ target="..."
+ encoding="..."
+ debug="..."
+/>
+
+ + Parameters +
+| + Attribute + | ++ Description + | ++ Required + + | +
| + projectname + | ++ Set the project name + | ++ + Yes + | +
| + project + | +
+ Set the project location. + + + This is the folder that contains all the source files for + the given project. + + The location is set using an absolute path. + |
+ + Yes + | +
| + binary + | +
+ Set the binary locations. + + This is a list of folders or jar files that contain all + the .class files for the given project. They are + separated by the platform path separator. Each entry must + exist. + + + They should be specified using absolute paths. + |
+ + Yes + | +
| + target + | + +
+ Set the target location. + + This is the folder in which the generated files are + generated. + + The location is set using an absolute path. + |
+ + + Yes + | +
| + encoding + | + +
+ Set the file encoding. + + This is the file encoding to use while reading source files during the generation. If an encoding is not + specified the system property file.encoding will be used.+ + The specified encoding is not checked to ensure it is valid in any way and an invalid encoding will cause + an UnsupportedEncodingException to be thrown from the Ant task.
+ |
+ + No + | +
| + debug + | +
+ Set the debug value. + + + The possible values are: true,
+ false+ Default is false.
+ |
+ + No + | + +
| + extramanifests + | +
+ Set the extra manifest files' locations. + + This is a list of extra MANIFEST.MF files' locations that + can be set to provide more api packages to scan. They are + separated by the platform path separator. Each entry must + exist. + + + If the path is not absolute, it will be resolved relative + to the current working directory. + + Jar files can be specified instead of MANIFEST.MF file. + If a jar file is specified, its MANIFEST.MF file will be + read if it exists. + |
+ + No + | +
| + extrasourcelocations + | +
+ Set the extra source locations. + + This is a list of locations for source files that will be + scanned. They are separated by the platform path + separator. Each entry must exist. + + + They should be specified using absolute paths. + |
+ + No + | +
| + allownonapiproject + | + +
+ Allow the task to run on non-API Tools enabled
+ projects. + + If this task is run on a project that does not have an + API Tools nature, no api_description file will be + generated as it is assumed that the project does not + support API Tools. In some cases there is a need to + generate the description file on projects without the + nature. Setting this parameter to true will cause the + task to not check for a nature. + |
+ + No + | +
+ Examples +
+
+ <apitooling.apigeneration
+ projectname="org.eclipse.jdt.core_3.5.0.v_927"
+ project="d:\eclipse\org.eclipse.jdt.core"
+ binary="d:\eclipse\org.eclipse.jdt.core\bin;d:\eclipse\org.eclipse.jdt.core\antbin"
+ target="d:\plugins\org.eclipse.jdt.core"
+ encoding="UTF-8"
+ allownonapiproject="true"
+ debug="true"
+ />
+
+
+
+ This will create a file called .api_description
+ inside the folder
+ d:\plugins\org.eclipse.jdt.core based on the
+ source contained in
+ d:\eclipse\org.eclipse.jdt.core and the .class
+ files contained in
+ d:\eclipse\org.eclipse.jdt.core\bin.
+
Related references
+ Analysis Ant Task+ API Freeze Ant + Task
+ API Use Ant Task
+ Analysis + Report Conversion Ant Task
+ API Freeze + Report Conversion Ant Task
+ API Deprecation Ant + Task
+ API + Deprecation Report Conversion Ant Task
+ API Use Report + Conversion Ant Task + + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/api_evolution.htm b/org.eclipse.pde.doc.user/reference/api-tooling/api_evolution.htm new file mode 100644 index 0000000000..12cd493b33 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/api_evolution.htm @@ -0,0 +1,120 @@ + + + + + + + + +
API Evolution
++
+ +API tooling is about controlling API Evolution and Version Numbering. +
+ +Read Achieving API Binary Compatibility for understanding the various incompatibilities. +
+ +The following API incompatibilities have been explained in more detail below : +
+ +Field Addition to Class
+Adding an API field to an API class that is extended by Clients is dangerous in two respects: +
+- It may break API contract compatibility similar to Evolving_Java-based_APIs#Example_4_-_Adding_an_API_method in case of name clashes. +
- It may cause linkage errors in case an instance (respectively static) field hides a static (respectively instance) field, see JLS8 13.4.8.
+ + ++ + This can not happen if all field declarations follow the usual naming conventions from JLS8 6.1 and classes only have API fields that are either +Example - Adding a Field to Class
+++ + +public class Base {String h = "Base";} +public class Derived extends Base { } + +public class Test { + public static void main(String[] args) { + String s = new Derived().h; + System.out.println(s); + } +} ++This program produces the output:
+ Base + +Suppose that a public static field h is added to
Derived: ++ + public class Derived extends Base { public static String h = "humongous"; } ++ +If
+Derivedis recompiled but notTest, then running the new binary with the existing binary forTestwill cause anIncompatibleClassChangeError. +Furthermore, if char type h is added to Derived instead, there would be compilation error.
+
- "static final" (and hence have a name that doesn't contain any lowercase letters), or +
- non-static and non-final (and hence have a name that contains a least one lowercase letter)
Apart from the binary compatibility issues, it is generally good software engineering practice that API classes should not expose any non-constant fields. +
+ +Field Addition to Interface
+ +Adding an API field to an API interface that is implemented by Clients is dangerous in two respects: +
+- It may break API contract compatibility similar to Evolving_Java-based_APIs#Example_4_-_Adding_an_API_method in case of name clashes. +
- It may cause linkage errors in case an instance (respectively static) field hides a static (respectively instance) field, see JLS8 13.4.8. This can not happen if all field declarations follow the usual naming conventions from JLS8 6.1 and classes only have API fields that are either
+
- "static final" (and hence have a name that doesn't contain any lowercase letters), or +
- non-static and non-final (and hence have a name that contains a least one lowercase letter)
Default Method Addition to Interface
+Adding a default method will break an existing client type if it already implements another interface that declares a default method with a matching signature, and the client type already refers to the default method from the other interface (except when using the Interface.super.method() notation). The added default method will cause an IncompatibleClassChangeError at run time, see JLS8 13.5.6. Furthermore, re-compiling the type will result in a compile error.
+
Example - Adding A Default Method
+
+
+API
+ public interface interfaceAPI {}
+
+Client Code
+ public interface clientInterface {
+ default void doSomething() {
+ System.out.println("Do something client...") ;
+ }
+}
+
+public class ClientCode implements clientInterface, interfaceAPI {
+ public static void main(String[] args) {
+ new ClientCode().doSomething();
+ }
+}
+
+ This program produces the output:
+ Do something client... +Suppose that a default method is added to interfaceAPI:
+
+public interface interfaceAPI {
+ default void doSomething() {
+ System.out.println("Do something API...");
+ }
+}
+
+ If interfaceAPI is recompiled but not ClientCode, then running the new binary with the existing binary for ClientCode will cause an IncompatibleClassChangeError.
+
Defining API Restrictions
+API Tools provides Javadoc tags to explicitly document and restrict the use of API. The following tables summarizes the Javadoc tags supported by each member and the semantics of each tag.
+A client refers to a plug-in or bundle that requires the bundle where the associated API is defined. Restrictions are not applied in the same bundle where API is defined. For example, a bundle that defines an interface as @noimplement is also allowed to provide an implementation of that interface.
+Supported Restriction Tags
+| + | Class | +Interface | +Enum | +Annotation | +Method | +Constructor | +Final Field |
+ Non-Final Field | +
|---|---|---|---|---|---|---|---|---|
@noimplement |
+ - |
+  |
+ - |
+ - |
+ - |
+ - |
+ - |
+ - |
+
@noextend |
+ |
+ |
+ - |
+ - |
+ - |
+ - |
+ - |
+ - |
+
@noinstantiate |
+ |
+ - |
+ - |
+ - |
+ - |
+ - |
+ - |
+ - |
+
@nooverride |
+ - |
+ - |
+ - |
+ - |
+ |
+ - |
+ - |
+ - |
+
@noreference |
+ |
+ |
+ |
+ |
+ |
+ |
+ - |
+ |
+
Restriction Semantics
+@noimplement |
+ Indicates that clients must not implement this interface. Any class using the implements keyword for the associated interface or parent of the associated interface where there is no implementing superclass will be flagged with problem. |
+
|---|---|
@noextend |
+ Indicates that clients must not extend this class or interface. Any class or interface using the extends keyword for the associated type will be flagged with a problem. |
+
@noinstantiate |
+ Indicates that clients must not instantiate this class. Any code that instantiates the associated class with any constructor will be flagged with a problem. |
+
@nooverride |
+ Indicates that clients must not redeclare this method. Any subclass that defines a method that overrides the associated method will be flagged with a problem. |
+
@noreference |
+ Indicates that clients must not reference this type (class, interface, enum, or annotation), method, constructor, or non-final field. Any code that directly invokes the associated method or constructor or references the associated non-final field will be flagged with a problem. +When the tag is used on a type, it behaves as though the tag was added to any of the types members. For example, adding the tag to class will flag any references to any methods or non-final fields from that class. |
+
Related tasks
+Setting up a baseline +Related references
+Javadoc @since tag Management+API Baselines Preferences
+API Errors and Warnings Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/api_since_tags.htm b/org.eclipse.pde.doc.user/reference/api-tooling/api_since_tags.htm new file mode 100644 index 0000000000..c1ce94c6e3 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/api_since_tags.htm @@ -0,0 +1,87 @@ + + + + + + + + +
Javadoc @since Tag Management
+API Tools provides support for management of @since Javadoc tags on new elements that have been added to API (types, methods, fields, etc).
+New API elements could be a new type added to an API package, a new type added to an API type, a new method added to an API type or a new field added to an API type.
+Method addition is a special case, where a method addition could be adding a method to a type, overriding a parent class method, implementing a parent interface method
+or changing an existing methods' signature.
+
+Note: @since tag information is not propagated via implementation or sub-classing. Each element that is added to API is expected to have
+its' own @since tag and version information.
+
+The tooling provides the following validation for @since tags:
+
The preferences for @since tag management can be changed on the Plug-in Development > API Errors/Warnings preference page.
Missing @since tags
+
+Every new API element detected will be checked by the tooling to ensure it has an @since tag.
+If the new element does not have an @since tag, it will be flagged as needing one, and a version for the tag will be proposed.
+The proposed version for the new tag will be the current version of the bundle - except in the case of a breaking API change where the bundle
+version also needs to be updated. If the bundle version also needs to be updated, the proposed version for the missing @since tag will be that of the proposed
+bundle version.
+
+Consider the following example: we have a bundle A with version 1.0.0 and we have a class C that was added in version 1.1.0 of A which contains method m1(). +
+-
+
- If we add a new method to C, say m2(), the tooling will report a missing
@sincetag problem on m2() and suggest +that a new tag of@since 1.1be placed on m2().
+ - If we add a new method to C, say m2() again and we change m1() - introduce a breaking API change - the tooling will report a
+missing
@sincetag problem on m2() and suggest that a new tag of@since 2.0be place on m2(). Where2.0.0+is the new proposed bundle version.
+
Malformed @since tags
+
+New elements can have their @since tags checked for consistency to ensure they are properly formulated. API tools
+checks that all @since tags follow the general format of:
+[@since] [pre-amble] [2 part version] [post-amble]
+
+Consider the following @since tag examples:
+
-
+
@since A 1 added m2(): would be flagged as malformed because the version is missing the second segment
+@since: would flagged as malformed since there is no version information
+@since A: would be flagged since there is no version information
+@since 1.0.0: would be flagged since the version has too many segments
+@since A 1.0 added m2(): would not be flagged
+
Invalid @since tag versions
+
+New elements can also have their @since tags checked for validity. An @since tag is considered to be valid
+if the version information in the tag matches the version of the bundle.
+
+Consider the following example where we have added a new method m2() to an API class in bundle A whose version is 1.0.0: +
+-
+
@since A 1.0 added method m2(): is considered valid
+@since A 2.0 added method m2(): is invalid since the version of bundle A is 1.0.0
+@since A 0.1 added method m2(): is invalid since the version of bundle A is 1.0.0
+
Related tasks
+ Setting up a baseline +Related references
+ API Baselines Preferences+ API Errors and Warnings Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/applications/analysis-application.htm b/org.eclipse.pde.doc.user/reference/api-tooling/applications/analysis-application.htm new file mode 100644 index 0000000000..e788fc25aa --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/applications/analysis-application.htm @@ -0,0 +1,140 @@ + + + + + + + +
API Analysis Command Line Application
+Purpose
+This application runs a complete API analysis of a Plugin project relative to a baseline - including API use, binary compatibility, and bundle version number validation. The profile is compared to an API baseline for binary compatibility (usually the previous release of a product).
+ +Usage
+Description
+The name of the application task is: org.eclipse.pde.api.tools.apiAnalyzer. To be used, the bundle file org.eclipse.pde.api.tools in version superior or equals to 1.1.800 has to be installed in the Eclipse Platform instance. Once the Platform is properly configured,
+the application can be started with commands like:
eclipse -application org.eclipse.pde.api.tools -project /path/to/project -depednencies /path/to/list/of/dependencies.txt -baseline default -failOnError
Application Arguments
+| Attribute | +Description | +Required | +
| project | +This attribute specifies the location of the project to analyze. The project must be the a valid Eclipse Plugin project,
+that is a project with typical .project, MANIFEST.MF... files.
+ |
+Yes | +
| dependencyList | +This attribute specifies a path to a file containing a list of depenencies that will be used as default target platform.
+ +The file must list the absolute path of dependencies (as jar files), either separated by new lines or colon (:). Tokens that are not +absolute path to jar files are ignored. + |
+Yes | +
| baseline | +This attribute specifies the location of the reference baseline.
+ +It can be the absolute path to a directory or a to a .target file, or default.
+If default, the current platform running the API Tools will be used as baseline.
+ |
+No. If omitted, similar to default |
+
| failOnError | +Report API compliance errors as a failure (non-0 exit code) |
+No | +
Examples
+ +In a Tycho-enabledpom.xml file:
+
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ [...]
+ <plugin>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>list-dependencies</id>
+ <goals>
+ <goal>list</goal>
+ </goals>
+ <phase>verify</phase>
+ <configuration>
+ <outputAbsoluteArtifactFilename>true</outputAbsoluteArtifactFilename>
+ <outputScope>false</outputScope>
+ <outputFile>${project.build.directory}/dependencies.txt</outputFile>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>org.eclipse.tycho.extras</groupId>
+ <artifactId>tycho-eclipserun-plugin</artifactId>
+ <version>1.4.0</version>
+ <executions>
+ <execution>
+ <id>api-analysis</id>
+ <goals>
+ <goal>eclipse-run</goal>
+ </goals>
+ <phase>verify</phase>
+ <configuration>
+ <applicationsArgs>
+ <!-- need to set workspace to a dir that's not a child of the project -->
+ <arg>-data</arg>
+ <args>${project.basedir}/../target/${project.artifactId}-apiAnalyzer-workspace</args>
+ <args>-application</args>
+ <args>org.eclipse.pde.api.tools.apiAnalysis</args>
+ <args>-project</args>
+ <args>${project.basedir}</args>
+ <args>-baseline</args>
+ <args>default</args>
+ <args>-dependencyList</args>
+ <args>${project.build.directory}/dependencies.txt</args>
+ <args>-failOnError</args>
+ </applicationsArgs>
+ <repositories>
+ <repository>
+ <id>eclipse-4.12</id>
+ <layout>p2</layout>
+ <url>https://download.eclipse.org/eclipse/updates/4.12-I-builds/</url>
+ </repository>
+ </repositories>
+ <dependencies>
+ <!-- This will constitute the default baseline -->
+ <dependency>
+ <artifactId>org.eclipse.sdk.ide</artifactId>
+ <type>p2-installable-unit</type>
+ </dependency>
+ </dependencies>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+
+This will run API analysis and fail the build in case an error is found.
+ +Related references
+API Analysis Ant Task + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api-compare-wizard.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-compare-wizard.png new file mode 100644 index 0000000000..021f7f7824 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-compare-wizard.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api-problem-filter-prop.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-problem-filter-prop.png new file mode 100644 index 0000000000..0b2f70a5d4 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-problem-filter-prop.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api-setup-wizard-preview.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-setup-wizard-preview.png new file mode 100644 index 0000000000..cc057d5f8d Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-setup-wizard-preview.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api-setup-wizard.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-setup-wizard.png new file mode 100644 index 0000000000..a86d88cc87 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-setup-wizard.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-archive-page.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-archive-page.png new file mode 100644 index 0000000000..a8e89ad49e Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-archive-page.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-conversion-page.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-conversion-page.png new file mode 100644 index 0000000000..21c9757c30 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-conversion-page.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-package-page.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-package-page.png new file mode 100644 index 0000000000..81a6b4f58c Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard-package-page.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard.png new file mode 100644 index 0000000000..325e0fe6e8 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api-use-pattern-wizard.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_analysis.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_analysis.png new file mode 100644 index 0000000000..e6f25396ab Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_analysis.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_compatibility.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_compatibility.png new file mode 100644 index 0000000000..8366db0475 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_compatibility.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_usage.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_usage.png new file mode 100644 index 0000000000..56a4ff9d74 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_usage.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_usescans.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_usescans.png new file mode 100644 index 0000000000..69f820a453 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_usescans.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_version.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_version.png new file mode 100644 index 0000000000..116fea8886 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_options_version.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/api_tooling.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_tooling.png new file mode 100644 index 0000000000..0427bd871b Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/api_tooling.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-pref-page.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-pref-page.png new file mode 100644 index 0000000000..f27354cf2d Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-pref-page.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-qf-dialog.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-qf-dialog.png new file mode 100644 index 0000000000..7ee6b66aff Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-qf-dialog.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-qf.png new file mode 100644 index 0000000000..da5c46d854 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/baseline-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/error_ovr.gif b/org.eclipse.pde.doc.user/reference/api-tooling/images/error_ovr.gif new file mode 100644 index 0000000000..c112416d5a Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/error_ovr.gif differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/errorwarning-prop-page.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/errorwarning-prop-page.png new file mode 100644 index 0000000000..dde8105dd7 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/errorwarning-prop-page.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/filter-dialog-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/filter-dialog-qf.png new file mode 100644 index 0000000000..e4b4202ff5 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/filter-dialog-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/filter-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/filter-qf.png new file mode 100644 index 0000000000..0c7ef2573f Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/filter-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/ok.gif b/org.eclipse.pde.doc.user/reference/api-tooling/images/ok.gif new file mode 100644 index 0000000000..689e5234f3 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/ok.gif differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-dialog-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-dialog-qf.png new file mode 100644 index 0000000000..dbc42be5e3 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-dialog-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-editor-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-editor-qf.png new file mode 100644 index 0000000000..8a9a7a6855 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-editor-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-qf.png new file mode 100644 index 0000000000..089bb01394 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/remove-filter-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-dialog-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-dialog-qf.png new file mode 100644 index 0000000000..2580dbf341 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-dialog-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-editor-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-editor-qf.png new file mode 100644 index 0000000000..16b8979e2d Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-editor-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-qf.png new file mode 100644 index 0000000000..f4425bd2e8 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/sincetag-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/success_ovr.gif b/org.eclipse.pde.doc.user/reference/api-tooling/images/success_ovr.gif new file mode 100644 index 0000000000..20fc2f250e Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/success_ovr.gif differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/use-ui-patterns.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/use-ui-patterns.png new file mode 100644 index 0000000000..f9bb9f43ec Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/use-ui-patterns.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/use-ui.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/use-ui.png new file mode 100644 index 0000000000..7e36cf69a4 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/use-ui.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/usescans-pref-page.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/usescans-pref-page.png new file mode 100644 index 0000000000..b6a7673ed3 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/usescans-pref-page.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/version-dialog-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/version-dialog-qf.png new file mode 100644 index 0000000000..0d7c3aa40b Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/version-dialog-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/version-editor-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/version-editor-qf.png new file mode 100644 index 0000000000..b1b36561d7 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/version-editor-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/images/version-qf.png b/org.eclipse.pde.doc.user/reference/api-tooling/images/version-qf.png new file mode 100644 index 0000000000..05d6bee148 Binary files /dev/null and b/org.eclipse.pde.doc.user/reference/api-tooling/images/version-qf.png differ diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-baselines.htm b/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-baselines.htm new file mode 100644 index 0000000000..8789d73fb4 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-baselines.htm @@ -0,0 +1,60 @@ + + + + + + + +API Baselines Preferences
+ The following preferences can be set using the Plug-in Development > API Baselines preference page.
An API baseline defines the state you want to compare your development workspace bundles against for the purposes of binary compatibility, bundle version numbers, and @since tags. For example, if you are developing bundles for Eclipse 3.4, you could use Eclipse 3.3 as your baseline.
+
+ 
+
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
| Add Baseline... | +Allows you to add a new API baseline. | ++ |
| Edit... | +Allows you to edit a selected API baseline. | ++ |
| Remove | +Allows you to remove the selected API baseline(s). | ++ |
| Missing API baseline | +This preference is used to notify you when the API builder is going to run and you do not have a default API baseline set. | +Error | +
+
Related tasks
+ Setting up an API baseline +Related references
+ PDE Preferences+ API Errors and Warnings Preferences
+ Missing API Baseline Quick Fix
+ API Baseline Wizard
+ API Use Scans Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-errorswarnings.htm b/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-errorswarnings.htm new file mode 100644 index 0000000000..564f04963c --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-errorswarnings.htm @@ -0,0 +1,719 @@ + + + + + + + +
API Errors and Warnings Preferences
+ The following preferences can be set using the Plug-in Development > API Errors/Warnings preference page.
+
+ API problems are created during project builds (auto and full builds), the tooling breaks down the types of problems reported into one of three categories:
+-
+
- Usage Problems - restricted code is being called by unauthorized plug-ins +
- API Incompatibilities - changes between versions are not compatible +
- Version Problems - plug-in versions or code versions (@since tags) not correct +
- Analysis Options - general options +
You can also configure the problem severities on a per project basis as well,
+ by using the API Errors/Warnings property page for a project
+
API Use
+
+ 
+
General
+| Option |
+ Description |
+ Default |
+
|---|---|---|
Unsupported use of API Javadoc Tags |
+ When enabled the API analysis builder will check for API Javadoc tags used incorrectly. |
+ Ignore |
+
Reference not defined in specified execution environment |
+ When enabled the API analysis builder will check for references to system libraries that might + be illegal according to the execution environment specified for the bundle. |
+ Ignore |
+
Restrictions
+| Option |
+ Description |
+ Default |
+
|---|---|---|
Implementing an interface marked as '@noimplement' |
+ When enabled the API analysis builder will check for illegal implementation of marked interfaces. |
+ Warning |
+
Extending a type marked '@noextend' |
+ When enabled the API analysis builder will check for classes that extend marked types. |
+ Warning |
+
Referencing a field or method marked '@noreference' |
+ When enabled the API analysis builder will check for field and method references to tagged members. |
+ Warning |
+
Instantiating a class tagged '@noinstantiate' |
+ When enabled the API analysis builder will check that tagged classes are not instantiated. |
+ Warning |
+
Overriding a method marked as '@nooverride' |
+ When enabled the API analysis builder will check that tagged methods in parent classes are not overridden in any child class either by extending (re-implement with a call to the overridden parent) or re-implementing (with no call to the overridden parent). |
+ Warning |
+
Leaks
+| Option |
+ Description |
+ Default |
+
|---|---|---|
Extends a non-API class |
+ When enabled the API analysis builder will check if any API classes extend non-API types. |
+ Warning |
+
Implements a non-API interface |
+ When enabled the API analysis builder will check if any API classes implement a non-API interface |
+ Warning |
+
Field with non-API type |
+ When enabled the API analysis builder will check if any API types have public or protected fields with non-API types. |
+ Warning |
+
Method with a non-API return type |
+ When enabled the API analysis builder will check if any API types have public or protected methods with non-API return types. |
+ Warning |
+
Method with non-API parameter type |
+ When enabled the API analysis builder will check if any API types have public or protected methods with non-API parameter types. |
+ Warning |
+
API Compatibility
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Report API breakage even if authorized by major version increment |
+ When enabled the API analysis builder will report problems for API breakages even if the major version of the bundle has already been incremented. |
+ Disabled |
+
Bundle
+| Option |
+ Description |
+ Default |
+
|---|---|---|
An API type has become non-API |
+ When enabled the API analysis builder will check if any API types in the current bundle have been changed to non-API types. |
+ Error |
+
A type has been removed |
+ When enabled the API analysis builder will check if any API types have been removed from the API scope in the given bundle. |
+ Error |
+
An API re-exported type has become non-API |
+ When enabled the API analysis builder will check if any API re-exported types in the current bundle have been changed to non-API types. |
+ Error |
+
A re-exported type has been removed |
+ When enabled the API analysis builder will check if any API re-exported types have been removed from the API scope in the given bundle. |
+ Error |
+
Class
+| Option |
+ Description |
+ Default |
+
|---|---|---|
A method (that needs to be implemented) has been added: |
+ When enabled the API analysis builder will check if any public or protected methods that need to be implemented have been added to any API types. |
+ Error |
+
Restrictions have been added |
+ When enabled the API analysis builder will check if API restrictions have been added for any API classes. |
+ Error |
+
A type parameter has been added |
+ When enabled the API analysis builder will check if any type parameters have been added to any API classes. |
+ Error |
+
The superinterfaces hierarchy has been reduced |
+ When enabled the API analysis builder will check if any parent interfaces have been removed from any API classes. |
+ Error |
+
The keyword 'abstract' has been added |
+ When enabled the API analysis builder will check if the 'abstract' keyword has been added to any API classes. |
+ Error |
+
The keyword 'final' has been added |
+ When enabled the API analysis builder will check if the 'final' keyword has been added to any API classes. |
+ Error |
+
Converted to annotation, enum, or interface |
+ When enabled the API analysis builder will check if any API classes have been changed to annotations, enums, or interfaces. |
+ Error |
+
The visibility has been reduced |
+ When enabled the API analysis builder will check if any public API classes have been made private or default scope. |
+ Error |
+
A field has been removed |
+ When enabled the API analysis builder will check if any public or protected fields have been removed from any API classes. |
+ Error |
+
A method has been removed |
+ When enabled the API analysis builder will check if any public or protected methods have been removed from any API classes. |
+ Error |
+
A constructor has been removed |
+ When enabled the API analysis builder will check if any public or protected constructors have been removed from any API classes. |
+ Error |
+
The superclass hierarchy has been reduced |
+ When enabled the API analysis builder will check if any superclasses have been removed from the hierarchy. |
+ Error |
+
A member type has been removed |
+ When enabled the API analysis builder will check if any member types have been removed from any API classes. |
+ Error |
+
A type parameter has been removed |
+ When enabled the API analysis builder will check if any type parameters have been removed from any API classes. |
+ Error |
+
Interface
+| Option |
+ Description |
+ Default |
+
|---|---|---|
A field (interface not tagged as '@noimplement') has been added |
+ When enabled the API analysis builder will check if any public fields have been added to any API interfaces. |
+ Error |
+
A method (interface not tagged as '@noimplement') has been added |
+ When enabled the API analysis builder will check if any public methods have been added to any API interfaces. |
+ Error |
+
Restrictions have been added |
+ When enabled the API analysis builder will check if API restrictions have added for any API interfaces. |
+ Error |
+
A type parameter has been added |
+ When enabled the API analysis builder will check if any type parameters have been added to any API interfaces. |
+ Error |
+
Converted to class, enum, or annotation |
+ When enabled the API analysis builder will check if any API interfaces have been changed to classes, enums, or interfaces. |
+ Error |
+
The superinterfaces hierarchy has been reduced |
+ When enabled the API analysis builder will check if any parent interfaces have been removed for any API interfaces. |
+ Error |
+
A type parameter has been removed |
+ When enabled the API analysis builder will check if any type parameters have been removed from any API interfaces. |
+ Error |
+
A field has been removed |
+ When enabled the API analysis builder will check if any public fields have been removed from any API interfaces. |
+ Error |
+
A method has been removed |
+ When enabled the API analysis builder will check if any public methods have been removed from any API interfaces. |
+ Error |
+
A member type has been removed |
+ When enabled the API analysis builder will check if nay member types have been removed from any API interfaces. |
+ Error |
+
Enum
+| Option |
+ Description |
+ Default |
+
|---|---|---|
The superinterfaces hierarchy has been reduced |
+ When enabled the API analysis builder will check if any parent interfaces have been removed from any API enums. |
+ Error |
+
Converted to annotation, class, or interface |
+ When enabled the API analysis builder will check if any API enums have been changed to annotations, classes, or interfaces. |
+ Error |
+
A field has been removed |
+ When enabled the API analysis builder will check if any public fields have been removed from any API enums. |
+ Error |
+
An enum constant has been removed |
+ When enabled the API analysis builder will check if any enum constants have been removed from any API enums. |
+ Error |
+
A method has been removed |
+ When enabled the API analysis builder will check if any public methods have been removed from any API enums. |
+ Error |
+
A member type has been removed |
+ When enabled the API analysis builder will check if any member types have been removed from any API enums. |
+ Error |
+
Annotation
+| Option |
+ Description |
+ Default |
+
|---|---|---|
A method without a default value has been added |
+ When enabled the API analysis builder will check if a method without a default value has been added to API annotations. |
+ Error |
+
Converted to class, enum, or interface |
+ When enabled the API analysis builder will check if any API annotations have been converted to classes, enums or interfaces. |
+ Error |
+
A field has been removed |
+ When enabled the API analysis builder will check if any public fields have been removed from any API annotations. |
+ Error |
+
A method has been removed |
+ When enabled the API analysis builder will check if any public methods have been removed from any API annotations. |
+ Error |
+
A member type has been removed |
+ When enabled the API analysis builder will check if any public member types have been removed from any API annotations. |
+ Error |
+
Field
+| Option |
+ Description |
+ Default |
+
|---|---|---|
A constant value has been added |
+ When enabled the API analysis builder will check if a constant value has been added to any previously un-initialized public or protected field constants for any API types. |
+ Error |
+
The type has been modified |
+ When enabled the API analysis builder will check if the type of any public or protected fields has been changed for any API types. |
+ Error |
+
The constant value has been modified |
+ When enabled the API analysis builder will check if the value of any public or protected field constants has been changed in any API types. |
+ Error |
+
The visibility has been reduced |
+ When enabled the API analysis builder will check if any public or protected fields have been made private in any API types. |
+ Error |
+
The keyword 'final' has been removed for static constant |
+ When enabled the API analysis builder will check if any public or protected fields have had the final keyword removed in any API types. |
+ Error |
+
The keyword 'final' has been added |
+ When enabled the API analysis builder will check if the final keyword has been added to any public or protected fields in any API types. |
+ Error |
+
The keyword 'static' has been removed |
+ When enabled the API analysis builder will check if the static keyword has been removed from any public or protected fields in any API types. |
+ Error |
+
The keyword 'static' has been added |
+ When enabled the API analysis builder will check if the static keyword has been added to any public or protected fields in any API types. |
+ Error |
+
The constant value has been removed |
+ When enabled the API analysis builder will check if the value of a constant field has been removed for any public or protected field constants in any API types. |
+ Error |
+
A type argument has been removed |
+ When enabled the API analysis builder will check if a type argument has been removed from any public or protected fields in any API types. |
+ Error |
+
Method
+| Option |
+ Description |
+ Default |
+
|---|---|---|
The @nooverride restriction has been added |
+ When enabled the API analysis builder will check if the restrictions of any public or protected methods have been changed in any API types by adding the @nooverride tag. |
+ Error |
+
A type parameter has been added |
+ When enabled the API analysis builder will check if a type parameter has been added to any public or protected methods for any API types. |
+ Error |
+
Converted variable argument to array type |
+ When enabled the API analysis builder will check if a varargs argument has been expanded to an object array for any public or protected methods for any API types. |
+ Error |
+
The visibility has been reduced |
+ When enabled the API analysis builder will check if any public or protected methods have been made private for any API types. |
+ Error |
+
The keyword 'abstract' has been added |
+ When enabled the API analysis builder will check if any public or protected methods have been made abstract in any API types. |
+ Error |
+
The keyword 'static' has been added |
+ When enabled the API analysis builder will check if any public or protected methods have been made static in any API types. |
+ Error |
+
The keyword 'static' has been removed |
+ When enabled the API analysis builder will check if any public or protected methods have been made non-static in any API types. |
+ Error |
+
The keyword 'final' has been added (type tagged '@noextend') |
+ When enabled the API analysis builder will check if any public or protected methods have been made final in any API types that have been tagged @noextend. |
+ Error |
+
The annotation default value has been removed |
+ When enabled the API analysis builder will check if the default value associated with any API annotation method has been removed. |
+ Error |
+
A type parameter has been removed |
+ When enabled the API analysis builder will check if a type parameter has been removed from any public or protected methods for any API types. |
+ Error |
+
Constructor
+| Option |
+ Description |
+ Default |
+
|---|---|---|
A type parameter has been added |
+ When enabled the API analysis builder will check if a type parameter has been added to any public constructors for any API types. |
+ Error |
+
Converted variable argument to array type |
+ When enabled the API analysis builder will check if any varargs parameters have been expanded to object arrays for any public constructors for any API types. |
+ Error |
+
The visibility has been reduced |
+ When enabled the API analysis builder will check if any public constructors have been made non-public in any API types. |
+ Error |
+
A type parameter has been removed |
+ When enabled the API analysis builder will check if a type parameter has been removed from any public constructors for any API types. |
+ Error |
+
Type Parameter
+| Option |
+ Description |
+ Default |
+
|---|---|---|
A class bound has been added |
+ When enabled the API analysis builder will check if a class bound has been added to any type parameter of any API types. |
+ Error |
+
An interface bound has been added |
+ When enabled the API analysis builder will check if any interface bounds have been added to any type parameter of any API types. |
+ Error |
+
A class bound has been modified |
+ When enabled the API analysis builder will check if any class bounds have been changed on any type parameter of any API types. |
+ Error |
+
An interface bound has been modified |
+ When enabled the API analysis builder will check if any interface bounds have been changed on any type parameter of any API types. |
+ Error |
+
A class bound has been removed |
+ When enabled the API analysis builder will check if any class bounds have been removed from any type parameter of any API types. |
+ Error |
+
An interface bound has been removed |
+ When enabled the API analysis builder will check if any interface bounds have been removed from any type parameter of any API types. |
+ Error |
+
Version Management
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Report missing '@since' tags |
+ When enabled the API analysis builder will check if @since tags are missing for types or members added since the version of the API baseline in use. |
+ Error |
+
Report malformed '@since' tags |
+ When enabled the API analysis builder will check if any @since tags currently in use are malformed (incorrect syntax). |
+ Error |
+
Report invalid '@since' tag version |
+ When enabled the API analysis builder will check if any @since tags currently in use have the wrong version. |
+ Error |
+
Report incompatible bundle version |
+ When enabled the API analysis builder will check if the bundle version for the plug-in is incorrect, based on any API changes and the current API baseline in use. |
+ Error |
+
Report unnecessary minor or micro version change |
+ When enabled the API analysis builder will check if the minor or micro version for the plug-in is incorrectly incremented. |
+ Warning |
+
Report major version change without API breakage |
+ When enabled the API analysis builder will check if the major version for the plug-in has changed without a breaking API change. |
+ Warning |
+
Report changed execution environment incompatibility |
+ When enabled the API analysis builder will check if the bundle version for the plug-in requires a minor version change because of the changed execution environment. |
+ Error |
+
Analysis Options
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Bundle missing required constraint/prerequisite |
+ When enabled the API analysis builder will report any missing required constraint or prerequisite that prevents the builder from performing a complete analysis. Regardless of the value of this option + the analysis is skipped for the corresponding bundle. |
+ Error |
+
Unused API problem filters |
+ When enabled the API analysis builder will report any API problem filters that are no longer being used. |
+ Warning |
+
API Use Scans Options
+
+ 
+
| Option |
+ Description |
+ Default |
+
|---|---|---|
Unresolved type problem |
+ When enabled the API analysis builder will report any API types that have been removed that are included in any use scan listed on the API Use Scans prefrence page. |
+ Error |
+
Unresolved method problem |
+ When enabled the API analysis builder will report any methods that have been removed that are included in any use scan listed on the API Use Scans prefrence page. |
+ Error |
+
Unresolved field problem |
+ When enabled the API analysis builder will report any fields that have been removed that are included in any use scan listed on the API Use Scans prefrence page. |
+ Error |
+
Related references
+PDE Preferences+API Errors and Warnings Property Page
+API Baselines Preferences
+API Use Scans Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-usescans.htm b/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-usescans.htm new file mode 100644 index 0000000000..8becce5d30 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/preferences/ref-usescans.htm @@ -0,0 +1,60 @@ + + + + + + + +
API Use Scans Preferences
+ The following preferences can be set using the Plug-in Development > API Use Scans preference page.
An API Use Scan is a list of references using the ant task or the report tool. The API Analysis builder checks that all references listed in the provided use scans still exist in your workspace projects. Any missing types, methods or fields will be reported as problems in the workspace based on your Error/Warning preference settings.
+
+ 
+
+
| Option |
+ Description |
+
|---|---|
| Select All | +Selects all use scan locations in the list. The API analysis builder will check all locations. | +
| Deselect All | +Deselects all use scan locations in the list. The API analysis builder will not check any locations. | +
| Add Directory... | +Adds a new use scan stored in a directory. | +
| Add Archive... | +Adds a new use scan stored in an archive file. | +
| Edit Location... | +Allows you to change the location of a use scan directory or archive. | +
| Remove | +Removes the selected use scans from the list. | +
Related references
+PDE Preferences+API Use Scan Ant Task
+API Use Scan Report Tool
+API Errors and Warnings Preferences
+API Baselines Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/propertypages/ref-errorswarnings-prop.htm b/org.eclipse.pde.doc.user/reference/api-tooling/propertypages/ref-errorswarnings-prop.htm new file mode 100644 index 0000000000..65ddac3053 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/propertypages/ref-errorswarnings-prop.htm @@ -0,0 +1,26 @@ + + + + + + + +
API Errors and Warnings Property Page
+API problems are created during project builds (auto and full builds), the tooling breaks down the types of problems reported into one of three categories:
+-
+
- Usage Problems - restricted code is being called by unauthorized plug-ins. +
- Binary Incompatibilities - changes between versions are not binary compatible. +
- Version Problems - plug-in versions or code versions (@since tags) not correct. +
You can also configure the problem severities for the entire workspace as well using the Plug-in Development > API Errors/Warnings preference page.
For a complete listing of the preferences and their descriptions, please refer to the API Errors/Warnings preference page.
+ +Related references
+API Errors and Warnings Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/propertypages/ref-filters-prop.htm b/org.eclipse.pde.doc.user/reference/api-tooling/propertypages/ref-filters-prop.htm new file mode 100644 index 0000000000..7b21f3e11d --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/propertypages/ref-filters-prop.htm @@ -0,0 +1,31 @@ + + + + + + + +API Problem Filters Property Page
+API problems are created during project builds (auto and full builds), but sometimes there are problems reported that are known or expected which cannot be readily fixed. These problems can be filtered.
++ Once a problem filter has been created, it can be viewed or removed using the API Problem Filters property page.
+To locate this property page:
+-
+
- Open the context menu for any API Tools enabled project and select Properties. +
- Navigate to Plug-in Development > API Problem Filters. +
+
+Related tasks
+Creating filters+Removing filters + +
Related references
+API Errors and Warnings Property Page+API Errors and Warnings Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-api-filter-qf.htm b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-api-filter-qf.htm new file mode 100644 index 0000000000..187e00b4b2 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-api-filter-qf.htm @@ -0,0 +1,52 @@ + + + + + + + +
Add API Problem Filter Quick Fix
+This quick fix can be used to quickly create an API problem filter for a known or expected API problem that cannot be easily corrected.
+This quick fix is available in one of two places:
+-
+
- The Problems view. +
- Editing the resource the problem exists in. + +
The Problems view
+-
+
- Open the Problems view. +
- Select an API Tools problem.
+
+
+ - Use Ctrl + 1 to trigger the quick fix from the Problems view (or use the context menu as shown above).
+
+
+
Editing the resource
+-
+
- Open the resource the API problem exists in. +
- Use Ctrl + 1 on the corresponding problem.
+
+
+
+
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.
+Related tasks
+Creating API Problem Filters+Removing filters
+ +
Related references
+API Problem Filters Property Page+Missing API Baseline Quick Fix
+Version Numbering Quick Fix
+Since Tag Quick Fix
+Remove Unused Problem Filter Quick Fix + + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-missing-baseline-qf.htm b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-missing-baseline-qf.htm new file mode 100644 index 0000000000..b2b14c9e28 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-missing-baseline-qf.htm @@ -0,0 +1,40 @@ + + + + + + + + +
Missing API Baseline Quick Fix
+This quick fix can be used to quickly help resolve missing API baseline problems.
+This quick fix is available in the Problems view.
+The Problems view
+-
+
- Open the Problems view. +
- Select the missing API baseline problem.
+
+
+ - Use Ctrl + 1 to trigger the quick fix from the Problems view (or use the context menu as shown above).
+
+
+
Completing the quick fix will open the Plug-in Development > API Baselines preference page, allowing you to create a new baseline using the API baseline wizard.
Related tasks
+Setting up an API baseline+ +
Related references
+API Baselines Preferences+Add API Problem Filter Quick Fix
+Version Numbering Quick Fix
+Since Tag Quick Fix
+Remove Unused Problem Filter Quick Fix + + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-remove-api-filter-qf.htm b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-remove-api-filter-qf.htm new file mode 100644 index 0000000000..2879643ceb --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-remove-api-filter-qf.htm @@ -0,0 +1,52 @@ + + + + + + + +
Remove API Problem Filter Quick Fix
+This quick fix can be used to quickly remove an API problem filter for an unsupported API problem filter problem.
+This quick fix is available in one of two places:
+-
+
- The Problems view. +
- Editing the resource the problem exists in. + +
The Problems view
+-
+
- Open the Problems view. +
- Select an API Tools problem.
+
+
+ - Use Ctrl + 1 to trigger the quick fix from the Problems view (or use the context menu as shown above).
+
+
+
Editing the resource
+-
+
- Open the resource the API problem exists in. +
- Use Ctrl + 1 on the corresponding problem.
+
+
+
+
Once the problem filter has been removed the corresponding resource is rebuilt and the unused filter problem is removed from the Problems view and any open editors.
+ +Related tasks
+Creating API Problem Filters+Removing filters
+ +
Related references
+API Problem Filters Property Page+Missing API Baseline Quick Fix
+Version Numbering Quick Fix
+Since Tag Quick Fix + + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-sincetag-qf.htm b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-sincetag-qf.htm new file mode 100644 index 0000000000..a4f49741eb --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-sincetag-qf.htm @@ -0,0 +1,47 @@ + + + + + + + +
Since Tag Quick Fix
+This quick fix can be used to quickly add since tags or help correct problems with existing since tags.
+This quick fix is available in one of two places:
+-
+
- The Problems view. +
- Editing the resource the problem exists in. + +
The Problems view
+-
+
- Open the Problems view. +
- Select a since tag problem.
+
+
+ - Use Ctrl + 1 to trigger the quick fix from the Problems view (or use the context menu as shown above).
+
+
+
Editing the resource
+-
+
- Open the resource the API problem exists in. +
- Use Ctrl + 1 on the corresponding problem.
+
+
+
+
Once the since tag problem has been corrected the corresponding resource is rebuilt and the problem is removed from the Problems view and any open editors.
+ +Related references
+Missing API Baseline Quick Fix+Add API Problem Filter Quick Fix
+Version Numbering Quick Fix
+Remove Unused Problem Filter Quick Fix + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-version-qf.htm b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-version-qf.htm new file mode 100644 index 0000000000..b8c5803051 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/quickfixes/ref-api-version-qf.htm @@ -0,0 +1,48 @@ + + + + + + + +
Version Numbering Quick Fix
+This quick fix is used to quickly and easily correct version numbering problems for your plug-in.
+This quick fix is available in one of two places:
+ +-
+
- The Problems view. +
- The manifest editor for the corresponding manifest file. + +
The Problems view
+-
+
- Open the Problems view. +
- Select a version numbering problem.
+
+
+ - Use Ctrl + 1 to trigger the quick fix from the Problems view (or use the context menu as shown above).
+
+
+
The manifest editor
+-
+
- Open the manifest editor on the manifest with the version problems. +
- Navigate to the MANIFEST.MF tab. +
- Use Ctrl + 1 on the corresponding version problem.
+
+
+
+
Related references
+Missing API Baseline Quick Fix+Add API Problem Filter Quick Fix
+Since Tag Quick Fix
+Remove Unused Problem Filter Quick Fix + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/views/ref-api-tooling-view.htm b/org.eclipse.pde.doc.user/reference/api-tooling/views/ref-api-tooling-view.htm new file mode 100644 index 0000000000..13d7408732 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/views/ref-api-tooling-view.htm @@ -0,0 +1,41 @@ + + + + + +
API Tools View
+The API Tools view shows all deltas found between a set of selected elements (project, source folders,
+package fragments, or compilation units) and a reference baseline. TheAPI Tools view is available under
+
+Window > Show View > Other... > API Tools > API Tools
+.
Delta details
+The view itself is showing only the delta's localized message with an overlay image that tells whether the corresponding delta
+is seen as a compatible (
) or an incompatible
+(
) delta.
+
+A double-click on a delta shows additional information inside the property view.
The additional information are:
+-
+
- the component on which the delta is reported, +
- the element type, +
- the flags, +
- the key, +
- the kind, +
- the new modifiers, +
- the old modifiers, +
- the restrictions, +
- the type name, +
- the localized message. +
API Baseline Wizard
+The API baseline wizard can be used to:
+-
+
- Add new API baselines to your workspace. +
- Edit an existing API baseline. +
The wizard can be used from the Plug-in Development > API Baselines preference page preference page, by selecting either the Add Baseline... button (to add a new baseline) or the Edit... button (to edit an existing baseline).
| Option |
+ Description |
+ Default |
+
|---|---|---|
| Name | +You can choose any name you want for a baseline with the exception that it cannot contain system restricted characters. For example on Windows, you cannot use '/' in file names. | +Empty | +
| Location | +The location for an API baseline is the path to an Eclipse SDK install, typically a path to the 'plugins' folder for the install. | +Empty | +
| Browse... | +Selecting the Browse button will allow you to browse for the location of an Eclipse SDK installation. | ++ |
| Reset | +Selecting the Reset button will re-scan the specified location and recreate the API baseline. | ++ |
+
The API Baseline wizard, showing an example Eclipse 3.3.2 baseline being created.
+
+
+Related tasks
+Setting up a baseline + +Related references
+API Baselines Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-compare-wizard.htm b/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-compare-wizard.htm new file mode 100644 index 0000000000..691967bcc2 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-compare-wizard.htm @@ -0,0 +1,50 @@ + + + + + + + +API Compare Wizard
+The API compare wizard can be used to compare a selected set of selected elements (projects, source folders, package fragments, or compilation units) to a selected API baseline and show those +results in the API Tools View
++
| Option |
+ Description |
+ Default |
+
|---|---|---|
| Baseline | +You can choose any API baseline from the combo box to compare to. | +Default baseline or empty | +
| Add New Baseline | +Opens the API Baselines preference page so that a new baseline can be added for use. | ++ |
+
The API Compare wizard, showing an example Eclipse 3.4.1 baseline being compared to.
+
+
+Related tasks
+Comparing to an API baseline+Setting up a baseline + +
Related references
+API Baselines Preferences + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-setup-wizard.htm b/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-setup-wizard.htm new file mode 100644 index 0000000000..0273cf23fc --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-setup-wizard.htm @@ -0,0 +1,79 @@ + + + + + + + +API Tools Setup Wizard
+Before any plug-in project can make use of API Tools it must first be set up to use the tooling, which can be done using the API Tools setup wizard.
++To activate the wizard use the following steps:
+-
+
- Open the context menu on a plug-in project and select PDE Tools +
- On the resulting fly-out menu select API Tools Setup... +
| Option |
+ Description |
+ Default |
+
|---|---|---|
| Choose a project | +This text field allows you to filter the current list of projects by their name. Where '*' matches anything and '?' matches any character | +Empty | +
| Projects | +This list contains all of the projects in the current workspace that can be set up to use API Tools. To be available to be converted a project must be a Java plug-in project. | ++ |
| Select All | +Selects all of the projects in the list. | ++ |
| Deselect All | +Deselect all of the projects in the list. | ++ |
| Delete component.xml after update is complete | +This option will remove the component.xml file from your plug-in project when the setup is complete. A component.xml file was used prior to API Tools to describe the API of your plug-in. +If a component.xml file is found it will be used by the setup wizard to add API restrictions (Javadoc tags) to the corresponding source files in your plug-in. All proposed changes can be viewed on the preview page for the wizard. |
+ On | +
+The first page of the wizard allows you to select projects and set additional options. +
+
+
+
+On the preview page you can see all of the changes that will be made to the project and any source files. +
+
+
+
Related tasks
+Setting up API Tools + +Related references
+API Tools Setup Action+PDE Tools Menu + + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-use-dialog.htm b/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-use-dialog.htm new file mode 100644 index 0000000000..b895e2f9c3 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-api-use-dialog.htm @@ -0,0 +1,228 @@ + + + + + + + +
API Use Reports
+An API Use Report describes a set of references from one set of bundles to another set of bundles. +A report can be generated using the API Use Ant Task. +A user interface is provided to configure and generate a report in the External Tools dialog. +To create a new use scan configuration simply double-click the API Use Report configuration type.
+ +API Use Report Tab
+The API Use Report tab allows you to configure the analysis.
+The following example shows a configuration to extract all references to Eclipse bundles in a 3.4 installation.
+ +
+ +
| Option |
+ Description |
+ Default |
+
|---|---|---|
| Analyze | +You can select what you want to analyze, which can be either an API baseline, target definition or a directory of bundles. + You can also select to only generate HTML for an existing report. You can only select one option, with each option allowing you to configure it. I.e. you can go to the API baselines preference page to edit existing baselines if you select analyzing an API baseline. | +API Baseline | +
| Analyze > API Baseline | +You can choose any API baseline from the combo box to analyze | +Default baseline or empty | +
| Analyze > Baselines... | +Allows access to the API Baselines preference page to configure the baseline to analyze. | ++ |
| Analyze > Target Definition | +You can choose any target definition from the combo box to analyze | +The active target definition or empty | +
| Analyze > Targets | +Allows access to the Target Platform preference page to configure the target definition to analyze. | ++ |
| Analyze > Directory | +You can enter the absolute path to a directory containing the bundles. | +empty | +
| Analyze > Browse... | +Allows you to browse for a folder of bundles to analyze. | ++ |
| Analyze > Generate HTML report for existing use scan | +Allows you to create a report for an existing scan and not have to perform the analysis again. | ++ |
| Search for > References to | +Allows you to specify the name (or matching RegEx) of the bundle that you want to see references to.
+ Consider the following example: org\.eclipse.*. In this example we are saying that we want to see all references to any bundle that starts with the name org.eclipse.. |
+ empty | +
| Search for > API references | +Allows you to scan for API references. | +unchecked | +
| Search for > Internal references | +Allows you to scan for internal references. | +checked | +
| Search for > Illegal API Use | +Allows you to scan for illegal API usage i.e. usage of restricted API members. | +unchecked | +
| Search in > Bundles matching | +Allows you to specify the name (or matching RegEx) of the bundle(s) that you want to scan for references from i.e. a search scope.
+ Consider the following example: .*. In this example we are saying that we want to search in all bundles whose name matches any character sequence.
+ The same effect can be achieved leaving the field blank. |
+ empty | +
| Filters > Additional Filters | +Allows you to specify a directory of API problem filters to use during the scan.
+
+ The setting is the root directory of the .api_filters files that should be used to filter potential references found by the use scan. +root + | + +-- component name (i.e. org.eclipse.jface) + | + +--- .api_filters ++ |
+ empty | +
| Filters > Browse... | +Opens a dialog where you can select a root filter directory. + | +empty | +
| Reporting > Report Type | +Allows you to choose between two html report formats. If Referenced bundles report (Producers) is selected the report
+ will list all of the bundles containing the types that are being referenced in the searched bundles. If Referencing bundles report (Consumers) is selected the report will
+ be organized to show all of the bundles in the search scope that contain references.
+ + When switching report types, check that the References to and Bundles matching regular expressions have the correct values. When using a wildcard expression such as .* in one + setting, switching to another report type often requires the wilcard being moved to the other setting to get the most useful report. + + |
+ Referenced bundles report (Producers) | +
| Reporting > Report Output Location | +Allows you to specify the absolute path where any generated reports should be placed. | +empty | +
| Reporting > Browse... | +Opens a dialog where you can select the location to output any reports. | ++ |
| Reporting > Clean report directory before reporting new results | +Allows you to clear out an existing XML report location prior to the scan reporting any results. + It should be noted that this option will completely remove the specified report directory if it exists, with all child directories being recursively removed as well. | +unchecked | +
| Reporting > Create HTML reports | +Converts all of the XML output into formatted HTML and place it in <report location>\html |
+ unchecked | +
| Reporting > Clean HTML report location | +Allows you to clear out an existing HTML location prior to creating new reports. + It should be noted that this option will completely remove the specified HTML directory if it exists, with all child directories being recursively removed as well. + This option only enables if you select the Create HTML Reports option mentioned above. | +unchecked | +
| Reporting > Open report when search completes | +Opens the HTML report when the analysis is complete. This option only enables if you select the Create HTML Reports option mentioned above. | +unchecked | +
| Reporting > Description | +Allows you to enter a human-readable description for the report. | +empty | +
Patterns Tab
+The Patterns tab allows you to create a variety of Regular Expression patterns to control the use analysis. +There are currently three supported kinds of patterns:
+-
+
- Archive Pattern - Allows you to specify nested archives that should be ignored during analysis. +
- Package Pattern - Allows you to specify packages that should be API or internal without having to update your bundle manifest. +
- Report Conversion Pattern - Allows you to create a package name regular expression to filter references taht are reported. All reported referece are filtered + using their fully qualified package name. +
+ +
| Option |
+ Description |
+ Default |
+
|---|---|---|
| Add... | +Allows you to add a new pattern. This button will start the + Pattern wizard. | ++ |
| Edit | +Allows you to edit the currently selected pattern. Only one pattern can be edited at a time. | ++ |
| Remove | +Allows you to remove the selected pattern(s). You can remove more than one pattern at a time. | ++ |
Related tasks
+Comparing to an API baseline+Setting up a baseline + +
Related references
+API Baselines Preferences+API Use Patterns Wizard + + diff --git a/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-apiuse-patterns-wizard.htm b/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-apiuse-patterns-wizard.htm new file mode 100755 index 0000000000..ac97da8b77 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/api-tooling/wizards/ref-apiuse-patterns-wizard.htm @@ -0,0 +1,162 @@ + + + + + + + +
API Use Patterns Wizard
+This wizard helps guide you through creating regular expression patterns for controlling an API Use analysis.
+To activate the wizard use the following steps:
+-
+
- While creating a new API Use Report launch configuration, switch to the Patterns tab. +
- On the tab press the Add... button +
| Option |
+ Description |
+ Default |
+
|---|---|---|
| Pattern Types | +This listing shows all of the patterns that can be created with the wizard. | +First element in list | +
| Description | +Shows the human-readable description of the pattern kind selected in the Pattern Types listing. | ++ |
+The first page of the wizard allows you to select what kind of pattern you would like to create. Descriptions for each pattern +are given to help you choose - simply select the pattern and the description is displayed in the Description field. +
+
+
+
Archive Patterns
++When API use analysis is done all folders and archives within a bundle are scanned; ensuring all class files are analyzed. In some cases +a bundle may contain an archive with old versions of class files (for example) that you do not want to be analyzed. In this case an archive pattern +can be used to completely ignore a specific archive or all archives matching a given regular expression. +
+| Option |
+ Description |
+ Default |
+
|---|---|---|
| Bundle Name | +The complete symbolic name of the bundle to apply this pattern to.
+ For example: org.eclipse.pde.api.tools. |
+ empty | +
| Archive Name | +The complete name or regular expression of the archive(s) to apply the pattern to.
+ For example: *.jar - which will ignore any nested jar file. |
+ empty | +
+
+
Package Patterns
++When extracting references for analysis, the API Use search engine uses meta-data from the bundle to determine if a reference is internal or not. In +some cases a bundle has not been set up to properly describe what classes are internal and which are not. A Package Pattern allows you to +augment these malformed bundles - only from the search engine point of view, the actual bundle is not changed in any way - to describe what is +or is not internal. +
+| Option |
+ Description |
+ Default |
+
|---|---|---|
| Pattern | +The regular expression pattern to match packages against.
+ For example: .*\.internal\..*. |
+ empty | +
| API Pattern | +If the pattern should make matching packages be considered as API or not. | +checked | +
+
+
Report Conversion Patterns
++When an API use analysis is complete, there can be an immense amount of information to look through. With a report conversion pattern though +you can cut down on the reference information presented in the HTML reports to only see what you are interested in. To do so you can create +exclusion patterns used to prune the references that are reported. +
+| Option |
+ Description |
+ Default |
+
|---|---|---|
| Filter references to this pattern | +Allows you to ignore reporting references to the pattern.
+ For example if the pattern was org\.eclipse\.jdt\..*, selecting this option would not report any references made to JDT. |
+ selected | +
| Filter references from this pattern | +Allows you to ignore reporting references to the pattern.
+ For example if the pattern was org\.eclipse\.jdt\..*, selecting this option would not report any references from JDT. |
+ + |
| Pattern | +The regular expression pattern. | +empty | +
+
+
Related tasks
+Setting up API Tools + +Related references
+API Tools Setup Action+PDE Tools Menu
+API Use Reports + + diff --git a/org.eclipse.pde.doc.user/reference/extension-points/index.html b/org.eclipse.pde.doc.user/reference/extension-points/index.html new file mode 100644 index 0000000000..c0542acbe0 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/extension-points/index.html @@ -0,0 +1,32 @@ + + + + + +
PDE Extension Points
+The following extension points can be used to extend the capabilities of the + PDE infrastructure:
+-
+
- org.eclipse.ui.trace.traceComponents +
- org.eclipse.pde.build.fetchFactories +
- org.eclipse.pde.core.bundleClasspathResolvers +
- org.eclipse.pde.core.javadoc +
- org.eclipse.pde.core.pluginClasspathContributors +
- org.eclipse.pde.core.source +
- org.eclipse.pde.core.targetLocations +
- org.eclipse.pde.core.targets +
- org.eclipse.pde.ui.launchShortcuts +
- org.eclipse.pde.ui.newExtension +
- org.eclipse.pde.ui.osgiFrameworks +
- org.eclipse.pde.ui.pluginContent +
- org.eclipse.pde.ui.samples +
- org.eclipse.pde.ui.targetLocationProvisioners +
- org.eclipse.pde.ui.templates +
+Eclipse platform
+API rules of engagement
+Version 0.15 - Last revised 12:00 May 30, 2001
+Here are the rules of engagement for clients of the Eclipse platform +API (and other components).
++What it means to be API
+The Eclipse platform defines API elements for use by its clients, namely +ISVs writing plug-ins. These plug-ins may in turn define API elements for +their clients, and so on. API elements are the public face: they carry +a specification about what they are supposed to do, and about how they +are intended to be used. API elements are supported: the Eclipse platform +team will fix implementation bugs where there is a deviation from the specified +behavior. Since there is often a high cost associated with breaking API +changes, the Eclipse platform team will also try to evolve API elements +gracefully through successive major releases.
++How to tell API from non-API
+By their very nature, API elements are documented and have a specification, +in contrast to non-API elements which are internal implementation details +usually without published documentation or specifications. So if you cannot +find the documentation for something, that's usually a good indicator that +it's not API.
+To try to draw the line more starkly, the code base for the platform +is separated into API and non-API packages, with all API elements being +declared in designated API packages.
+-
+
- +API package - a Java package that contains at least one API class +or API interface. The names of API packages are advertised in the documentation +for that component; where feasible, all other packages containing only +implementation details have "internal" in the package name. The names of +API packages may legitimately appear in client code. For the Eclipse platform +proper, these are: + +
-
+
- +org.eclipse.foo.* - for example, org.eclipse.swt.widgets, +org.eclipse.ui, +or org.eclipse.core.runtime + +
- +org.eclipse.foo.internal.* - not API; internal implementation +packages + +
- +org.eclipse.foo.examples.* - not API; these are examples + +
- +org.eclipse.foo.tests.* - not API; these are test suites +
-
+
- +API class or interface - a public class or interface in +an API package, or a public or protected class or interface +member declared in, or inherited by, some other API class or interface. +The names of API classes and interfaces may legitimately appear in client +code. + +
- +API method or constructor - a public or protected +method or constructor either declared in, or inherited by, an API class +or interface. The names of API methods may legitimately appear in client +code. + +
- +API field - a public or protected field either +declared in, or inherited by, an API class or interface. The names of API +fields may legitimately appear in client code. +
-
+
- +Stick to officially documented APIs. Only reference packages that +are documented in the published API Javadoc for the component. +Never reference a package belonging to another component that has "internal" +in its name---these are never API. Never reference a package for which +there is no published API Javadoc---these are not API either. +
+General rules
+The specification of API elements is generated from Javadoc comments in +the element's Java source code. For some types of elements, the specification +is in the form of a contract. For example, in the case of methods, the +contract is between two parties, the caller of the method and the implementor +of the method. The fundamental ground rule is: +-
+
- +Honor all contracts. The contracts are described in the published +Javadoc for the API elements you are using. +
-
+
- +You must honor "must". Pay especially close heed to conditions where +"must" is used. +
-
+
- +Do not rely on incidental behavior. Incidental behavior is behavior +observed by experiment or in practice, but which is not guaranteed by any +API specification. + +
- +Do not treat null as an object. Null is more the lack of an object. +Assume everything is non-null unless the API specification says otherwise. + +
- +Do not try to cheat with Java reflection. Using Java reflection +to circumvent Java compiler checking buys you nothing more. There are no +additional API contracts for uses of reflection; reflection simply increases +the likelihood of relying on unspecified behavior and internal implementation +detail. + +
- +Use your own packages. Do not declare code in a package belonging +to another component. Always declare your own code in your own packages. +
+Calling public API methods
+For most clients, the bulk of the Eclipse API takes the form of public +methods on API interfaces or classes, provided for the client to call when +appropriate. +-
+
- +Ensure preconditions. Do ensure that an API method's preconditions +are met before calling the method. Conversely, the caller may safely assume +that the method's postconditions will have been achieved immediately upon +return from the call. + +
- +Null parameters. Do not pass null as a parameter to an API method +unless the parameter is explicitly documented as allowing null. This is +perhaps the most frequently made programming error. + +
- +Restricted callers. Do not call an API method that is documented +as available only to certain callers unless you're one of them. In some +situations, methods need to be part of the public API for the benefit of +a certain class of callers (often internal); calling one of these methods +at the wrong time has unspecified (and perhaps unpredictable) consequences. + +
- +Debugging methods. Do not call an API method labelled "for debugging +purposes only". For example, most toString() methods are in this +category. + +
- +Parameter capture. Do not pass an array, collection, or other mutable +object as a parameter to an API method and then modify the object passed +in. This is just asking for trouble. +
+Instantiating platform API classes
+Not all concrete API classes are intended to be instantiated by just anyone. +API classes have an instantiation contract indicating the terms under which +instances may be created. The contract may also cover things like residual +initialization responsibilities (for example, configuring a certain property +before the instance is fully active) and associated lifecycle responsibilities +(for example, calling dispose() to free up OS resources hung on +to by the instance). Classes that are designed to be instantiated by clients +are explicitly flagged in the Javadoc class comment (with words like "Clients +may instantiate."). +-
+
- +Restricted instantiators. Do not instantiate an API class that is +documented as available only to certain parties unless you're one of them. +In some situations, classes need to be part of the public API for the benefit +of a certain party (often internal); instantiating one of these classes +incorrectly has unspecified (and perhaps unpredictable) consequences. +
+Subclassing platform API classes
+Only a subset of the API classes were designed to be subclassed. API classes +have a subclass contract indicating the terms under which subclasses may +be declared. This contract also covers initialization responsibilities +and lifecycle responsibilities. Classes that are designed to be subclassed +by clients are explicitly flagged in the Javadoc class comment (with words +like "Clients may subclass."). +-
+
- +Restricted subclassers. Do not subclass an API class that is not +intended to be subclassed. Treat these classes as if they had been declared +final. (These are sometimes referred to as "soft final" classes). +
+Calling protected API methods
+Calling inherited protected and public methods from within a subclass is +generally allowed; however, this often requires more care to correctly +call than to call public methods from outside the hierarchy. ++Overriding API methods
+Only a subset of the public and protected API methods were designed to +be overridden. Each API method has a subclass contract indicating the terms +under which a subclass may override it. By default, overriding is not permitted. +It is important to check the subclass contract on the actual method implementation +being overridden; the terms of subclass contracts are not automatically +passed along when that method is overridden. +-
+
-
+Do not override a public or protected API method unless it is explicitly
+allowed. Unless otherwise indicated, treat all methods as if they had
+been declared final. (These are sometimes known as "soft final" methods).
+If the kind of overriding allowed is:
+
+
-
+
- "implement" - the abstract method declared on the subclass must +be implemented by a concrete subclass +
- "extend" - the method declared on the subclass must invoke the +method on the superclass (exactly once) +
- "re-implement" - the method declared on the subclass must not +invoke the method on the superclass +
- "override" - the method declared on the subclass is free to +invoke the method on the superclass as it sees fit
+
+ - +Ensure postconditions. Do ensure that any postconditions specified +for the API method are met by the implementation upon return. + +
- +Proactively check preconditions. Do not presume that preconditions +specified for the API method have necessarily been met upon entry. Although +the method implementation would be within its rights to not check specified +preconditions, it is usually a good idea to check preconditions (when feasible +and reasonably inexpensive) in order to blow the whistle on misbehaving +callers. + +
- +Null result. Do not return null as a result from an API method unless +the result is explicitly documented (on the specifying interface or superclass) +as allowing null. + +
- +Return copies. Do not return an irreplaceable array, collection, +or other mutable object as the result from an API method. Always return +a copy to avoid trouble from callers that might modify the object. +
+Implementing platform API interfaces
+Only a subset of the API interfaces were designed to be implemented by +clients. API interfaces have a contract indicating the terms under which +it may be implemented. Interfaces that are designed to be implemented by +clients are explicitly flagged in the Javadoc class comment (with words +like "Clients may implement."). A client may declare a subinterface of +an API interface if and only if they are allowed to implement it. +-
+
- +Restricted implementors. Do not implement an API interface that +is documented as available only to certain parties unless you're one of +them. In many situations, interfaces are used to hide internal implementation +details from view. +
+Implementing public API methods
+See "Overriding API methods". ++Accessing fields in API classes and interfaces
+Clients may read API fields, most of which are final. Certain struct-like +objects may have non-final public fields, which clients may read and write +unless otherwise indicated.
+-
+
- +Null fields. Do not set an API field to null unless this is explicitly +allowed. +
+Casting objects of a known API type
++An object of a known API type may only be cast to a different API type +(or conditionally cast using instanceof) if this is explicitly allowed +in the API. +
+-
+
- +Cast and instanceof. Do not use instanceof and cast expressions +to increase what is known about an object beyond what the API supports. +Improper use exposes incidental implementation details not guaranteed by +the API. +
+And, of course, casting any object to a non-API class or interface is always +inappropriate. +
++Not following the rules
+Whether done knowingly or unwittingly, there are consequences for transgressing +the rules. It might be easier for all involved if there were API police +that would bust you for breaking the rules. However, that is not the case. +For the most part, API conformance operates as an honor system, with each +client responsible for knowing the rules and adhering to them.
+The contracts on the API elements delimit the behavior that is supported +and sustained. As the Eclipse platform matures and evolves, it will be +the API contracts that guide how this evolution happens. Outside of these +contracts, everything is unsupported and subject to change, without notice, +and at any time (even mid-release or between different OS platforms). Client +code that oversteps the above rules might fail on different versions and +patch levels of the platform; or when run on different underlying OSes; +or when run with a different mix of co-resident plug-ins; or when run with +a different workbench perspective; and so on. Indeed, no one is even particularly +interested in speculating exactly how any particular transgression might +come back to bite you. To those who choose to ignore the rules, don't say +that you weren't warned. And don't expect much more than a sympathetic +"Told you so."
+On the other hand, client plug-in code that lives by the above rules +should continue to work across different versions and patch levels of the +platform, across different underlying OSes, and should peacefully co-exist +with other plug-ins. If everyone plays by the rules, the Eclipse platform +will provide a stable and supported base on which to build exciting new +products.
+ + diff --git a/org.eclipse.pde.doc.user/reference/misc/index.html b/org.eclipse.pde.doc.user/reference/misc/index.html new file mode 100644 index 0000000000..a8ae739141 --- /dev/null +++ b/org.eclipse.pde.doc.user/reference/misc/index.html @@ -0,0 +1,20 @@ + + + + + + + +Other Reference Information
+The following specifications, white papers, and design notes describe various + aspects of the PDE.
+-
+
- Map of PDE Plug-ins + +
Map of PDE Plug-ins
+The PDE provides a comprehensive plug-in development + environment.
+PDE itself is divided up into a number of separate + plug-ins. The following table shows which API packages are found in which plug-ins + (the most commonly referenced API packages are highlighted). This table is useful + for determining which plug-ins a given plug-in should include as prerequisites. +
+| API Package | +Plug-in id | +
| org.eclipse.pde.api.tools.annotations[.*] | +org.eclipse.pde.api.tools.annotations | +
| org.eclipse.pde.core[.*] | +org.eclipse.pde.core | +
| org.eclipse.pde.launching[.*] | +org.eclipse.pde.launching | +
| org.eclipse.pde.ui[.*] | +org.eclipse.pde.ui | +
Builder Configuration Properties
+
+The overall build mechanism is driven by a builder configuration
+which includes a build.properties file.
+
-
+
- Basic Settings
++ +
++ +topLevelElementId +The id of the feature being built. +
This property is new in 3.4 and depends on the use of the 3.4 allElements.xml file. Build configurations using older style customTargets.xml and/or allElements.xml files should not use this property.+ +buildDirectory +
+The directory where the +build will take place. +
++ + +configs +
+A list of configurations to +build. A configuration is an ampersand separated list of comma +separated operating system, windowing system and architecture. If +no config is specified, the platform independent config will be +built. Example: + +++configs = win32, win32, x86 & linux, gtk, ppc
+
+
-
+
- p2 Integration
+See the p2 Integration documentation for properties controlling feature builds, and product builds.
+
-
+
- Base Control: The base is a target eclipse install
+containing plug-ins and features that you require but are not building
+yourself.
++ +
++ +baseLocation +
+The location of the target +eclipse install. In the default template, the value of this is +${base}/eclipse. (See the base property below). This +directory is expected to contain plugins/ and features/ +subdirectories +which contain the binary plug-ins and features respectively. +
++ +baseos +
+The operating system of the +eclipse specified by baseLocation +
++ +basews +
+The windowing system of the +eclipse specified by baseLocation +
++ +basearch +
+The architecture of the +eclipse specified by baseLocation +
++ +pluginPath +
+A platform path-separator +separated list of locations to find additional plug-ins and features. +
++ +skipBase +
+If set, automatically +download a base eclipse to use as a target +
++ +base +
+The location the base +eclipse will be downloaded to. This should be the parent of +baseLocation, such that baseLocation = ${base}/eclipse. +
++ +eclipseURL +
+The URL for the eclipse +download site +
++ +eclipseBuildId +
+The build ID of the eclipse +to download +
++ +eclipseBaseURL +
+The actual URL of the zip to +download. In the default template, the value is: + +++eclipseBaseURL = ${eclipseURL}/eclipse-platform-${eclipseBuildId}-win32.zip++ +filteredDependencyCheck +
+Constraint the set of plug-ins and features + to be considered during the build to the one reachable from the features / plugins being built when set to true +
++ + + +resolution.devMode +
+When set to true, the validation done on the set of plug-ins being built will be + less strict. For example it will allow multiple versions of a singleton bundle to be resolved. +
+
+
-
+
- Output
+Control: The following properties affect the shape
+of the build results.
++ +
++ +runPackager +
+Set if the packager needs to +be run. Set this if your build results need to contain binary +features and plug-ins that come from the baseLocation. +
++ +product +
+The product configuration +file. Set this if you are building a product. It controls +branding of your build results. +
++ +archiveNamePrefix +
+The prefix of the name of +the final archive files. This is used in allElements.xml when +setting the archive name on a per config basis. By default, the +value will be ${buildId} +
++ +archivePrefix +
+The name of the archive root +folder, this is "eclipse" for eclipse builds. +
++ +buildType +Type of build, normally +something like I, N, M, etc. ++ +buildLabel +The label for the build. In +the default template, the value is ${buildType}.${buildId} ++ +collectingFolder +
+The folder where the build +output will be collected. In the default template, the +value is ${archivePrefix}. +
++ +groupConfigurations +
+Whether or not to group all +configuration into one archive file. +
++ +archivesFormat +
+The archive format for the +different configs being built. This is an ampersand separated +list of configs and their archive format. The format is separated +by a dash (-). Example: +
+++archivesFormat = win32, win32, x86 - antzip & linux, gtk, ppc - tar
++ +outputUpdateJars +
+When set, generates plug-ins +and features in JAR format for an update site. +
++ +zipArgs +
+Arguments to be sent to the +zip executable when the archive format is zip. +
++ + +tarArgs +
+Arguments to be sent to the +tar executable when the archive format is tar. +
+
+
+
-
+
- Signing and Jnlp control:
++ +
++ +generateJnlp +
+Set to true to generate JNLP +manifests for the JAR archives +
++ +jnlp.codebase +
+The site URL. This +should be a URL that will be used as the root of all relative URLs in +the output. +
++ +jnlp.j2se +
+The J2SE version required to run the JNLP app being exported +
++ +jnlp.locale +
+The locale in which the generated jnlp files should be generated. +
++ +jnlp.generateOfflineAllowed +
+Generate the <offlineAllowed/> in the generated files when set to true. +
++ +jnlp.configs +
+Filter the content of the generated jnlp files based on the configuration being built. The configurations need to be listed. +
++ +signJars +
+Set to true to sign +jars for features and plug-ins. +
++ +sign.alias +
+The alias passed to the ant +signJar task. +
++ +sign.keystore +
+The keystore passed to the +ant signJar task. +
++ +sign.storepass +
+The storepass passed to the +ant signJar task. +
++ + +sign.keypass +
+The keypass passed to the +ant signJar task. +
+
+
-
+
- Version Control. (See also Version Qualifiers)
++ +
++ +forceContextQualifier +
+The value of this property +is used when replacing qualifiers in plug-in and feature +versions. If set it is used instead of the tags from the map +files +or the timestamp. +
++ +generateFeatureVersionSuffix +
+Set to true to generate +feature version suffixes +
++ + +generateVersionsLists +
+Set to true to generate +properties files listing the final version numbers of features and +plug-ins being built. This will create +finalFeaturesVersions.properties +and finalPluginsVersions.properties files in the builder directory. +
+
+
+ - Fetch phase Control (See also Fetching
+from Repositories)
++ +
++ +skipMaps +
+If set, do not attempt to +fetch map files from CVS +
++ +mapsRepo +
+The CVS repository to fetch +map files from. Example: +
+++:pserver:anonymous@example.com/path/to/repo
++ +mapsRoot +
+The path in the CVS +repository to the directory containing the map files +
++ +mapsCheckoutTag +
+The CVS tag to use to +checkout the map files +
++ +tagMaps +
+Set to true to tag the map +files after fetching them. +
++ +mapsTagTag +
+The tag with which to tag +the map files after fetching them. +
++ +skipFetch +
+Set to true to skip the +entire fetch phase. +
++ + +fetchTag +
+The tag to use when fetching +features and plug-ins from CVS. This property overrides the +values in the map files. +
+
+
-
+
- Compilation Control (See also Controlling
+Compilation Environment)
++ +
++ +logExtension +
+The extension of the +generated log file. This only applies when using the default JDT +compiler. Default value is ".log". +
++ +javacDebugInfo +
+Whether or not to include +debug info in the output jars. This is passed to the ant javac +task. If not set, default value is on. +
++ +javacFailOnError +
+Whether or not to fail the +build if there are compilation errors. This is passed to the ant +javac task. If not set, default value is true. +
++ +javacVerbose +
+Whether or not to enable the +verbose mode of the compiler. This is passed to the ant javac +task. If not set, default value is false. +
++ +compilerArg +
+Set specific arguments to +pass directly to the compiler. +
++ +javacSource +
+The java source +compatibility level to use if a plug-in does not specify any +settings. If not set, 1.3 is the default value. +
++ +javacTarget +
+The target .class +compatibility level to use if a plug-in does not specify any +settings. If not set, 1.2 is the default value. +
++ +flattenDependencies +
+Sort bundle dependencies across feature boundaries. (See also Compilation Order and Parallelization) +
++ +parallelCompilation +
+Set to true to enable parallel compilation. (Requires flattenDependencies=true) ++ +parallelThreadCount +
+The maximum number of threads to use. Corresponds to threadCount on the ant parallel task. ++ +parallelThreadsPerProcessor +
+The maximum number of threads to use per available processor. Corresponds to threadsPerProcessor on the ant parallel task. ++ +bootclasspath +
+The bootclasspath to use if +the plug-in does not specify any settings itself. This is a +platform path separator separated list of jars. If not set, the +file set matching ${java.home}/jre/lib/*.jar will be used. +
++ + +<Execution Environment> +
+Set properties for each JRE +that can be used to build. These properties will match up against +Execution Environments specified by individual bundles. The +values should specify the jars to compile against when using that +environment. See Controlling +Compilation Environment. +
+
+
-
+
- Other properties
++ +
+generateAPIDescription +Enable automatic generation of API description files for bundles. +generateSourceReferences +Enable generation of Eclipse-SourceReferences headers into bundle manifests. +
+
+
Feature and Plug-in Build Configuration Properties
+
+The build mechanism is driven by a build configuration. The +build configuration for an individual plug-in, fragment, or feature is +found +in a build.properties file for the corresponding element.
+PDE project creation wizards generate the build.properties +file when +plug-in projects are created. The file contains information on how to +compile source folders into +JARs. This information can be indirectly updated in the Runtime page of +the +manifest editor. It can also be directly modified using the appropriate +editor.
+PDE provides a simple editor for the build.properties that +has form and source views. +The file itself follows the Java properties format. You need to provide +a number of +keys and their corresponding values. Multiple values are separated +using a comma +as the delimiter.
+Common properties
+-
+
- bin.includes - lists files that will included in the +binary version of the plug-in being built; +
- bin.excludes - lists files to exclude from the binary +build; +
-
+
- qualifier - when the element version number ends with .qualifier +this indicates by which value ".qualifier" must be replaced. The value +of the property can either be context, <value> or + none. Context will generate a date according to the system +date, or use the CVS tags when the built is automated. Value is an +actual value. None will remove ".qualifier". If the property is +omitted, context is used. (See Version Qualifiers.) +
-
+
- custom=true - indicates that the build script is +hand-crafted as opposed to automatically generated. Therefore no other +value is consulted. +
-
+
- customBuildCallbacks -
+indicates an xml file containing custom targets to use when using this
+feature/plug-in. (See Feature
+and Plug-in Custom Build Steps)
+
+ - customBuildCallbacks.failonerror -
+ sets the subant task's failonerror parameter. The default is "false".
+
+ - customBuildCallbacks.buildpath -
+ sets the subant task's buildpath parameter. Use when the location of the custom callbacks file is not
+ relative to the root of the plug-in.
+
+ - customBuildCallbacks.inheritall - sets the subant task's inheritall parameter. Ant's default is false.
+
+
Plug-in specific properties
+-
+
- source.<library> - lists source folders that will be +compiled (e.g. source.xyz.jar=src/, src-ant/). If the library +is specified in your plug-in.xml or manifest.mf, the value should match +it; +
- output.<library> - lists the output folder receiving +the result of the compilation; +
- exclude.<library> - lists the files that should not +be copied into the library by the compiler; +
- extra.<library> - extra classpaths used to perform +automated build. Classpath can either be relative paths, or platform +urls referring to plug-ins and fragments of your development +environment (e.g. ../someplugin/xyz.jar, platform:/plugins/org.apache.ant/ant.jar). +Platform urls are recommended over relative paths; +
- manifest.<library> - indicate the file that will be +used as a manifest for the library. The file must be located in one of +the source folder being used as input of the jar. +
-
+
- src.includes - lists files to include in the source build; +
- src.excludes - lists files to exclude from the source +build; +
-
+
- jars.extra.classpath - (deprecated) same effect +than extra.<library> except that the entries are applied to all +libraries; +
- jars.compile.order - defines the order in which jars +should be compiled (in case there are multiple libraries). +
-
+
- jre.compilation.profile - +set the Environment used to compile this bundle. + +
- javacSource - set the
+source compatibility level for compiling this bundle. Overrides
+jre.compilation.profile.
+
+ - javacTarget - set the +target .class compatibility level for compiling this bundle. +Overrides jre.compilation.profile. +
- bootClasspath - set the
+boot classpath to compile this bundle against, Overrides
+jre.compilation.profile.
+
+
-
+
- javacWarnings.<library> +- set the warning options to pass to the compiler. (See the -warn option in +Using the batch compiler +from the Java development user guide). +
- javacErrors.<library> +- set the error options to pass to the compiler. (See the -err option in +Using the batch compiler +from the Java development user guide). +
- javacDefaultEncoding.<library> +- sets default encoding to use when compiling the given library. +
- javacCustomEncodings.<library>
+- a comma separated list of
+paths and encodings to use when compiling the given library.
+Example:
+++javacCustomEncodings.library.jar = src/org/foo[US-ASCII], src/org/foo/bar.java[ISO-8859-1]
+
+ - javacProjectSettings - A relative path to a preference file specifying properties for the JDT Compiler. Set to true to use the default ".settings/org.eclipse.jdt.core.prefs". +
- compilerArg - specify custom compiler arguments +
- compilerAdapter - specify a custom compiler adapter to use instead of the default org.eclipse.jdt.core.JDTCompilerAdapter +
- compilerAdapter.useLog - true/false: whether or not the custom compiler adapter should receive the -log argument. +
- compilerAdapter.useArgFile - true/false: whether or not the custom compiler adapter should receive the generated javaCompiler.<library>.args argument file. +
- sourceFileExtensions - a list of extensions (*.java, *.aj) that should be considered as source when using a custom compiler adapter. + +
The values +defined for these keys ending with "includes" or "excludes" are +expressed as Ant "patterns". Standard formats give the expected +results. For example, "*.jar" indicates all jar files in +the top level directory. The patterns are not deep by default. If +you want to +describe all Java files for example, you should use the pattern "**/*.java". +The pattern "**" matches any number of directory levels. +Similarly, to describe whole sub-trees, use "xyz/".
+Feature specific +properties
+-
+
- root - List the files and folders that must be included in
+the root of the product. See the Rootfiles help page for more detail, incuding the following additional properties:
+
-
+
- root.<config>: per configuration rootfiles. +
- root.folder : rootfiles placed in subfolders. +
- root.permissions : perform chmods on rootfiles. +
- root.link : generate softlinks for rootfiles. +
+ - root.<config> - list the files and folders that must +be included in the root of the product when it is built for the +specified configuration. config is composed of the three (3) segments +of a configuration separated with a dot; +
-
+
- root.permissions.<permissionValue> - list the files +and folders to chmod to the given value. Reference to folders must ends +with a '/'; +
- root.permissions.<config>.<permissionValue> - +list the files and folders to chmod to the given value for a specific +configuration. Reference to folders must ends with '/'; +
-
+
- root.link - list by pairs (separated by a comma) the files +and folders that need to be symbolicly linked. The first entry indicate +the source (target in the unix terminology) and the second entry the +link name; +
- root.link.<config> - a comma separated list of pairs +of files and folders that need to be symbolicly linked for a specific +configuration. The first entry indicate the source (target in the unix +terminology) and the second entry the link name; +
-
+
- generate.feature@<featureId> - indicates that the
+source feature featureId will be the source feature for the
+feature indicated as value of this property. The values listed after
+the first comma indicates elements to be fetched from the
+repository; (See Source
+Plugin and Feature Generation)
+
+ - generate.plugin@<pluginId> - indicates that the +source plug-in pluginId will be the source plug-in for the +indicated as value of this property. +
-
+
- significantVersionDigits
+- The number of significant digits used when generating feature version
+suffixes (See Version
+Qualifiers)
+
+ - generatedVersionLength -
+The length of the generated feature version suffix.
+
+
bin.includes=epl-v10.html,feature.xml,feature.properties,license.html+
root=rootfiles,configuration/
root.permissions.755=eclipse
root.linux.motif.x86=../../plugins/platform-launcher/bin/linux/motif,linux.motif
root.linux.motif.x86.link=libXm.so.2.1,libXm.so.2,libXm.so.2.1,libXm.so
root.linux.motif.x86.permissions.755=*.so*
+ + diff --git a/org.eclipse.pde.doc.user/schema.css b/org.eclipse.pde.doc.user/schema.css new file mode 100644 index 0000000000..a03ed6a451 --- /dev/null +++ b/org.eclipse.pde.doc.user/schema.css @@ -0,0 +1,71 @@ +/******************************************************************************* + * Copyright (c) 2004, 2009 IBM Corporation and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * IBM Corporation - initial API and implementation + *******************************************************************************/ + +H6.SchemaHeader { + font-size:16px; + display:inline +} + +P.SchemaCopyright { + font-size: smaller; + font-style: normal; + color: #336699; + display:inline; + margin-top: 3.000000pt; + margin-bottom: 11.000000pt; + margin-right: 0.000000pt; + margin-left: 0.000000pt; +} + +P.SchemaDtd { + color: #800000; + margin-top: 0.000000pt; + margin-bottom: 0.000000pt; + margin-right: 0.000000pt; + margin-left: 10.000000pt; +} + +P.SchemaDtdAttlist { + color: #800000; + margin-top: 0.000000pt; + margin-bottom: 0.000000pt; + margin-right: 0.000000pt; + margin-left: 20.000000pt; +} + +span.SchemaTag { + color: #000080; +} + +span.SchemaCstring { + color: #008000; +} + +pre.Example { + margin-top: 0.000000pt; +} + +.ConfigMarkupElementDesc { + color: black; + margin-top: 0.000000pt; + margin-bottom: 0.000000pt; + margin-right: 0.000000pt; + margin-left: 10.000000pt; +} + +.ConfigMarkupAttlistDesc { + color: black; + margin-top: 0.000000pt; + margin-bottom: 0.000000pt; + margin-right: 0.000000pt; + margin-left: 32.000000pt; +} + diff --git a/org.eclipse.pde.doc.user/tasks/api_tooling_baseline.htm b/org.eclipse.pde.doc.user/tasks/api_tooling_baseline.htm new file mode 100644 index 0000000000..096a58b01c --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/api_tooling_baseline.htm @@ -0,0 +1,35 @@ + + + + + + + +
Setting up an API baseline
+Once your plug-in is converted to use API Tools, 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. +
Related references
+API Baselines Preferences+API Baseline Wizard
+Missing API Baseline Quick Fix + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/api_tooling_compare_to_baseline.htm b/org.eclipse.pde.doc.user/tasks/api_tooling_compare_to_baseline.htm new file mode 100644 index 0000000000..f3a3e37e47 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/api_tooling_compare_to_baseline.htm @@ -0,0 +1,40 @@ + + + + + + + +
Comparing to an API baseline
+Any API Tools 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 Tools view. +
Related tasks
+Setting up a baseline + +Related references
+API Baselines Preferences+API Baseline Wizard
+Missing API Baseline Quick Fix + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/api_tooling_create_filters.htm b/org.eclipse.pde.doc.user/tasks/api_tooling_create_filters.htm new file mode 100644 index 0000000000..135327ad01 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/api_tooling_create_filters.htm @@ -0,0 +1,35 @@ + + + + + + + +
Creating API Problem Filters
+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 quick fix.
+Using the quick fix let's see how we can add a new filter.
+The Problems view
+-
+
- Open the Problems view. +
- Select an API Tools problem. +
- Use Ctrl + 1 to trigger the quick fix from the Problems 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 quick fix 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.
+ +Related references
+API Problem Filters Property Page+Add API Problem Filter Quick Fix + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/api_tooling_options.htm b/org.eclipse.pde.doc.user/tasks/api_tooling_options.htm new file mode 100644 index 0000000000..1c5184387a --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/api_tooling_options.htm @@ -0,0 +1,37 @@ + + + + + + + +
Changing API Tools 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. +
Related references
+API Errors and Warnings Preferences + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/api_tooling_remove_filters.htm b/org.eclipse.pde.doc.user/tasks/api_tooling_remove_filters.htm new file mode 100644 index 0000000000..0f3f53c75e --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/api_tooling_remove_filters.htm @@ -0,0 +1,32 @@ + + + + + + + +Removing filters
+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. +
Related tasks
+Creating filters+
Related references
+API Problem Filters Property Page+Add API Problem Filter Quick Fix
+Remove Unused API Problem Filter Quick Fix + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/api_tooling_setup.htm b/org.eclipse.pde.doc.user/tasks/api_tooling_setup.htm new file mode 100644 index 0000000000..ea7e10880e --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/api_tooling_setup.htm @@ -0,0 +1,45 @@ + + + + + + + +
Setting up API Tools
+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 Tools Setup... +
- Once the API Tools 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 Tools. +
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. +
Related tasks
+ Setting up a baseline+
Related references
+ API Tools Setup Wizard+ PDE Tools Menu
+ API Tools Setup Command
+ Defining API Restrictions + + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/pde_compilation_env.htm b/org.eclipse.pde.doc.user/tasks/pde_compilation_env.htm new file mode 100644 index 0000000000..650798f133 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_compilation_env.htm @@ -0,0 +1,234 @@ + + + + + + + +
Setting the Compilation Environment
+By default, your bundles will be compiled with whichever JRE is
+being used to run the build and with source and target levels set to
+1.3 and 1.2.
+
PDE build is capable of configuring the JRE used during compilation
+on a per bundle basis. To take advantage of this, the first thing
+to do is to tell PDE build which JREs you have available. In your
+build configuration build.properties file, set properties to point to
+each of your installed JREs. The template build.properties
+provided in org.eclipse.pde.build/templates/headless-build has a list
+of environments commented out. Simply uncomment the properties
+for which you have JREs and set the value to be the set of jars that
+belong on the boot classpath. For example, setting the property:
+
+
will compile bundles requiring java 1.5
+against rt.jar and jsse.jar. The names of the properties should
+match the names of the environments that PDE Build knows
+about.
+PDE Build will automatically set the source and target levels for each
+environment. The environments that PDE builds knows and their
+associated source/target levels are as follows:
+
| Environment + |
+ Source + |
+ Target + |
+
| CDC-1.0/Foundation-1.0 + |
+ 1.3 + |
+ 1.1 + |
+
| CDC-1.1/Foundation-1.1 + |
+ 1.3 + |
+ 1.2 + |
+
| OSGi/Minimum-1.0 + |
+ 1.3 + |
+ 1.1 + |
+
| OSGi/Minimum-1.1 + |
+ 1.3 + |
+ 1.2 + |
+
| JRE-1.1 + |
+ 1.1 + |
+ 1.1 + |
+
| J2SE-1.2 + |
+ 1.2 + |
+ 1.1 + |
+
| J2SE-1.3 + |
+ 1.3 + |
+ 1.1 + |
+
| J2SE-1.4 + |
+ 1.3 + |
+ 1.2 + |
+
| J2SE-1.5 + |
+ 1.5 + |
+ 1.5 + |
+
| JavaSE-1.6 + |
+ 1.6 + |
+ 1.6 + |
+
| PersonalJava-1.1 + |
+ 1.1 + |
+ 1.1 + |
+
| PersonalJava-1.2 + |
+ 1.1 + |
+ 1.1 + |
+
| CDC-1.0/PersonalBasis-1.0 + |
+ 1.3 + |
+ 1.1 + |
+
| CDC-1.0/PersonalJava-1.0 + |
+ 1.3 + |
+ 1.1 + |
+
| CDC-1.1/PersonalBasis-1.1 + |
+ 1.3 + |
+ 1.2 + |
+
| CDC-1.1/PersonalJava-1.1 + |
+ 1.3 + |
+ 1.2 + |
+
Choosing the Environment for your Bundle
+There are two settings that affect the environment used to compile your +bundle. One is the manifest header Bundle-RequiredExecutionEnvironment. +This header is a list of environments on which your bundle is able to +run. Your bundle should only use methods that are in the proper +subset of all the environments listed. It is desirable to have +your compilation environment match your runtime environment as closely +as possible.+
+The second setting is the property jre.compilation.profile +from your bundle's build.properties file. The value of this +property should be the preferred environment for compiling this bundle +if the Bundle-RequiredExecutionEnvironment list is not adequate.
+
+These two settings together form a list of environments, +jre.compilation.profile first, then the environments from +Bundle-RequiredExecutionEnvironment. The first +environment on this list that is available in your build configuration +(see above section) will be used to compile your bundle.
+
+Example:
+
<buildDirectory>/plugins/bundleA/+
META-INF/manifest.mf: Bundle-RequiredExecutionEnvironment: CDC-1.0/Foundation-1.0, J2SE-1.3
build.properties: jre.compilation.profile=J2SE-1.4
<buildConfiguration>/
build.properties: J2SE-1.3=C:/Java1.3/jre/lib/rt.jar;C:/Java1.3/jre/lib/i18n.jar
J2SE-1.4=C:/Java1.4/jre/lib/rt.jar;C:/Java1.4/jre/lib/jsse.jar
In the above setup, the list of
+environments considered (in order) is: J2SE-1.4,
+CDC-1.0/Foundation-1.0, J2SE-1.3. The bundle can run on
+CDC/Foundation and J2SE-1.3, but for some reason, it should be
+compiled with J2SE-1.4. In this case, J2SE-1.4 is set in the
+build configuration and comes first in the list of environments, so it
+is used to compile the bundle. The source and target levels used
+in this case are 1.3 and 1.2. If instead, the build configuration
+defined only J2SE-1.3 and not J2SE-1.4, then J2SE-1.3 would be the only
+environment on the list for which a JRE is available, so it would be
+used to compile the bundle. In that case, the source and target
+levels would be 1.3 and 1.1.
+
Explicitly Setting Compilation values
+If, for some reason, using the environments as outlined above does not +result in the desired setup, then it is possible for a bundle to +explicitly list the settings it requires. For example, if you +have a bundle that uses J2SE-1.4 with asserts, then the source and +target levels would need to be 1.4, instead of the default 1.3 and 1.2.+
+To explicitly set the java source and target levels, the bundle should +set the properties javacSource and +javacTarget in its +build.properties +file. These properties will override the values derived from the +environment settings.
+
+Similarly, setting the property bootClasspath in the +bundle's build.properties file will override the set of +jars the bundle is compiled against.
+
+ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_compilation_order.htm b/org.eclipse.pde.doc.user/tasks/pde_compilation_order.htm new file mode 100644 index 0000000000..afc5d8dc5a --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_compilation_order.htm @@ -0,0 +1,53 @@ + + + + + + + +
Compilation Order and Parallelization
+By default, PDE/Build compiles plug-ins by delegating through the feature structure. Features are visited depth first, the plug-ins within each feature are compiled in dependency-order (as determined by the OSGi resolver).
+This means that all dependencies of a given bundle must contained in the same feature, or in a feature that appears earlier in the depth-first traversal of the feature inclusion hierarchy. This can make it difficult to organize your +features.
+ +Flattening Dependencies
+New in 3.5 is a builder property flattenDependencies. Setting this property to true will cause PDE/Build to instead sort all plug-ins regardless accross feature boundaries. PDE/Build will then generate a new build script +compile.<feature>.xml which lists all plug-ins in order sorted by their dependencies. This allows you to partition your bundles into different features according to their functionality without worrying about their inter-dependencies.
+ +Parallel Compilation
+If flattenDependencies is specified, then PDE/Build is then able to compile bundles in parallel. It does this by partitioning the sorted list of bundles into groups where each group contains bundles that depend only on bundles in earlier groups.
+Each group is then wrapped in an Ant <parallel> task. The following properties control the parallelization behaviour:
+| parallelCompilation | Set to true to enable parallel compilation. (Requires flattenDependencies=true) |
| parallelThreadCount | The maximum number of threads to use. Default is 3. Corresponds to threadCount on the ant parallel task. |
| parallelThreadsPerProcessor | The maximum number of threads to use per available processor. Corresponds to threadsPerProcessor on the ant parallel task. |
The resulting compile script that gets generated then looks something like this:
++ <project name="Compile master" default="main"> + <target name="main"> + <parallel threadsPerProcessor='3'> + <ant antfile="build.xml" dir="plugins/org.eclipse.osgi" target="build.jars"/> + </parallel> + <parallel threadsPerProcessor='3'> + <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.common" target="build.jars"/> + <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.p2.jarprocessor" target="build.jars"/> + </parallel> + <parallel threadsPerProcessor='3'> + <ant antfile="build.xml" dir="plugins/org.eclipse.update.configurator" target="build.jars"/> + <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.simpleconfigurator" target="build.jars"/> + <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.frameworkadmin" target="build.jars"/> + <ant antfile="build.xml" dir="plugins/org.eclipse.core.jobs" target="build.jars"/> + <ant antfile="build.xml" dir="plugins/org.eclipse.core.databinding.observable" target="build.jars"/> + <ant antfile="build.xml" dir="plugins/org.eclipse.swt" target="build.jars"/> + ... + ++ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_compiler_options.htm b/org.eclipse.pde.doc.user/tasks/pde_compiler_options.htm new file mode 100755 index 0000000000..ce0c09aab8 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_compiler_options.htm @@ -0,0 +1,83 @@ + + + + + + + +
Compiler options
+PDE/Build supports a number of options to control the compiler for individual plug-ins. For settings related to +source and target levels and bootclasspath, see "Setting the Compilation Environment". +
+ +Warnings and Errors
+PDE/Build allows specifying custom compile warnings and errors in the build.properties file. These can be set on a per library basis (a single plug-in can +contain multiple jar libraries) with the javacWarnings.<library> and javacErrors.<library> options. The values for these properties +are given in the "-warn:..." section on the using the batch compiler page (from the Java development user guide).
+ +Example: +javacErrors.. = forbidden,discouraged, + javacWarnings.library.jar = deprecation,nullDereference ++ +
Warnings and Errors from Project preferences
+The JDT project preferences can now also be used during PDE/Build. PDE/Build itself is not able to read the preference files, but it is able to pass them +to the JDT compiler which does understand them. + +To use this, a plug-in should specify the javacProjectSettings property in its build.properties file. The value should be: +-
+
- javacProjectSettings=true : Use the project setting specified in the default .settings/org.eclipse.jdt.core.prefs preferences file. +
- javacProjectSettings=path/to/jdt.prefs : Use the specified preference file. +
File Encoding
+PDE/Build can accept custom file encodings on a per library, folder or file basis. +-
+
- javacDefaultEncoding.<library> +- sets default encoding to use when compiling the given library. +
- javacCustomEncodings.<library>
+- a comma separated list of
+paths and encodings to use when compiling the given library. When specifying a folder, the encoding is used for everything contained in that folder. When
+specifying a file, the encoding is used for just that file.
+Example:
+++javacCustomEncodings.library.jar = src/org/foo[US-ASCII], src/org/foo/bar.java[ISO-8859-1]
+
+
Custom Compiler Arguments
+Custom compiler arguments can now be specified per bundle using the compilerArg property in the bundle's build.properties file. This property is similar +to the compilerArg property in the builder configuration except that it affects only the single plug-in instead +of all plug-ins. The specific arguments here depend on the compiler being used. The JDT compiler arguments are listed here. + +Compiler Option Precedence
+There are a number of difference ways to specify different compiler options. As a general rule, option precedence is as follows: +-
+
- javacDefaultEncoding.<library> has precedence over a custom -encoding command line option. +
- For general options, an option appearing later on the compiler command line overrides options specified earlier. The options are provided to the JDT in the following order:
+
-
+
- The compilerArg property from the builder configuration. (Affects all bundles). +
- The compilerArg property from this plug-in's build.properties. +
- The compiler preferences file specified with javacProjectSettings. +
- The generated compiler arguments file (javaCompiler.<library>.args) containing file encodings, javacWarnings, javacErrors and access rules. +
+
Using a Custom Compiler
+A bundle can now use a custom compiler by setting the compilerAdapter property. The specified compiler adapter must be available in the ant environment. The JDT compiler +adapter used by default is org.eclipse.jdt.core.JDTCompilerAdapter. One particular reason for specifying an alternate compiler is for Aspect J or Groovy bundles. Bundles specifying +a custom compiler adapter may need to also specify some of the following properties: +-
+
- sourceFileExtensions : A list of extensions that should be considered source. (eg *.java, *.aj, *.groovy). +
- compilerAdapter.useLog : whether or not to pass "-log" argument to the compiler +
- compilerAdapter.useArgFile : whether or not to pass the generated javaCompiler.<library>.args argument file. (Contains access rules, file encodings and warning/error levels). +
Controlling the output format of the build
++This section describes how to control the output of a feature or +product build.
+Controlling the output format
++The archivesFormat property allows specifying the output format (zip, +tar, and folder) of the build on a configuration basis. The format of +the property is <configuration> - <format>, where +configuration is the same value as specified in the configs +property and format is one of the following.
+-
+
- folder - the output will be stored in a folder located +in ${buildDirectory}/tmp/${archivePrefix}. The targets +specified in the allElements.xml are not used in this case. +Due to current restrictions, only one configuration can be build at a +time when using folder as output format. +
- zip - the output will be stored in a zip file. The zip +file will be created by the zip.exe found on the machine running the +build. This is useful if you have non jar'ed plug-ins that contains +files requiring specific permissions (mostly on UNIX based systems). +The property zipargs allows passing additional options to the +zip command. +
- antZip - the output will be stored in a zip file. The +zip file will be created by Ant's implementation of zip. This is the +default value when nothing is specified. +
- tar - the output will be stored in a gzip'ed tar file. +The OS implementation of tar and gzip will be used. The property tarargs +allows passing additional options to the tar command. +
Generating JNLP manifests
++To enable the generation of JNLP manifests at build time, set generateJnlp +to true, set jnlp.codebase to be the value where +the +jnlp file will be served from (see codebase attribute in jnlp tag), and set jnlp.j2se. +Note that this will not package your plug-ins and features for an +update site, see the "preparing the output for an update site or jnlp +site" below. +Due to current restrictions, the creation of the jnlp manifest only +works when producing folders as an output format. +
+Preparing the output for an update site or jnlp site
++When put on an update site or a java web start site, plug-ins and +features need to be packaged properly. To do this, simply set the outputUpdateJars +property to true. Note that this will not generate the site.xml for the +eclipse update site and it will not generate jnlp files (see generating +jnlp files). +
+Grouping multiple configurations in one archive
+In order to produce an output that contains the plug-ins and features +of multiple configurations, set groupConfigurations to true. +This will create an archive that contains all the plug-ins and features +that match the configurations listed in the configs property. +When using this, don't forget to add a target named <feature.id>.group.group.group +in the allElements.xml file. +Due to current restrictions, the usage of this option will cause the +value specified in archivesFormat to be ignored and antZip +will be used by default. +Signing jars
++In order to sign jars during the build, set the property signJars +to true and set values for the properties sign.alias, sign.keystore, +and sign.storepass. +
+ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_custom_callbacks.htm b/org.eclipse.pde.doc.user/tasks/pde_custom_callbacks.htm new file mode 100644 index 0000000000..3172ac294f --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_custom_callbacks.htm @@ -0,0 +1,181 @@ + + + + + + + +Feature and Plug-in custom build steps
+New in 3.2 is the ability for a feature or plug-in to contribute +custom ant targets to its own build. These custom steps can be +used for things like instrumenting byte-code after compilation, +indexing help files for documentation, or copying extra files into the +bundle.
+To use custom targets, a feature or plug-in must define the property +customBuildCallbacks in its build.properties file; the value +of this +property is the location of an xml file, relative to the root of the +feature/plug-in, containing the custom targets. If the xml file is located elsewhere, use the property +customBuildCallbacks.buildpath to set the directory to use.
+Templates named +customBuildCallbacks.xml +containing the supported custom targets are +provided in org.eclipse.pde.build/templates/plugins and +org.eclipse.pde.build/templates/features. These +templates can be copied into your feature/plug-in and modified as +needed.
++ The custom targets will be invoked using the subant task; by default, failonerror is set to false. To change this +set the property customBuildCallbacks.failonerror to true. Similarly, the inheritall parameter defaults to false. Set the +property customBuildCallbacks.inheritall to change this. +
+Plug-ins
+The generated build.xml that builds a plug-in contains several
+targets that perform specific tasks. PDE Build allows the plug-in
+to provide custom pre and post targets that will be called before and
+after specific tasks. In addition to any ant properties that may
+already be defined, each custom target may also be passed a couple of
+specific properties. The following targets support custom
+callbacks:
+
-
+
- build.jars: The +build.jars target will invoke in turn each of the compilation targets +that will be built for this bundle. It supports pre.build.jars and post.build.jars targets which are +called before and after all the compilation targets are called. +Both the pre and post targets are provided with the property build.result.folder +which is the folder to which the +results of the +build will be copied. +
- Compilation Targets:
+The build.xml defines a compilation target for each jar being built (eg
+@dot for the bundle itself, or library.jar). Each compilation
+target supports 3 custom callbacks:
+
-
+
- pre.<compilation target>:
+Called before source files are compiled. It is provided with the
+following properties:
+
-
+
- target.folder: The folder where the compiled +class +files will be placed +
- source.folder<N>: The source folder(s) +containing +the source to be compiled. (e.g. source.folder1, source.folder2, +etc). +
- <compilation target>.classpath: A
+reference to
+the ant path structure containing the classpath that will be used in
+the compilation. (e.g. @dot.classpath, library.jar.classpath). The reference to the classpath should be used with a refid.
+
Example: ++<classpath refid="library.jar.classpath"/> +<property name="mypath" refid="library.jar.classpath" /> +
+
+
+ - post.compile.<compilation +target>: Called after the source is compiled, but +before the class files are jared or copied into the build result +folder. +It is provided with the same properties as the pre.<compilation +target> target. +
- post.<compilation target>:
+Called at the end of the compilation target after the results are
+copied to the build result folder. It is provided with the
+following properties:
+
-
+
- jar.Location: The jar or folder containing the +compilation results. +
- <compilation target>.classpath: A reference to +the ant path structure containing the classpath that was used in the +compilation. +
+
+ - pre.<compilation target>:
+Called before source files are compiled. It is provided with the
+following properties:
+
- build.sources: This +target builds the source zips for each of the compilation +targets. It supports pre.build.sources +and post.build.sources +targets. Both of these targets are provided with the property +build.result.folder which is the folder to which the source zip files +will be copied. +
- gather.bin.parts:
+This target copies the build results (i.e. the jars and any other files
+being included in the bundle) to the final destination directory.
+It is also the target where the version qualifiers are replaced in the
+manifest file (see Version
+Qualifiers). It supports pre.gather.bin.parts
+and post.gather.bin.parts
+targets. Two properties are provided to the pre and post targets:
+
-
+
- build.result.folder: the folder containing the +results of +the build +
- target.folder: the destination folder to which +the build +results and bundle contents are being copied. +
+ - gather.sources: This
+target gathers the source zips for the bundle. It supports pre.gather.sources and post.gather.sources targets.
+Both the pre
+and post targets are provided with the target.folder property which is
+the folder that the sources are being copied to.
+
+ - gather.logs: This
+target collects the log files from the build. It supports pre.gather.logs and post.gather.logs. Both the pre
+and post
+targets are provided with the destination.temp.folder which is the
+temporary folder that the logs files are being copied to.
+
+ - clean: This target
+performs a clean, it supports pre.clean
+and post.clean targets.
+The pre and post targets have the following properties:
+
-
+
- plugin.destination: The folder that the final
+bundle was
+copied to.
+
+ - build.result.folder: The folder that the results +of the +build were copied to +
- temp.folder: The temporary folder where the results
+were staged before being copied to the final destination.
+
+
+ - plugin.destination: The folder that the final
+bundle was
+copied to.
Features
++The generated build.xml for features only supports custom build +callbacks for the gather.bin.parts target. This target will +invoke the gather.bin.parts target of all the included features and +plug-ins. It supports pre.gather.bin.parts and +post.gather.bin.parts. Both of these targets are provided with +the following properties: +
+-
+
- destination.temp.folder: The directory to which +the plug-ins will be copied. +
- feature.directory: The directory to which the
+files for
+this feature will be copied.
+
+
Customizing a Headless Build
+There are multiple methods for customizing a headless build:
+-
+
- Using a customTargets.xml file +
- Using an allElements.xml file +
- Using a customAssembly.xml file +
- Using feature or plug-in custom callbacks. (See Customizing feature and plug-in builds) +
The exact format of the contents of these files all depend on each other. Therefore, when using customTargets, allElements or customAssembly customizations, it is recommended to ensure that the templates used for these files all come from the same version of PDE/Build. New versions of PDE/Build are backward compatible with old versions of these customization scripts.
+Template versions of these scripts are available in the org.eclipse.pde.build plug-in under the templates/headless-build folder. To use the customization, simply copy the template into your build configuration directory and edit the appropriate targets.
+ +customTargets.xml
+The customTargets.xml script is for top level customization of the build process. It provides ant targets that are called between the major phases of the build. There are pre and post targets available around each of the following build steps:
+-
+
- Process p2 repositories +
- Get Map files +
- Fetch source +
- Generate build scripts +
- Process and run the build scripts +
- Assemble the compiled plug-ins and features +
- Package pre-compiled binary plug-ins and features +
To use the customTargets.xml script, simply copy it from the PDE/Build templates directory into your build configuration directory and edit the appropriate ant targets. The script will be automatically detected and used by the headless build.
+The customTargets.xml script also provides delegation to the allElements.xml script for each of the build phases.
+ +allElements.xml
+The allElements.xml script is a kind of delegation script that is used to run the various build steps on a given element (usually a feature). As with the customTargets.xml, to use these customization steps, copy the template from PDE/Build into your build configuration directory. In Eclipse 3.4, the target element that will be built can be specified in the top level build configuration build.properties file using the properties topLevelElementType and topLevelElementId. The elementType should be set to feature and the elementId should be set to the feature-id you wish to build.
+
+ <target name="allElementsDelegator">
+ <ant antfile="${genericTargets}" target="${target}">
+ <property name="type" value="${topLevelElementType}" />
+ <property name="id" value="${topLevelElementId}" />
+ </ant>
+ </target>
+
+The allElements.xml also provides targets used during the assembly and packaging phase of the build. The defaultAssemble target will be called to assemble the archives for all platforms. If desired, custom targets can be defined for individual platforms.
+To use a custom target for a given platform, define a property "assemble.<element-id>[.<config>] and a corresponding target. The property tells PDE/Build to use this custom target instead of the default target. This custom target can then be used to give the archive a custom name or perform pre or post processing on the archive.
+Example:
+
+ <property name="assemble.org.foo.feature.id.linux.gtk.x86" value="true" />
+ <target name="assemble.org.foo.feature.id.linux.gtk.x86">
+ <property name="archiveName" value="acme-RCP-${buildId}-linux.gtk.x86.tar.gz" />
+ <-- custom pre assemble steps for linux.gtk.x86-->
+ <ant antfile="${assembleScriptName}" dir="${buildDirectory}"/>
+ <-- custom post assemble steps for linux.gtk.x86-->
+ </target>
+
+
+customAssembly.xml
+The customAssembly.xml script is new in 3.4. It provides customization points that will be called during the assembly and packaging phases of the build. As with customTargets.xml and allElements.xml, to use these customization, copy the template from PDE/Build into your build configuration directory.
+The assemble and packaging scripts generated by PDE/Build perform the following actions:
+-
+
- Call the gather.bin.parts target in the generated build.xml for all features and plug-ins being built. +
- Jar up (and optionally sign) any plug-ins and features that are not shipped as folders +
- Copy the final results into a staging area and create the final archive +
The assemble scripts deal with collecting the features and plug-ins that were compiled during the build and the package scripts deal with collecting any pre-compiled binary features and plug-ins. The customAssembly.xml script provides the following targets before or after each of the above steps:
+-
+
- gather.bin.parts: Called after each invocation of the gather.bin.parts target on the individual plug-ins and features. +
- post.gather.bin.parts: Called after invoking the gather.bin.parts targets for all plug-ins and features. Results exist as folders and have not yet been jarred. +
- pre.jarsigning: Called just prior to signing a jar. +
- post.jarup: Called after all plug-ins and features have been jarred (and potentially signed). +
- pre.archive: Called just before the archive file is built +
Building features
++PDE Build comes with infrastructure to automate building features. +Most of the setup necessary +for such a build can be done through a few modifications to the +template build.properties provided +by PDE build. The following section focuses on setting up a simple +build assuming that all plug-ins +and features (both to-build and pre-built) referenced from the feature +being built are already +locally available on disk. +
+Basic Setup
+The Build Configuration Directory
+The first step in setting up a build is to create the build configuration directory. This is the directory in which the files that control and customize the headless build are kept.
+The main file for controlling the build is the top level build configuration build.properties file. When setting up a new build, copy the template file from the org.eclipse.pde.build bundle in your eclipse install that you will be using to run your build. The template file is located under org.eclipse.pde.build/templates/headless-build/build.properties.
+This directory is refered to by the builder properties which is normally set on the ant command line.
+The buildDirectory
+The buildDirectory property specifies the directory in which PDE/Build will generate scripts and perform the actual build. Plug-ins and features that are being built should placed in ${buildDirectory}/plugins and ${buildDirectory}/features sub-directories. + If bundles and features are being fetch from a repository (See Fetching From Repositories), then they will be placed here as well.
+This directory may be the same as the build configuration directory, or it may be a different directory. It may be desirable to use a separate directory, especially if the build configuration is kept in CVS and you don't want to pollute it with generated build artifacts.
+Initial Properties
+To set up a basic feature build, you need to edit the build configuration build.properties file and set the following properties:
+-
+
- topLevelElementId: Set to the id of the feature you wish to build. +
- baseLocation: the location of an eclipse install containing pre-built features and plug-ins in features/ and plugins/ subdirectories. These are the binaries against which you will be compiling. If you have no pre-requisite binaries and are building everything from scratch, this property can be left un-set. +
- buildDirectory: the directory the build will take place in. +
- configs: list the configurations for which you want your feature to be built. You can uncomment the configuration(s) provided (be careful of the line continuations). If the feature you are building is platform independent, this property does not need to be set or can be set to *,*,*. +
- archivePrefix: the name of the directory in which your feature will be unzipped on disk. +
Previous version of PDE/Build also required an allElements.xml file, this is no longer necessary in 3.4. The allElements.xml can still be used, but is only required if you wish to customize certain aspects of your build. See Customizing a Headless Build.
+ +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/build.xml>: This is the path to the build.xml provided by pde build. It is located in the org.eclipse.pde.build/scripts directory. This is the build script that drives the whole 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 -buildfile
+<<eclipseInstall>/plugins/org.eclipse.pde.build_<version>/scripts/build.xml>
+-Dbuilder=<path to the build configuration folder>+
Once the build is complete, you can get the result in the build directory in the folder named I.TestBuild (this name can be configured by setting the buildLabel property).
+Advanced scenarios
+If you require more customization of the build, ie fetching from a repository, see the Advanced PDE Build topics for more information.
+ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_feature_generating_ant.htm b/org.eclipse.pde.doc.user/tasks/pde_feature_generating_ant.htm new file mode 100644 index 0000000000..3db03ff2c4 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_feature_generating_ant.htm @@ -0,0 +1,116 @@ + + + + + + + +Generating Ant scripts
+ +Ant is a simple open-source scripting engine that is capable of running +scripts written in XML format. Ant is ideal for executing tasks usually found in +automated builds.
+ +The variables set in the plug-in, fragment or feature build.properties + will be used to generate scripts for +Ant. PDE generates Ant scripts for creating +individual plug-in and fragment build files and one overall script for building +the feature JAR. This "main" script is also responsible for running individual +script files in the right order (defined by the plug-in dependency chain). Each +build file has the same name (build.xml) and is created as a sibling of the manifest +files in the corresponding projects.
+ +Since Ant scripts use the replacement variables in build.properties, you can typically use them "as is", without +modifying the generated scripts. If you do modify them, you must not recreate the +scripts every time you want to rebuild the component.
+ +To create scripts, you can simply select Create Ant Build File while a +suitable manifest file (plugin.xml, fragment.xml or feature.xml) is selected in +the Navigator or Package Explorer views. The command will generate +the build script. After selecting Run Ant... from the pop-up menu while +the newly generated script file is selected, the following wizard will open:
+ +
+
The standard Ant wizard allows customization in two ways: by +providing the execution arguments and by selecting one or more build targets.
+ +Properties
+Ant arguments are typically used to provide property values that +override default values and control the build process. Arguments are set using +"-Dproperty=value". The following properties are recognized:
+ +-
+
-
+
bootclasspath - if set, it replaces the default boot + classpath. Used when compiling cross-platform plug-ins (e.g. building a UI + plug-in for Windows using Linux)
+ - build.result.folder - where + the temporary files for the update JAR creation should be placed. + These files are usually the plug-in library JARs. +
- plugin.destination - where + plug-in and fragment update JARs should be put. These JARs represent + entire plug-ins and fragments in a format suitable for publishing on an + Install/Update server and referencing by a feature. The typical layout of an + Update site is to have all the plug-in and fragment JARs in one place and + all the features in another. This argument is useful for placing plug-ins and + fragment directly into the desired directory (or the staging place on the + local machine before pushing the features onto the remote server). +
- feature.destination - where + feature update JARs should be put. +
To adapt the behavior of the compiler, the following properties are recognized:
+-
+
- javacFailOnError - stop the build when an error occurs when set to true. Default is false. +
- javacDebugInfo - compile source with debug information when set to true. Default is true. +
- javacVerbose - produce verbose output when set to true. Default is true. +
- javacSource - value of the -source command-line switch. +
- javacTarget - generate class files for specific VM version. +
- compilerArg - additional command line arguments for the compiler. +
Targets
+ +When executing feature build scripts, the +following targets are used to call individual targets of plug-ins or fragments. +In order to specify what target to execute, the property target should be +set (e.g. -Dtarget=refresh). One of the all.* targets serves as an iterator, whereas +the actual target to execute is specified via the property target.
+-
+
- all.plugins - for all listed plug-ins +
- all.fragments - for all listed fragments +
- all.children - for all listed plug-ins and fragments +
- build.jars - build JARs for all feature children; +
- build.sources - build source for all feature children; +
- build.update.jar - generate a feature JAR in the format used by the install/update mechanism. + The above mentioned property feature.destination can be used to define + where to put the JAR; +
- zip.distribution - creates a zip +file with the feature and its plug-ins and fragments in an SDK-like structure +but does not include source code; +
- zip.sources - creates a zip file with the feature and its plug-ins and fragments in an SDK-like structure which only includes the source; +
- clean - delete everything produced by running any of the target; +
- refresh - performs a "Refresh" action in the current project, thus making the +newly generated resources visible in the Navigator or Package Explorer. +
- zip.plugin - creates a zip file with the binary and source contents of a plug-in with the following structure:
+
+ id_version/
where 'id' is the plug-in unique identifier +and 'version' is the plug-in version. This zip file can be directly unzipped +into the Eclipse installation directory as a form of a quick manual deployment.
+ contents +
+
Generating Ant scripts from the command line
+Ant scripts are typically generated using the Plug-in Development
+Environment (PDE), but it is also possible to generate
+them by hand or from other scripts.
+Indeed PDE exposes Ant tasks to generate the various build scripts.
+Build script generation facilities
+reside in the following tasks. Arguments are also listed for each
+task.
+
-
+
- eclipse.fetch: generates an Ant script that fetches
+content from a CVS repository. The eclipse fetch is driven by a file
+whose format is described below (see Directory
+file format).
+
+ +
++ +elements: +
+the entry that will be +fetched. The format +expected is of the form type@id[,version] as specified in the directory file +format; ++ +buildDirectory: +
+the directory into which +fetch scripts will be generated and into which features and plug-in projects will be +checked out; ++ +directory: +
+the path to a directory file; ++ +children: +
+optional, specifies whether +the script generation for contained plug-ins and fragments should be invoked. +Default is set to true; ++ +cvspassfile: +
+optional, the name of a CVS +password file; ++ +fetchTag: +
+optional, overrides the tag +provided in +directory file by the given value; ++ +configInfo: +
+optional, an ampersand +separated list of +configuration indicating the targeted configuration. The default is set +to be platform independent; ++ + +recursiveGeneration: +
+optional, specify whether or +not fetch scripts should be generated for nested features. The default is +set to true. +
+
+
-
+
- eclipse.buildScript: generates a build.xml file for the
+given elements as well as additional scripts used by the pde build infrastructure.
+
+ +
++ +elements : +
+the entry to be built. +Entry is expected to be of the form type@id[,version] as specified in the +directory file format; ++ +buildDirectory : +
+the directory where the +features and plug-ins to build are located. Plug-ins and features must +respectively be located in plugins and features folders; ++ +children : +
+optional, specifies whether +the script generation for contained plug-ins and fragments should be invoked. +Default is set to true; ++ +recursiveGeneration : +
+optional, specified whether +the +script generation for contained features should be invoked. Default is +set to true; ++ +devEntries : +
+optional, a comma separated +list of +directories to be given to the compile classpath; ++ +buildingOSGi : +
+optional, indicates if the +target is 3.x. +or 2.1. Default is true; +
++ +baseLocation : +
+optional, indicates a folder +which +containing a target eclipse install with features/ and plugins/ +subdirectories; ++ +configInfo : +
+optional, an ampersand +separated list of +configuration indicates the targeted configuration. The default is set +to be platform independent; ++ +pluginPath : +
+optional, a platform file +separator separated list of locations from which to find additional +plug-ins; ++ +archivesFormat : +
+optional, an ampersand +separated list of +configs and the expected output format for each of those. The format is +separated by a dash (-) from the configuration. The values supported +are: folder, tar, zip, antZip, respectively meaning don't archive, use +tar to create the archive, use the version of info zip available on the +platform, use ant zip . The default value is antZip; ++ +product : +
+optional, '/' separated path +to the location of +an RCP product being built. The first segment of the path must refer to +the plug-in id of a plug-in containing the .product file; ++ +signJars : +
+optional, indicates if the +scripts generated +must sign jars for features and plug-ins. The default value is false. +The parameters to the sign task are controlled by the following ant +properties: sign.alias, sign.keystore and sign.storepass respectively +being passed to the alias, keystore and storepass parameters from the +ant signJar +task. The default value is false; ++ +generateJnlp : +
+optional, indicates if a +jnlp file should +be generated for all the features being built; ++ + +outputUpdateJars : +
+optional, generates plug-ins +and +features in the update site format when set. The default value is +false. Note that the site.xml is not generated nor updated; ++ +groupConfiguration +: +
+optional, whether or not to +group all configurations being built into a single archive; +
++ + +generateVersionsLists : +
+optional, whether or not to +generate properties files listing the versions of features and plug-ins +that were built; +
++ + +filteredDependencyCheck : +
+optional, constrain the set of plug-ins and features + to be considered during the build to those reachable from the features; +
++ + +filterP2Base : +
+optional, constrain the set of plug-ins and features + to be considered from the baseLocation to those considered to be installed by p2; +
++ +generateFeatureVersionSuffix: + +optional, whether or not to +generate the feature version suffix. See also Version Qualifiers; ++ + +generatedVersionLength : +
+optional, the length of the generated feature version suffix. By default it is set to 28. See also Version Qualifiers; +
++ + +significantVersionDigits : +
+optional, the number of significant digits used when generating feature version suffixes. + See also Version Qualifiers; +
++ + + +forceContextQualifier : +
+optional, uses the given +value to replace the .qualifier being by plug-ins and features. See also Version Qualifiers; +
+
+
-
+
- eclipse.generateFeature:
+generates a feature that will contain the provided elements. This
+task is used to build an RCP
+application from a product configuration file.
++ +
++ +featureId : +
+The id to give to the +generated Feature. +
++ +buildDirectory: +
+the directory where the +features and plug-ins (in /features and /plugins subdirectories) to +include are located. The generated feature will be placed in the +/features subdirectory. +
++ +baseLocation : +
+optional, indicates a folder +which contains installed features and plug-ins +
++ +productFile : +
+optional, a product file on +which to base the generated feature. +
++ +verify : +
+Whether or not to use the +resolver to verify that the provided plug-ins and features are +available. This also determines whether or not the the feature +will be able to correctly handle platform specific fragments and +plug-ins that will be JARed. If all the elements to be included +in the feature are available locally, then verify should be set to +True. If the elements need to be fetched from a repository, set +verify to False, use the resulting feature to fetch the required +plug-ins and features, then regenerate the container feature using +verify = True. +
++ +pluginPath : +
+optional, a platform file +separator separated list of locations from which to find additional +plug-ins ++ +configInfo : +
+optional, an ampersand +separated list of +configuration indicates the targeted configuration. The default is set +to be platform independent; ++ +pluginList : +
+optional, a comma separated +list of plug-in ids to include in the generated feature. (Supports attributes, see below) +
++ +featureList : +
+optional, a comma separated +list of feature ids to include in the generated feature. (Supports attributes, see below) +
++ +fragmentList : +
+optional, a comma separated +list of fragment ids to include in the generated feature. (Supports attributes, see below) +
++ +buildPropertiesFile : +
+optional, the location of a properties file whose contents should be used as the generated feature's build.properties. +
++ + +includeLaunchers : +
+optional, whether or not to include the equinox launchers, default value is "true". +
+
+The pluginList, featureList, and fragmentList arguments of the eclipse.generateFeature task all support attributes. These arguments all take the form:
+List = <element-id>[;<attribute>=<value>]* [,<element-id>[;<attribute>=<value>]*]*
+Each attribute=value pair will be inserted into the generated xml corresponding to the given element. Example:
++ featureList = org.eclipse.feature;optional=true + pluginList = org.eclipse.plugin.A;unpack=true + fragmentList=org.eclipse.fragment.a;os=win32,org.eclipse.fragment.b;os=linux;ws=gtk;arch=x86 + + <feature ...> + ... + <includes id="org.eclipse.feature" version="0.0.0" optional="true" /> + ... + <plugin id="org.eclipse.plugin.A" version="0.0.0" unpack="true" /> + <plugin id="org.eclipse.fragment.a" version="0.0.0" os="win32" fragment="true" /> + <plugin id="org.eclipse.fragment.b" version="0.0.0" os="linux" ws="gtk" arch="x86" fragment="true" /> + ... + </feature> +
+
+
Examples
+<eclipse.fetch elements="bundle@org.eclipse.osgi"+
buildDirectory="c:\toBuild"
directory="directory.txt"
configInfo="win32,win32,x86 & linux, motif, x86"
/>
<eclipse.buildScript elements="bundle@org.eclipse.osgi"
buildDirectory="c:\toBuild"
archivesFormat="macosx, carbon, ppc - tar"/>
Directory file format
+Directory files are used to indicate where the plug-ins and features +can be obtained, as well as their versions. It is a Java property file whose keys are always of the form +type@id[,version] but where the value is open ended. When using +map files to fetch your elements, the directory file is a concatenation +of all the map files, for more details on map files see Fetching From +Repositories. + +Using the targets
+The tasks previously described only work if Eclipse is running. In +the particular scenario of executing Ant scripts using Eclipse +tasks,the scripts must be run using the Eclipse Ant Runner application. +The command line for this particular +case is the following: +
+java -jar plugins/org.eclipse.equinox.launcher_<version>.jar -application org.eclipse.ant.core.antRunner -buildfile build.xml+
Note that the parameters appearing after the application are the +parameters that are passed to Ant. +
+ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_fetch_phase.htm b/org.eclipse.pde.doc.user/tasks/pde_fetch_phase.htm new file mode 100644 index 0000000000..42f385725f --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_fetch_phase.htm @@ -0,0 +1,192 @@ + + + + + + + +Fetching from Repositories
++The infrastructure offered by PDE Build provides steps to fetch the +source code and pre-built plug-ins from a repository as part of the build process (see the eclipse.fetch task +and the properties to control fetching). +Two possibilities are available: let PDE build automatically fetch the +source, or fetch the source code manually.
+ +First step to automation, the map file
++Given the identifier of a feature or a plug-in that needs to be built, the build +infrastructure is able to fetch from a repository all the included features and +plug-ins.
++In order to know where to get things from, PDE uses map files. A map +file is a java property file which maps feature and plug-in ids to a +location and a tag in a repository. The format of map files is open and but +the key part is fixed by PDE Build:
+<elementType>@<elementID>[,<elementVersion>] = <repo specific content>+
where elementType is one of bundle, feature, +plugin or fragment, and elementId and elementVersion give the specifics of the element.
+ +Map file entry for CVS
+The format of a map file entry to fetch content from CVS is the following: +<key> = CVS, [,args]+
-
+
- tag, the CVS tag to check out; +
- cvsRoot, a CVS connection string; +
- path, an optional CVS module and path where to get the folder containing the element. By default the element name is used as module name; +
- prebuilt, an optional boolean indicating if the element downloaded is prebuilt. By default this is false; +
- cvsPassFile, an option path to a cvs pass file; +
- password, an optional password to use to connect to CVS; +
plugin@com.ibm.icu,3.6.1=CVS,tag=v200704191630,cvsRoot=:pserver:anonymous@dev.eclipse.org:/cvsroot/tools,path=org.eclipse.orbit/com.ibm.icu/bin,prebuilt=true+
+
| Old style Map Entries |
|
+In Eclipse 3.2 and earlier, the map file format for CVS was:
+
+
+If any of the optional arguments aren't specified, then the commas are still required to delimit any following arguments. This format should be considered deprecated and the key/value format is prefered.
+<elementType>@<elementID> = CVS, <TAG>, <CVSROOT>[,<PASSWORD>[,<PATH>[,<CVSPASSFILE>]]]+ |
+
Map file entry for Ant GET
++The format of a map file entry to fetch content from any URL supported by Ant GET is the following:
+<key> = GET, <url> [,args]+
-
+
- unpack, set to true the indicate that the downloaded element should be unzipped; +
- verbose, set to true to show verbose progress information when downloading. The default value is false; +
- ignoreerrors, set to true to log errors during the transport. The default value is false; +
- usetimestamp, conditionally download a file based on the timestamp of the local copy (for http URLs only) when set to true. The default value is false; +
- username, the username for "BASIC" http authentication; +
- password, the password to perform the download. +
plugin@com.ibm.icu,3.4.5=GET,https://download.eclipse.org/tools/orbit/downloads/drops/S200705301823/bundles/com.ibm.icu_3.4.5.jar, unpack=true+
Map file entry for a p2 fetch
+A new extension has been added to PDE/Build that enables users to fetch artifacts from p2 repositories. You can now add an +entry to your map file for build input and PDE/Build will retrieve the artifact and include it in the build. The map file entry needs to include the +id and version of the installable unit (IU), and the URI of the repository where the IU can be found. The metadata and artifact repositories are +assumed to be co-located. +
++The format of a map file entry to fetch content via p2 is as follows: +
+<elementType>@<elementID> = p2IU, id=<id>, version=<version>, repository=<repository>+
-
+
- id, the identifier of the Installable Unit; +
- version, the version of the Installable (optional). If not specified, the highest version available will be fetched. +
- repository, the location (URI) of the repository where the IU will be found. +
In the Helios release, features can be fetched with p2 by specifying the Installable Unit representing the feature jar. See the feature metadata page +for details on the structure of p2 metadata for features.
+ +Examples: ++plugin@my.bundle.id,1.0.0=p2IU,id=my.bundle.id,version=1.0.0,repository=http://example.eclipse.org/repo +feature@my.feature.id = p2IU,id=my.feature.id.feature.jar, version=1.0.0,repository=http://example.eclipse.org/repo ++
Map file entry for other repositories
+PDE Build provides an extension point +where fetch script generators for different repositories can be plugged in. When your eclipse +install contains a bundle that provides a script generator extension +for a different type of repository, you can use that repository by +specifying it in your map file entries and adhering to the format specified by the extension provider.
+ +Setting up for CVS source fetching
+To set up fetching your source from CVS, you should do the following:+
-
+
- Make sure you have a cvs.exe on your system search path.
+(Download CVS from here).
+
+ - Create a folder called maps in the build directory. +
- Create a file with extension .map in the maps folder. +
- Fill in this map file with all the elements that need to be +fetched from a repository. +
- Edit the build.properties file from the configuration folder and +comment out the line skipFetch=true. If that property +is set, then PDE build will skip the entire fetch phase. If you +want the tag specified in the map files to be ignored you can set the +property fetchTag to a specific value. This is useful when +doing a nightly build from HEAD instead of from the tagged versions. +
Getting the map files from CVS
+Map files are usually stored in a repository. PDE Build offers default +infrastructure to get those map files from a CVS repository. +To enable this function change the following properties in your +configuration's build.properties from your configuration directory: +-
+
- skipMaps: Comment
+out this property. If this property is set, then PDE build will
+not fetch the map files.
+
+ - mapsRepo =
+:pserver:anonymous@example.com/path/to/repo. The CVS repository
+from which to get the map files.
+
+ - mapsRoot =
+/path/to/maps. The path in the CVS repository to the directory
+containing the map files.
+
+ - mapsCheckoutTag = +HEAD. The CVS tag to use to checkout the map files. +
Automatic fetching from other repositories
+If you are automatically fetching your map files from the +repository, you will need to copy the customTarget.xml file from +org.eclipse.pde.build/templates/headless-build into your configuration +directory. The target getMapFiles is used to fetch the map +files, this should be modified to fetch from your repository.
+Getting source code manually
+You can write custom fetch targets to retrieve your plug-ins and +features which can be invoked from +the preSetup or postSetup targets in the customTargets.xml file. +Features and plug-ins should +be fetched to +${buildDirectory}/features +and +${buildDirectory}/plugins +respectively. ++
+ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_individual_source.htm b/org.eclipse.pde.doc.user/tasks/pde_individual_source.htm new file mode 100644 index 0000000000..44843b209d --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_individual_source.htm @@ -0,0 +1,116 @@ + + + + + + + +
Individual Source Bundles
+The traditional format of source bundles in Eclipse was a folder containing src.zip's for all the plug-ins included in a given feature. Starting in 3.4, Eclipse now ships with individual source bundles. For each bundle there is a corresponding source bundle which is a jar containing the source for that bundle. This allows for more flexible delivery of source, and it also alleviates some path length issues that may be experienced on some platforms. + +Eclipse-SourceBundle
+A source bundle is identified by the presence of the Eclipse-SourceBundle header in its manifest. The format of this header is:
+Eclipse-SourceBundle: <bundle-id>;version=<version>;roots:="root1, root2"+
The bundle-id and version indicate the bundle that the included source code corresponds to. The roots directive indicates the folders within the source bundle that actually contain source code. If no roots directive is specified, then a value of "." is assumed.
+Class file libraries are mapped to source locations in a predictable manner. The root of the plug-in maps to the root of the source bundle. This is the main case for most jarred plug-ins. If the plug-in contains additional libraries "foo/lib.jar", the source is expected to be in corresponding "foo/libsrc/" folders in the source bundles.
+-
+
- Example 1 : The org.eclipse.pde.core bundle has class files in the root of the jar, plus a nested jar "ant_tasks/pde-ant.jar". Therefore, the source bundle should have java files in the root and java files in a "ant_tasks/pde-antsrc" folder.
+The roots directive lists both the root of the source bundle "." and the "ant_tasks/pde-antsrc" folder.
+
+org.eclipse.pde.core.jar org.eclipse.pde.core.source.jar + - org/**/*.class - org/**/*.java + - ant_tasks/pde-ant.jar - ant_tasks/pde-antsrc/org/**/*.java +
+
+Eclipse-SourceBundle: org.eclipse.pde.core;version="3.4.0.N20071128-0010";roots:="ant_tasks/pde-antsrc,." +
+ - Example 2 : The org.eclipse.pde.build bundle is a folder on disk. It contains a pdebuild.jar and a lib/pdebuild-ant.jar. The source bundle will be a jar that contains a "pdebuildsrc" folder and a "lib/pdebuild-antsrc" folder.
+
+org.eclipse.pde.build/ org.eclipse.pde.build.source.jar + - pdebuild.jar - pdebuildsrc/org/**/*.java + - lib/pdebuild-ant.jar - lib/pdebuild-antsrc/org/**/*.java +
+
+Eclipse-SourceBundle: org.eclipse.pde.build;version="3.4.0.N20071128-0010";roots:="pdebuildsrc,lib/pdebuild-antsrc" +
+
Generating Individual Source Bundles
+PDE/Build can automatically generate individual source bundles, but only in a headless build. Individual soure bundle geneation can be turned on by specifying:
+individualSourceBundles=true+
This must be specified in the build configuration's top level build.properties file and it controls all source generation for that build. See Generating Source Features and Plug-ins for details on generating traditional source plug-ins and features, the remainder of this page assumes familiarity with traditional source generation.
+ +generate.feature
+In a feature's build.properties file, the generate.feature property tells pde.build to generate a source feature. +generate.feature@<source feature id> = <feature id> [, feature@<feature id>]* [, plugin@<plugin id>]* [, exclude@<plugin id>]*+
When generating individual source bundles, this property remains as before and supports the same attributes (eg version, unpack, optional, etc), the difference will be noticed in the resulting source feature. Before, the source feature would have included 1 source plug-in + a source fragment for each platform being built. In the new format, the source feature will include a source bundle for each plug-in/fragment listed in the original feature.
+Plug-ins that were included in the source feature via the plugin@ syntax will not get corresponding source bundles. This is useful for adding doc plug-ins to the source feature.
+The exclude@ entry is new for individual source generation. Some plug-ins that were included in the originating feature (ie doc plug-ins or fragments that contain only native code) may not have source and should be excluded from the generated source feature. The exclude@ entry supports a version attribute.
+Example: +generate.feature@org.eclipse.jdt.source=org.eclipse.jdt, plugin@org.eclipse.jdt.doc.isv;unpack="false",exclude@org.eclipse.jdt.doc.user+ +
generate.plugin
+In the old format, the generate.plugin property generates a source plug-in based on the contents of a given feature. When generating individual source bundles, this changes to be based on a given plug-in:
+generate.plugin@<source plug-in id>=<plug-in id>+
The generate.plugin property was used by features to include source without having a source feature (even though behind the scenes an entire source feature was generated). When generating individual source bundle, features will need to include a *.source bundle for each plug-in along with a corresponding generate.plugin property for each one.
+Example: The sdk.examples feature used to look like this:
++ <feature id="org.eclipse.sdk.examples" ... > + .... + <plugin id="org.eclipse.sdk.examples.source" version="0.0.0"/> + <plugin id="org.eclipse.sdk.examples.source.win32.win32.x86" version="0.0.0"/> + </feature> ++
generate.plugin@org.eclipse.sdk.examples.source=org.eclipse.sdk.examples +
This changes to:
++ <feature id="org.eclipse.sdk.examples" ...> + ... + <plugin id="org.eclipse.compare.examples.source" version="0.0.0"/> + <plugin id="org.eclipse.debug.examples.core.source" version="0.0.0"/> + <plugin id="org.eclipse.swt.examples.source" version="0.0.0"/> + </feature> ++ +
+ generate.plugin@org.eclipse.compare.examples.source=org.eclipse.compare.examples + generate.plugin@org.eclipse.debug.examples.core.source=org.eclipse.debug.examples.core + generate.plugin@org.eclipse.swt.examples.source=org.eclipse.swt.examples +
generateSourceBundle
+Specific plug-ins may not require source bundles because they don't actually contain source. This may occur with platform specific fragments that only contain a native library. In this case, the bundles may be excluded by the feature as outlined above in generate.feature.
+Or, bundles can explicitly specify in their own build.properties file that no source bundle should be generated for them:
+generateSourceBundle=false+ +
Custom Content
+Custom content can always be added to generated source bundles using the post.gather.source custom callback in the originating bundle. (See Feature and Plug-in custom build steps).
+When doing this, set the property "src.additionalRoots" in the plugin's build.properties file so that the generate source bundle has the correct roots directive on the Eclipse-SourceBundle header.
+Example:
+
+org.junit4 :
+ build.properties
+ src.includes = about.html,junitsrc.zip
+ src.additionalRoots=junitsrc
+ customBuildCallbacks=customBuildCallbacks.xml
+
+ customBuildCallbacks.xml
+ <target name="post.gather.sources" >
+ <mkdir dir="${target.folder}/junitsrc"/>
+ <unzip src="${target.folder}/junitsrc.zip" dest="${target.folder}/junitsrc" overwrite="false"/>
+ <delete file="${destination.temp.folder}/junitsrc.zip" />
+ </target>
+
+
+Branding the Source Feature
+Previously, the generated source plug-in served as a branding plug-in for the generated source feature. Branding files (about.properties, eclipse32.gif, etc) were provided using the sourceTemplatePlugin directory in the original feature.
+When generating individual source bundles, the branding plug-in for the source feature will be the source bundle corresponding to the original branding plug-in. This means that branding files for the source feature's branding plug-in can be contributed using the src.includes property in the original branding plug-in.
+The sourceTemplatePlugin folder of the feature for which we are generating source also contributes files to the branding plug-in.
+ +sourceTemplatePlugin vs sourceTemplateBundle
+Previously, the contents of the sourceTemplatePlugin directory of the original feature was copied into the source plug-in. When generating individual source bundles, this remains true only for the branding source bundle (see above).
+For all the other source bundles, the contents of a sourceTemplateBundle directory will be copied over.
+ + + diff --git a/org.eclipse.pde.doc.user/tasks/pde_p2_builds.htm b/org.eclipse.pde.doc.user/tasks/pde_p2_builds.htm new file mode 100644 index 0000000000..29f48963af --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_p2_builds.htm @@ -0,0 +1,46 @@ + + + + + + + +Building p2 Repositories and Products
+PDE/Build has built in support for publishing p2 metadata using the new p2 Publisher. 3.4-style integration with the old metadata generator still works, but does not support newer features like the customization of metadata. +
+The new publisher integration gathers your features and bundles from source and publishes them directly to a p2 repository. To use the new functionality, the builder should define the property:
++
Setting this property will change the build in significant manner:
+-
+
- Feature builds produce a single p2 repository that is a group of all the configurations being built. +
- Product builds produce a properly installed fully enabled p2 product. (And optionally the corresponding repository.) +
See the separate feature and product build help pages for more detail on those types of builds.
+ + +Overview of the changes
+The build's local repository
+During the build, all metadata and artifacts will be published into a build repository defined by the property p2.build.repo. This property should specify a URI, the default value for this is file:${buildDirectory}/buildRepo.
+Once all the metadata and artifacts are published into this repository, the final assemble and packaging scripts will mirror and/or install from this repository into the locations that will become the archives produced by the build. This final +mirroring and installation can be skipped using skipMirroring and skipDirector properties, in which case the build results would all just be in the build repository.
+ +Generated build.xml : gathering vs publishing
+In the generated build.xml for features and plugins there is a target gather.bin.parts which was responsible for gathering the contents of the feature/plug-in and copying them to a final directory to be jared (or not) and included in the build results. +When using p2.gathering=true, we instead publish the feature/plug-in directly into a p2 repository. That is, we are using p2 to gather the binary artifacts directly from the source (this is where the name of the property comes from).
+This is done using a new target named publish.bin.parts which uses a new ant tasks contributed by PDE/Build. In old style builds, calling gather.bin.parts was done by delegating through the feature structure. Calling publish.bin.parts is instead +done directly from a new assemble p2 script that is generated.
+Rootfiles contributed by features
+Old style integrations grouped all the rootfiles contributed by all the features in the build into a single root file installable unit and artifact (which may have been named for a product). With the new publishing support, root files are instead +associated with the feature that contributed them. See the feature metadata layout page for more details.
+The assemble scripts
+Old style integration was done by calling the metadata generator on the binary results during the assembly and packaging process. When using p2.gathering=true there is a new assemble.<feature>.p2.xml script.
+This script will invoke the publish.bin.parts for all features and bundles being built. It will also publish metadata for all pre-existing binary features and plug-ins, as well as publishing metadata for products.
+At the end of the p2 assemble script, before the remaining assemble and package scripts are called, we have a complete repository with the full results of the build. The remaining assemble and package scripts are simply +slicing up the repository and/or performing installs using the p2 director to create the final archives which are the results of the build.
+ + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/pde_p2_buildtasks.htm b/org.eclipse.pde.doc.user/tasks/pde_p2_buildtasks.htm new file mode 100644 index 0000000000..4c0a4f9a18 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_p2_buildtasks.htm @@ -0,0 +1,507 @@ + + + + + + + ++ PDE Build Extensions to the p2 Publisher +
++ PDE Build contributes several ant tasks that extend the + p2 + publisher. These tasks allow PDE Build to publish + metadata and artifacts directly into a p2 repository. +
++ + The generated build scripts use these tasks in the context of + a full build where things like compiling class files and + replacing versions are done. However, some of the tasks may + be usefull in special cases to publish metadata directly + without running a full build. +
+
+ + eclipse.publish.featuresAndBundles ++ |
+ ||||||||||||||||
|
+ + This task is very similar to the + p2.publish.featuresAndBundles task contributed + by the p2 publisher. This task will publish metadata + for pre-existing binary features and plug-ins which are + not being built from source. The task will also publish + categories based on a provided site.xml or category.xml + file. + + |
+ ||||||||||||||||
|
+ + This task supports the following attributes: + +
|
+
+ <eclipse.publish.featuresAndBundles repository="file:C:/build/repository" category="file:C:/build/category.xml" > + <features dir="C:\eclipse\features\" includes="org.eclipse.cvs_1.1.100.v20090514-7E79FEc9BJ99r9XGQ3CICF" /> + <bundles dir="C:\eclipse\plugins" includes="org.eclipse.cvs_1.0.300.v20090520.jar" /> + <bundles dir="C:\eclipse\plugins" includes="org.eclipse.team.cvs.core_3.3.200.I20090430-0408.jar" /> + <bundles dir="C:\eclipse\plugins" includes="org.eclipse.team.cvs.ssh_3.2.100.I20090508-2000.jar" /> + + <bundles dir="C:\eclipse\plugins" includes="org.eclipse.team.cvs.ssh2_3.2.200.I20090508-2000.jar" /> + <bundles dir="C:\eclipse\plugins" includes="org.eclipse.team.cvs.ui_3.3.200.I20090521-1750.jar" /> + </eclipse.publish.featuresAndBundles> ++
+
+
+ + eclipse.gatherBundle ++ |
+ ||||||||||||||||
|
+ + Publish a plug-in directly from source. Once the .class + files for a bundle are compiled, this task will gather + up all the files that make up the binary result and + publish them as a p2 artifact with metadata. This task + is used in the publish.bin.parts task in the + plug-in's generated build.xml, this task replaces the + gather.bin.parts task when you are building + with the p2 publisher. + + + |
+ ||||||||||||||||
|
+ + This task supports the following attributes: + +
|
+
+ <eclipse.gatherBundle metadataRepository="file:/build/repo" artifactRepository="file:/build/repo"
+ buildResultFolder="${basedir}" baseDirectory="${basedir}" unpack="true" >
+ <outputFolder library="lib/pdebuild-ant.jar" dir="${basedir}" includes="bin_ant/**" />
+
+ <outputFolder library="pdebuild.jar" dir="${basedir}" includes="bin/**" />
+ </eclipse.gatherBundle>
+
+ +
+ + + eclipse.gatherFeature ++ |
+ ||||||||||
|
+ + Publish a feature directly from source. This task will + gather up all the files that make up the feature jar + and publish them as a p2 artifact with metadata. This + task will also publish artifacts containing any + root files that are + contributed by this feature. If the feature does not + specify a bin.includes property, then the + feature jar will not be generated, but there will still + be root file artifacts and feature group metadata. + + + |
+ ||||||||||
|
+ + This task supports the following attributes: + +
|
+
+ <eclipse.gatherFeature
+ metadataRepository="file:/build/repo"
+ artifactRepository="file:/build/repo"
+ buildResultFolder="${basedir}"
+ baseDirectory="${basedir}"
+ />
+
+
+ +
+ + eclipse.brand.p2.artifacts ++ |
+
+ ||||||||||||||||||
|
+ + Brand launcher artifacts for a product and republish + them with a new name for inclusion in the given + product. + + |
+ ||||||||||||||||||
|
+ + This task supports the following attributes: + +
|
+
Configuring p2 Products
+By default, PDE/Build will automatically generate start levels and other configuration information for you. It does this by generating properties into the p2.inf file. +If your product provides its own p2.inf file, then PDE/Build will append to a copy of that file. It is possible to suppress this behaviour by defining some properties in your p2.inf:
+| org.eclipse.pde.build.append | Set to false to disable appending any defaults to the p2.inf file. |
| org.eclipse.pde.build.append.startlevels | Set to false to disable appending start level information to the p2.inf file. |
| org.eclipse.pde.build.append.launchers | Set to false to disable including launchers in the p2.inf file. |
Start Levels
+Start level information can be set manually on the configuration tab of the product editor. If any start level information is set in the .product file, then PDE/Build will not generate any defaults. +This means that if you decide to set any custom start levels, then you must set start levels for all bundles that will require them. The default start levels generated by PDE/Build for p2 products are:
+| Bundle | Start Level | Auto-Start |
| org.eclipse.equinox.simpleconfigurator | 1 | true |
| org.eclipse.equinox.common | 2 | true |
| org.eclipse.update.configurator | 4 (default) | true |
| org.eclipse.core.runtime | 4 (default) | true |
| org.eclipse.equinox.ds | 2 | true |
When setting the start level for org.eclipse.update.configurator, PDE/Build will also automatically set In addition to these properties, org.eclipse.update.reconcile=false.
+Config.ini properties
+The p2 product publisher used by PDE/Build will automatically set a number of config.ini properties based on settings in your .product file:
+| Property | Based On |
| eclipse.product | The product set on the overview tab of the product editor. |
| eclipse.application | The application set on the overview tab of the product editor. |
| osgi.splashPath | The plug-in set on the Splash tab of the product editor. |
It is also possibly to add arbitrary config.ini properties to your .product file, however there is no tab the editor for this, so it must be done manually by editing the .product file as xml.
+An example of setting properties this way would look like this:
++ ... + <configurations> + <-- The product editor will generate start level information like this: + <plugin id="org.eclipse.core.runtime" autoStart="true" startLevel="4" /> + --> + <property name="osgi.bundles.defaultStartLevel" value="4" /> + <property name="osgi.requiredJavaVersion" value="1.5.0"/> + </configurations> + ... ++
Launchers
+PDE/Build will automatically brand launchers (which it gets from the org.eclipse.equinox.executable feature). These launchers will be automatically included in the +product along with generated metadata that will set the appropriate -startup and --launcher.library arguments in the product ini file.
+Because of changes to the structure of feature metadata with respect to root files, the org.eclipse.equinox.executable feature should not be included directly in your product.
+ + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/pde_p2_featurebuilds.htm b/org.eclipse.pde.doc.user/tasks/pde_p2_featurebuilds.htm new file mode 100644 index 0000000000..8b44bd0237 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_p2_featurebuilds.htm @@ -0,0 +1,41 @@ + + + + + + + +Feature Builds with p2
+Defining the new property:
+will cause a few changes for feature builds. See also the page for feature metadata layout.
+In particular, instead of producing per-platform archives, the build will produce a single p2 repository which is a group of all the platforms. Effectively this is forcing an implicit groupConfigurations=true.
+The following is a list of related properties (old and new):
+| p2.gathering | Set to true to turn on p2 publisher based builds. |
| p2.build.repo | A URI to the local build time p2 repository, default is file:${buildDirectory}/buildRepo. Results will be mirrored from here to the final archive location. |
| groupConfigurations | p2.gathering=true has the implicit effect of setting groupConfigurations=true. To control the output format of the archive use the group.group.group configuration. |
| generate.p2.metadata | This is property for the old metadata generator integration. It has no effect when p2.gathering=true. |
| p2.metadata.repo p2.artifact.repo |
+ These properties were associated with generate.p2.metadata and have no effect on feature builds when p2.gathering=true because the default behaviour in this case is to create a p2 repository. (However, these properties do affect product builds). | +
| p2.metadata.repo.name p2.artifact.repo.name | Optional, these properties will be used to name the final feature repository. |
| p2.compress | Set to true to compress the final feature repository xml into a jar. |
| p2.flavor | No effect for feature builds, but does affect product builds. |
| p2.publish.artifacts | No effect when p2.gathering=true (Old property) |
| p2.root.name p2.root.version | No effect when p2.gathering=true (Old property) |
| p2.context.repos | Define context repositories. See reusing metadata. |
| repoBaseLocation | A folder containing repositories to transform using <p2.repo2runnable>. See also reusing metadata. |
| transformedRepoLocation | The folder containing the output of <p2.repo2runnable>. See also reusing metadata. |
| p2.category.site | A URL to a site.xml file used to define categories. |
| p2.category.definition | A URL to a category.xml file used to define categories. |
| p2.category.prefix | Define a prefix to ensure unique ids for category IUs generated from site/category files that don't use unique names. |
| skipMirroring | Skip the mirroring step, no final archive is created. Build results are found in ${p2.build.repo}. |
Layout of Feature Metadata
+PDE Build has always used features as a kind of grouping mechanism specifying what exactly should be built. With p2, this idea of a feature as a group has been extended, resulting a more than a single installable unit (IU) being generated per feature.
+From build's perspective, a feature contributes three things: +-
+
- A grouping of nested features and plug-ins. +
- The (optional) feature jar itself that contains the feature.xml, license files, etc. +
- A mechanism to contribute root files to the install. +
When using the metadata generator introduced in 3.4, we end up with the following structure for feature "org.example.platform":
+| org.example.platform.feature.group | +This is the top level grouping IU for the feature, it will have requirements on all the features and plug-ins that were included and required by the feature.xml. It also includes a requirement on the + nested org.example.platform.feature.jar | +||
+
| |||
|---|---|---|---|
Notice this IU structure does not include anything for the root files contributed by the feature. Instead a build using the metadata generation placed all rootfiles together into a single IU and artifact.
+New in 3.5 is the p2 publisher. If we use PDE Build's eclipse.gatherFeature task to publish the feature from source, we instead get root file IUs corresponding to the feature that contributed them. In this case, we end up with metadata as follows:
+| org.example.platform.feature.group | The top level grouping IU for the feature | +||||
+
| |||||
|---|---|---|---|---|---|
The use of the new p2 publisher instead of the old metadata generator allows for much finer grain control over how root files are delivered for products.
+ + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/pde_p2_integration.htm b/org.eclipse.pde.doc.user/tasks/pde_p2_integration.htm new file mode 100644 index 0000000000..75b974ed70 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_p2_integration.htm @@ -0,0 +1,99 @@ + + + + + + + +PDE Build Integration with p2
+This page describes a deprecated old way of integrating with p2. See the "Building p2 Repositories and Products" page for the recommended methods to build with p2. +The properties described below work using a backward compability layer and do not support any new features that may be added to the p2 publisher.
+See the Generating p2 metadata page in the Platform Plugin-in Developer Guide for details on p2 metadata generation. Generating metadata by itself it not sufficient to create a p2-enabled product. To do this you must perform an actual p2 install from the generated metadata. See the p2 director documentation for details on how to perform this install from a headless script.
+It is possible to generate p2 metadata with manual calls to the p2 metadata generator in any of PDE/Build's custom tasks (see Customizing a Headless Build). +However, PDE/Build does provide integration with p2 via the following properties:
+ +generate.p2.metadata |
+ (DEPRECATED, use p2.gathering instead) Set to true to turn on p2 metadata generation. The ant scripts are based on the existence of this property and not the value. To turn off metadata generation, the property must be removed and not just set to false. + In the build scripts, calls to p2 targets are generated when the p2 bundle org.eclipse.equinox.p2.metadata.generator and its dependencies are present in the Eclipse that is running the build. + These p2 targets are conditional on the generate.p2.metadata property. + |
+
p2.metadata.repo |
+ Specify a file: URI giving the location of the p2 metadata and artifact repositories to publish to. It is common, but not necessary for the artifact repository to use the same location as the metadata repository. + Example: +
+ p2.metadata.repo=file:${buildDirectory}/repository
+ p2.artifact.repo=file:${buildDirectory}/repository
+
+ |
+
p2.metadata.repo.name |
+ Optional. Specify a names for the generator p2 repositories. When using a repository that already exists, the existing name of the repository will not be changed. + If not specified, p2 will name the repositories according to their location. + |
+
p2.flavor |
+ Set the flavor for the p2 metadata. When metadata is generated for the Eclipse SDK, a flavor of "tooling" is used. | +
p2.publish.artifacts |
+ Set to true to publish jars into the artifact repository. If set to false, then artifact metadata is generated but the jars are not copied to the artifact repository. WARNING: when set to true, make sure that the p2.artifact.repo is not the same location as the assembly directories used by PDE/Build, otherwise jars might end up deleted! | +
p2.root.name |
+ Specify the name and version for the root IU that will contain everything that was built. + If a .product file is specified in the build, then these properties will be ignored. Instead, when a .product file is available the root name and version will be the product id and version from the .product file. See below for more information. + |
+
Metadata Generation for Products
+When running a build with a product file set in the top level build configuration build.properties file (both in builds using the productBuild.xml and the normal build.xml), then PDE/Build will automatically generate metadata for that product.
+In addition to creating Installable Units for all the features and bundles, this will also create the following product Installable Units:
+-
+
- A top level Product IU using the product-id and the product version. If no version is set in the .product file, "1.0.0" is used. +
- Configuration Units that set start level information for individual bundles as specified in the config.ini used for the product. +
- Configuration Units that set program and vm arguments for the product's launcher .ini file. +
- Configuration Units that add entries to the config.ini based on the config.ini used for the product. +
- Installable Units to deliver the branded launcher as well as any root files. +
- Configuration Units that set arguments in the launcher .ini file specifying -startup and --launcher.library to enable installing the product with a bundle pool. +
With all of these generated Installable Units, it is possible to use p2 to install the complete product out of the repository.
+ +The Details
+PDE/Build is essentially calling the metadata generation task provided by p2 at certain points during the build. It is likely that during a build there is never a single point in time where all build artifacts exist on disk at the same place. Therefore, it would be necessary to either call the p2 metadata generater on the final archives or, as an optimization, call it multiple times throughout the build.
+Metadata generation will occur throughout the assemble and packaging phases. This is true for both normal builds and packager builds. To illustrate, for a product build using productBuild.xml, the following scripts will be generated (assuming configs=win32,win32,x86 & linux,gtk,ppc):
+-
+
- assemble.org.eclipse.pde.build.container.feature.all.xml +
- assemble.org.eclipse.pde.build.container.feature.win32.win32.x86.xml +
- assemble.org.eclipse.pde.build.container.feature.linux.gtk.ppc.xml +
- package.org.eclipse.pde.build.container.feature.all.xml +
- package.org.eclipse.pde.build.container.feature.win32.win32.x86.xml +
- package.org.eclipse.pde.build.container.feature.linux.gtk.ppc.xml +
Assemble scripts collect features and plug-ins that were built along with associated root files. Package scripts collect pre built binary features and plug-ins. The platform specific scripts collect the pieces for those particular configurations and the "all" scripts delegate to each of the platform specific scripts.
+p2 generation calls will occur as follows:
+-
+
- assemble win32.win32.x86 : Generate metadata for collected features and plug-ins for windows. +
- assemble win32.win32.x86 : Second call to generated metadata for collected root files for windows. +
- assemble linux.gtk.ppc : Generate metadata for collected features and plug-ins for linux. +
- assemble linux.gtk.ppc : Second call to generated metadata for collected root files for linux. +
- assemble all : If not running the packager: Generate metadata for a root installable unit that includes everything above. +
- package win32.win32.x86 : Generate metadata for packaged features and plug-ins for windows. +
- package win32.win32.x86 : Second call to generated metadata on rootfiles from packaging windows. +
- package linux.gtk.ppc : Generate metadata for packaged features and plug-ins for linux. +
- package linux.gtk.ppc : Second call to generated metadata on rootfiles from packaging for linux. +
- package all : Generate metadata for a root installable unit that includes everything above. +
The p2 metadata generator task supports incremental generation, each call to the p2 metadata generated is done with mode=incremental, the final call to generate the root installable unit will run with mode="final"
+ + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/pde_p2_productbuilds.htm b/org.eclipse.pde.doc.user/tasks/pde_p2_productbuilds.htm new file mode 100644 index 0000000000..699fa6bf4c --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_p2_productbuilds.htm @@ -0,0 +1,83 @@ + + + + + + + +Product Builds with p2
+Defining the new property:
+will cause a few changes for product builds. In particular, the build will produce properly installed fully p2 enabled products.
+The following is a list of related properties (old and new):
+| p2.gathering | Set to true to turn on p2 publisher based builds. | ||||||||||||||||||
| p2.build.repo | A URI to the local build time p2 repository, default is file:${buildDirectory}/buildRepo. Results will be mirrored from here to the final archive location. | ||||||||||||||||||
| generate.p2.metadata | This is property for the old metadata generator integration. It has no effect when p2.gathering=true. | ||||||||||||||||||
| p2.metadata.repo p2.artifact.repo |
+ These properties are be URIs. By default for product builds, the final archives are the installed products and metadata and artifacts are left in the ${p2.build.repo}. If p2.metadata.repo and p2.artifact.repo are defined, then + the artifacts and metadata for the product will be mirrored from the build repository. | +||||||||||||||||||
| p2.metadata.repo.name p2.artifact.repo.name | Optional, these properties will be used to name the final repository when p2.metadata.repo and p2.artifact.repo are used. | ||||||||||||||||||
| p2.compress | Set to true to compress the final repository xml into a jar. | ||||||||||||||||||
| p2.flavor | The flavor of the product, used as a qualifier on the configuration metadata for the product. See below. | ||||||||||||||||||
| p2.product.qualifier | The qualifier to use when replacing "1.0.0.qualifier" in a product's version. If not set, the qualifier will be based on forceContextQualifier or the timestamp. | ||||||||||||||||||
| p2.publish.artifacts | No effect when p2.gathering=true (Old property) | ||||||||||||||||||
| p2.root.name p2.root.version | No effect when p2.gathering=true (Old property) | ||||||||||||||||||
| p2.context.repos | Define context repositories. See reusing metadata. | ||||||||||||||||||
| repoBaseLocation | A folder containing repositories to transform using <p2.repo2runnable>. See also reusing metadata. | ||||||||||||||||||
| transformedRepoLocation | The folder containing the output of <p2.repo2runnable>. See also reusing metadata. | ||||||||||||||||||
| p2.category.site | A URL to a site.xml file used to define categories. | ||||||||||||||||||
| p2.category.definition | A URL to a category.xml file used to define categories. | ||||||||||||||||||
| p2.category.prefix | Define a prefix to ensure unique ids for category IUs generated from site/category files that don't use unique names. | ||||||||||||||||||
| skipMirroring | Skip the final mirroring from ${p2.build.repo} to ${p2.metadata.repo}. | ||||||||||||||||||
| skipDirector | Skip the call to the director. No installed products will be produced. If p2.metadata.repo and p2.artifact.repo are defined, those repositories will contain the product metadata and artifacts, otherwise ${p2.build.repo} will contain the results. | ||||||||||||||||||
| p2.director.log | Location of a log file to log the results of the director call. | ||||||||||||||||||
| p2.director.profile | The name to use for the p2 profile created by the director. Generally it is a good idea to name this something related to your product. Default is "profile". | ||||||||||||||||||
| p2.director.extraArgs | Extra arguments to pass to the directory. Default is "-profileProperties org.eclipse.update.install.features=true". | ||||||||||||||||||
| Mirroring Properties | When building products or features, PDE/Build mirrors dependencies from context repositories to be included in the build.
+ These properties control what dependencies are included in this operation. See the p2.mirror ant task for details.
+
|
+
Product Flavor
+As part of a product build, PDE/Build automatically generates default configuration metadata to set start levels and config.ini property. This metadata is commonly referred to as Configuration Units (CUs). In particular, start levels are set +using CU fragments on the IU for the bundle being started. The flavor is used as a qualifier when generating the CU's name based on the IU.
+For example, with "p2.flavor = tooling", 'toolingwin32.win32.x86org.eclipse.core.runtime' will be the name of the CU that configures the org.eclipse.core.runtime bundle on windows. +It may be a good idea to use a flavor based on your product id to avoid conflicts with other metadata, particularly if your product has particular needs with respect to start levels. +
+See also the configuring products page.
+The director call
+PDE/Build includes a runDirector target that is called to perform installs during a product build. Currently, this is a fork of the director application in a new process. +In more advanced releng scenarios, it is possible to reuse this task to perform additional installs. The task requires that the location of the equinox launcher for the builder is defined. An example call would look something like this: +
+ <property name="equinoxLauncherJar" value="/builder/eclipse/plugins/org.eclipse.equinox.launcher_1.0.200.v20090520.jar"/>
+ <ant antfile="${eclipse.pdebuild.scripts}/genericTargets.xml" target="runDirector" inheritAll="true">
+ <property name="ws" value="gtk"/>
+ <property name="os" value="linux"/>
+ <property name="arch" value="x86"/>
+ <property name="p2.director.installPath" value="${installFolder}"/>
+ <property name="p2.repo" value="${p2.build.repo}"/>
+ <property name="p2.director.iu" value="my.rcp.product"/>
+ <property name="p2.director.version" value="1.0.0"/>
+ </ant>
+
+
+
\ No newline at end of file
diff --git a/org.eclipse.pde.doc.user/tasks/pde_p2_reusingmetadata.htm b/org.eclipse.pde.doc.user/tasks/pde_p2_reusingmetadata.htm
new file mode 100644
index 0000000000..76f8fb3631
--- /dev/null
+++ b/org.eclipse.pde.doc.user/tasks/pde_p2_reusingmetadata.htm
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+ Reusing p2 Metadata
+Metadata for a given feature or bundle can be different depending on how it was generated. Particularily when customizing metadata, or when features contribute root files.
+Because of this, it is always a good idea to reuse metadata when possible instead of regenerating it based on binary features and bundles that you may not own.
+ +The repo2runnable task
+There is an Ant task <p2.repo2runnable> which will transform feature and bundle artifacts into their installed form. Generally speaking, this is the shape we need the plug-ins to be in if we want +to be able to compile against them. This task allows us to easily reconsume repositories from other projects in our own build. PDE/Build has built-in integration with this task through the following properties:
+| repoBaseLocation | A folder containing repositories to transform. This folder can contain zipped repositories as well as sub-folders which are repositories. |
| transformedRepoLocation | The folder where the tranformed artifacts will be placed. This folder will then become a p2 repository itself. |
+New in 3.5 are custom targets preProcessRepos and postProcessRepos which occur before and after PDE/Build's call to <p2.repo2runnable>. This allows for automatically mirroring or download zipped repositories: +
+build.properties:
+ repoBaseLocation=${buildDirectory}/inputRepositories
+ transformedRepoLocation=${buildDirectory}/transformedRepo
+
+customTargets.xml:
+<target name="preProcessRepos">
+ <p2.mirror source="https://download.eclipse.org/releases/galileo" destination="file:${repoBaseLocation}/mirrored">
+ <iu id="org.eclipse.equinox.p2.user.ui.feature.group" />
+ <iu id="org.eclipse.cdt.feature.group"/>
+ </p2.mirror>
+ <property name="RCP.Repo-3.5RC3" value="https://download.eclipse.org/eclipse/downloads/drops/S-3.5RC3-200905282000/org.eclipse.rcp-p2repo-3.5RC3.zip" />
+ <property name="Equinox.Repo-3.5RC3" value="https://download.eclipse.org/equinox/drops/S-3.5RC3-200905282000/equinox-SDK-3.5RC3.zip" />
+ <get src="${RCP.Repo-3.5RC3" dest="${repoBaseLocation}/org.eclipse.rcp-p2repo-3.5RC3.zip" />
+ <get src="${Equinox.Repo-3.5RC3" dest=""${repoBaseLocation}/eclipse-equinox-3.5RC3.zip" />
+</target>
+
+(At the time of of this writing, the location of the 3.5 final zips was not yet known, the URLs here serve as an example only and may not exist at any later date.)
+PDE/Build will first call the preProcessRepos custom target, then it will call the repo2runnable ant task to transform those downloaded repositories into a form that can be reused by the build.
+The transformedRepoLocation property which defines the location for the output of this transformation also serves as a context repository.
+ +Context repositories
+The property p2.context.repos is a comma separated list of repositories that serve as context to the build.
+When generating metadata, build will first consult the context repositories to see if there is already existing metadata for the feature or plug-in. +If metadata already exists, then it will be copied into the build local repository (${p2.build.repo}) instead of new metadata being generated. +
+As well, if features, bundles, or products have customized their metadata to depend on something that wasn't included in the build, then PDE/Build will +perform a mirror out of the context repositories. This mirror operation will include any IUs that were added to feature or plug-in metadata.
+ + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/pde_packager.htm b/org.eclipse.pde.doc.user/tasks/pde_packager.htm new file mode 100644 index 0000000000..d1662a3aef --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_packager.htm @@ -0,0 +1,449 @@ + + + + + + + +
+ Packaging Eclipse Components
+
+ + Eclipse components are delivered as archive files. Each + archive contains a collection of features and plug-ins. + Typically the archives contain all the functions that a + particular component has to offer. It is often the case that + consumers either need more than one component and/or only + need parts of some components. Without assistance, consumers + would have to manually fetch the archives containing the + superset of the functionality they need and then manually + extract the required features and plug-ins. This can be a + laborious and error prone process. +
++ + Fortunately, PDE contains a batch oriented mechanism, the + packager, which can help. In short, the packager + takes as input a list of archives containing features and a + list of interesting features. It then fetches the zips, + extracts the features (and their plug-ins) and repackages + them into an output zip. +
+
+ Quick Start
+
+
+ Below is a set of basic steps to get started with the
+ packager. It is suggested that you build *nix packages
+ on a *nix machine to ensure that file permissions are
+ preserved.
+
+
-
+
- Create a packaging configuration directory and copy the + template files (packager.properties, packaging.properties, + and customTargets.xml) from + org.eclipse.pde.build/templates/packager here. + +
- Edit the copied packager.properties files and set the
+ following properties:
+
-
+
-
+ baseDirectory : the directory
+ in which the actual packaging work will take place.
+
+ +
+ -
+ featureList : a comma separated
+ list of feature ids that you wish to include in your
+ archive.
+
+ -
+ componentFilter : A comma
+ separated list of components in which your features can
+ be found. Specifying this will avoid unnecessary
+ downloads. Use * if you don't know the
+ components. (See the componentName in the
+ Packager
+ Map File Format below).
+ +
+ - + contentFilter : A comma + separated list of content types you are interested + in. Common content types are runtime or + sdk. This is used to optimize the + downloading of the archives. Leave this + blank to not filter on content type. (See the + contentDescription in the Packager Map File + Format below). + + +
- + config : The + configurations to package. This is an "&" separated + list of comma separated triples of operating system, + windowing system and architecture (eg + win32,win32,x86 & linux,gtk,ppc) + +
+
+ -
+ baseDirectory : the directory
+ in which the actual packaging work will take place.
+
- Get packager map files. The following properties
+ control downloading the map files:
+-
+
- + localMaps : Set this property + if you have map files locally, put the map files in + ${downloadDirectory} (by default this is + ${baseDirectory}/toPackage). Comment out + this property to automatically download the map file. + + +
- + packagerMapURL : The URL from + which to download the map file. + +
+ - Run the packager using the following command:
+
+java -jar <eclipse install>/plugins/org.eclipse.equinox.launcher_<version>.jar -application org.eclipse.ant.core.antRunner
+
-buildfile <<eclipse install>/plugins/org.eclipse.pde.build_<version>/scripts/package.xml>
-DpackagingInfo=<path to your packaging configuration directory>
+ +
+
+ Packager Map File Format +
The packager map files are used to describe the various + archives, their content and where they can be downloaded + from. They are similar to the map files used in the build + process to fetch bundles from repositories. The format of + a packager map file entry is as follows:+
+
-
+
+
-
+ archiveName : This is the name of
+ the archive
+
+ - + url : This is the url where the + archive can be found. The concatenation of url and + archiveName should point to the archive to download. + + +
- + configList : This is an "&" + separated list of configs that this archive contains. + (eg: win32,win32,x86 & linux,gtk,x86). + If no value is given the archive is considered to be + platform independent. + + +
-
+ directory : The directory where the
+ content of the archive should be extracted relative to a
+ standard eclipse installation. When no value is
+ specified it means that the archive contains an eclipse
+ installation directory at its root.
+
+ - + contentDescription : The content + flags indicating the type of content in this archive. + + Normally this is something like runtime, + sdk, source, doc, etc. + +
-
+ componentName : The canonical name
+ of the component this archive is for. For example
+ eclipse, jdt, cdt, gef, emf, etc.
+ +
+
+ Note that configList and directory are optional, it is + important that the appropriate number "|" separators are still + used.
+ Examples:
+
+eclipse-SDK-3.1-win32.zip=https://download.eclipse.org/downloads/drops/R-3.1-200506271435/ | win32,win32,x86 | | sdk | eclipse+
eclipse-PDE-3.1.zip=https://download.eclipse.org/downloads/drops/R-3.1-200506271435/ | | | runtime | pde
+
+ + Packager Configuration Properties +
The following properties can be set in the packager + configuration packager.properties file:+
|
+ baseDirectory + |
+
+
+ The directory in which all the packaging will take
+ place + |
+
|
+ workingDirectory + |
+
+
+ The directory in which the scripts will be
+ generated. The value in the template is
+ ${baseDirectory}/workingPlace + |
+
|
+ downloadDirectory + + |
+
+ The folder to which the archives will be
+ downloaded. The value in the template is
+ ${baseDirectory}/toPackage + |
+
|
+
+ tempDirectory + |
+
+ The folder that the archives will be extracted
+ to. The value in the template is
+ ${baseDirectory}/temp + |
+
|
+ featurePaths + |
+
+ The name of the root of the archives downloaded.
+ The value in the template is eclipse. + + |
+
|
+ featureList + |
+
+ A comma separated list of feature ids that you wish to
+ repackage. + + |
+
|
+ componentFilter + |
+
+ A comma separated list of the components from which the
+ features in featureList can be found. This
+ filters the available archives and allows the packager
+ to optimize the set of files downloaded. + + |
+
|
+ contentFilter + |
+
+ A comma separated list of content types to fetch.
+
+ This filters the set of available archives and allows
+ the packager to optimize the set of files
+ downloaded. + |
+
|
+ config + |
+ + + An "&" separated list of configs (comma separated + triples of operating system, windowing system, + architecture) to repackage. (eg: win32, + win32, x86 & linux, gtk, x86) + | +
|
+ archivesFormat + + |
+
+ The formats of the archives. An "&" separated
+ list of config - format. (eg: win32, win32,
+ x86 - antZip & linux, gtk, ppc - tar).
+ If no archive format is specified for a given config,
+ the default format is antZip. + + |
+
|
+ zipargs + |
+
+ Extra arguments to be passed to zip + + |
+
|
+ unzipargs + |
+
+ Extra arguments to be passed to unzip + + |
+
|
+ archivePrefix + |
+
+ The prefix of the resulting archive(s) + + |
+
|
+ collectingFolder + |
+
+ The name of the root folder of the resulting
+ archive. + + |
+
|
+ buildId + |
+
+ Controls the build id in the default name of the
+ archive. + + |
+
|
+ buildType + |
+
+ Type of the build, used in naming the build
+ output. Typically one of I, N, M, S, ... + + |
+
|
+ buildLabel + |
+
+ Label for the build. The template value is
+ ${buildType}.${buildId} + + |
+
|
+ archiveNamePrefix + |
+
+ Control the name of the resulting archive. The
+ default value of this is ${buildId} + + |
+
|
+ packagingProperties + |
+
+ A relative path to the file containing the properties
+ packaging root files.. By default this points to
+ packaging.properties. + + |
+
|
+ deltaPack + |
+
+ Whether or not to generate a delta pack. This
+ will exclude platform independent pieces and will group
+ all configs into one archive. + + |
+
|
+ unzipOrder + |
+
+ a comma separated list of archive name prefixes setting
+ the order in which archives should be extracted. + + |
+
+
+ Packaging Root Files +
In the packager configuration packager.properties file, + the property packagingProperties points to a property file + which specifies the root files that need to be packaged. + By default this is the file packaging.properties.+ +
+ This property file should contain the properties specifying the + required root files. See the + Feature specific properties page for details on the root + properties.
+
+ + \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/pde_plugins_build.htm b/org.eclipse.pde.doc.user/tasks/pde_plugins_build.htm new file mode 100644 index 0000000000..45bcae8b51 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_plugins_build.htm @@ -0,0 +1,45 @@ + + + + + + + +
Building plug-ins / bundles
++In order to build plug-ins, bundles or fragments, PDE build requires that you create a feature listing all the elements to be built. +In this case the feature is only used to drive the build and will not be present in the final archive nor will it force you to use update sites. +
+
+A feature used to drive a plug-in build is a standard feature. What makes it different is that its build.properties file does not contain the property bin.includes. It is possible to automatically generate a feature containing the plug-ins you wish to build. This lets you build your plug-ins without requiring you to maintain a feature.
+See the eclipse.generateFeature task and the Customizing a Headless Build page.
+Example:
+
+build.properties: topLevelElementId = acme.build.feature
+customTargets.xml :
+ <target name="preSetup">
+ <eclipse.generateFeature
+ featureId="acme.build.feature"
+ buildDirectory="${buildDirectory}"
+ baseLocation="${baseLocation}"
+ productFile="${product}"
+ verify="false"
+ pluginPath="${pluginPath}"
+ configInfo="${configs}"
+ pluginList="acme.plugin.A,acme.plugin.B"
+ featureList="${featureList}"
+ includeLaunchers="false"
+ />
+ </target>
+
++Once you have created the feature to drive the build, follow the instructions on building features. +
+ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_product_build.htm b/org.eclipse.pde.doc.user/tasks/pde_product_build.htm new file mode 100644 index 0000000000..cc92cc207c --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_product_build.htm @@ -0,0 +1,103 @@ + + + + + + + +Building an RCP application from a product configuration 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.
+
Basic setup
++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 "
/<plug-in 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 org.eclipse.equinox.executable feature (it is available +from the eclipse p2 repository) 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
+<buildDirectory>/+
plugins/
pluginToBuildA
pluginToBuildB
myProduct.product
...
features/
featureToBuild
...
<buildConfiguration>/
build.properties
<baseLocation>
plugins/
org.eclipse.core.runtime
org.eclipse.ui
...
features/
org.eclipse.rcp
org.eclipse.platform.launchers
...
Running the build
+To run the build you will use the org.eclipse.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.
+
+
java -jar
+<eclipseInstall>/plugins/org.eclipse.equinox.launcher_<version>.jar -application
+org.eclipse.ant.core.antRunner -buildfile
+<<eclipseInstall>/plugins/org.eclipse.pde.build_<version>/scripts/productBuild/productBuild.xml>
+-Dbuilder=<path to the build configuration folder>+
Advanced scenarios
+Behind the scenes this setup will generate a feature containing the +plug-ins 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, +i.e. fetching from a repository, see the Advanced +PDE Build topics for +more information. +
+ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_rootfiles.htm b/org.eclipse.pde.doc.user/tasks/pde_rootfiles.htm new file mode 100644 index 0000000000..31727ee192 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_rootfiles.htm @@ -0,0 +1,111 @@ + + + + + + + +Adding Files to the Root of a Build
+
+ Root files are files that must be packaged with an Eclipse install but are not features or plug-ins. Common examples are the eclipse executable and ini files as well as licensing files.
Root files are contributed to a build by features containing the appropriate root properties.
Root file Properties
+root |
+ Specify a list comma separated list of files or folders to be included in all configurations being built. Relative paths are relative to the containing feature. Use "file:" to specify a file and "absolute:" to use an absolute path. + Examples: +
Each comma separated entry becomes an ant fileset. If the entry refers to a folder, then that folder is the "dir" parameter of the fileset and a "**" is used as the "includes" parameter. If the entry is a file, then the containing directory of the file becomes the "dir" parameter and the file is specified in the "includes" parameter. +For all relative files, the property ${baseDir} will be used in the directory. This ${baseDir} property will be feature's root directory where the generated build.xml file will be located. + + |
+
root.<config> |
+ Specify a list of files or folders to be included for the given configuration. Configurations specified here should correspond to configurations in the configs property for the build.
+ Relative paths are relative to the containing feature. The same "file:" and "absolute:" prefixes used in the "root" property also apply here. + Examples: +
|
+
root.folder.<subfolder> root.<config>.folder.<subfolder> |
+ Similar to the "root" and "root.<config>" properties, except that instead of being copied into the root of the eclipse install, files and folders are instea copied into the given subfolder.
+ Relative paths are relative to the containing feature. The same "file:" and "absolute:" prefixes used in the "root" property also apply here. + Examples: +
|
+
root.permissions.<rights> root.<config>.permissions.<rights> |
+ Specify a list of files to on which to run the ant chmod task. The value of this property will be passed to the ant chmod task as the "includes" parameter. This means that ant wildcard patterns can be used. + Examples: +
The + <rights> portion of the property is actually passed to the ant chmod task as the "perm" parameter. If the final archive format for the configuration is antTar, then the <rights> format is also passed to an ant tarfileset as the "filemode" parameter. Similarly, for antZip and zipfileset. While the ant chmod task supports permissions such as "og-rwx" (make non-owners unable to touch the file), the tar and zip filesets only support 3 digit octal strings. |
+
root.link root.<config>.link |
+ List by pairs (separated by comma) the files and folders that need to be symbolically linked. The first entry of the pair is the target and the second entry is the link name.. + Example: +
This results in an ant exec task that executes an "ln -sf" command. Given a value of "targetA, nameA, targetB, nameB, targetC, nameC", a set of "ln" commands will be executed in the folder where the eclipse rootfiles are collected: + ln -sf targetA nameA +ln -sf targetB nameB +ln -sf targetC nameC+ |
+
Including Root Files in a Product Build
++ When using a .product file based on features, then rootfiles can be added to the product simply by specifying the above rootfile properties in any of the included features. +
+It is possible to include a feature solely for the purpose of contributing rootfiles. If this "rootfile" feature does not specify a "bin.includes" property in its build.properties file, then it will not be included in the final build results, but its contributed rootfiles will be. +
+ +When a .product file is based on plug-ins instead of features, rootfiles can still be added to the build. In a product build, PDE/Build automatically generates a container feature which includes all the plug-ins specified in the .product file (See the eclipse.generateFeature task). There are two ways to add rootfiles to this product build:
+-
+
- Create a feature that contributes rootfiles, but does not specify a bin.includes property. Add this feature to the automatically generated container feature by setting the featureList property:
+
+ ${buildDirectory}/features/org.foo.rootfile.feature/rootfiles/* + /build.properties : root = rootfiles + ${buildDirectory}/build.properties: featureList = org.foo.rootfile.feature ++
+ - Add a build.properties file containing absolute root properties to the automatically generated container feature:
+
+ ${buildDirectory}/build.properties: generatedBuildProperties = ${buildDirectory}/root.properties + ${buildDirectory/root.properties: root = absolute:${buildDirectory}/rootfiles + ${buildDirectory}/rootfiles/* ++
+
Using Shared Licenses
++Many Eclipse features use the same license. For example, all features in the Eclipse SDK use the Eclipse +Foundation Software User Agreement. If individual licenses are added to each feature built with PDE, updating +them will be very tedious. Using the shared license support allows multiple features to reference license text +and files from a single location. This makes updating licenses across multiple features easier and less error prone. +
+
+To create a license feature, create a feature that does not include any bundles or features. Add the necessary
+license files and ensure they are included in your build.properties. The feature.properties should have two
+properties, licenseURL and license.
+
+To make use of the shared license facility, simply open your feature.xml file in the feature editor. Select the
+Information tab and then the License Agreement section. Selecting Shared license will allow
+you to specify the feature and version that contains your license text and optional license files. The
+license-feature and license-feature-version attributes will be added to the feature
+element of your feature.xml. If you are converting a single license to a shared license, you should remove the license
+files from the individual features. The license information should be removed from feature.properties and
+build.properties.
+
+The new shared license feature will have to be included in the build, so update your map files appropriately. You do not +need to nest the feature in another feature to fetch it, it happens automatically. An IU will not be created in the p2 +repository for the license feature, but the license text will be included in the p2 metadata. +
+ + + + diff --git a/org.eclipse.pde.doc.user/tasks/pde_source_generation.htm b/org.eclipse.pde.doc.user/tasks/pde_source_generation.htm new file mode 100644 index 0000000000..5310e79303 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_source_generation.htm @@ -0,0 +1,131 @@ + + + + + + + +Generating Source Features and Plug-ins
+Starting in 3.4, Eclipse has shipped with individual source bundles which allow for more flexible delivery of source. See the "Individual Source Bundles" page for details. Traditional folder-shaped source plug-ins can still be built as outlined below. +
++Consider the following SDK feature:
+
features/+
org.foo.sdk/
feature.xml: <includes id="org.foo.rcp" />
<includes id="org.foo.rcp.source" />
build.properties: generate.feature@org.foo.rcp.source = org.foo.rcp
org.foo.rcp/
feature.xml: <plugin id="org.foo.BundleA" />
<plugin id="org.foo.BundleB" />
<plugin id="org.foo.BundleB.win32" fragment="true" os="win32" />
+The idea of the SDK is that it includes a feature as well as +the source for that feature. Notice +the generate.feature property in the feature's +build.properties +file. This property tells PDE Build to generate a feature named +"org.foo.rcp.source" based on the contents of the feature +"org.foo.rcp". PDE build will generate an +org.foo.rcp.source feature, a plug-in that +will contain the source code, and fragments containing the source of +any platform specific bundles that were included in the feature:
+
features/+
org.foo.rcp.source/
feature.xml: <plugin id="org.foo.rcp.source"/>
<plugin id="org.foo.rcp.source.win32" fragment="true" os="win32" />
plugins/
org.foo.rcp.source/src/
org.foo.BundleA/src.zip
org.foo.BundleB/src.zip
org.foo.rcp.source.win32/src/
org.foo.BundleB.win32/src.zip
Customizing the Generated Source Feature
++The generate.feature property has the following form:
+generate.feature@<source feature id> = <feature id> [, feature@<feature id>[;attribute=value]*]* [, plugin@<plugin id>[;attribute=value]*]*+
-
+
- <source feature id>: +This is the id of the source feature and plug-in to be generated. +Normally it is something like <feature id>.source +
- <feature id>: +The feature on which to base the source feature, the source for all +contained plug-ins will be collected into the <source feature id> +plug-in. +
- feature@<feature id>: +This will include the named feature in the generated source feature. +
- plugin@<plug-in id>: +This will include the named plug-in in the generated source feature. +If the plug-in is JARed specify unpack="false". If multiple versions +of the plug-in are available, specify the requested version using version=<pluginVersion> followed by qualifier. +
-
+attribute=value : Both feature@ and plugin@ entries can be qualified with additional attributes that should be added in the generated source feature.
+Possible attributes (with example values) for feaure@ entries are: +-
+
- version = 1.0.0 : specify the version of the feature to include +
- optional = true : set the included feature as optional +
- ws=gtk : set the window system for the included feature +
- os=linux : set the operating system for the included feature +
- arch=x86 : set the architecture for the included feature +
-
+
- version = 1.0.0 : specify the version of the plug-in to include +
- unpack = true : set the included plug-in to be unpacked (ie the plug-in should be installed as a folder). +
- ws=gtk : set the window system for the included plug-in +
- os=linux : set the operating system for the included plug-in +
- arch=x86 : set the architecture for the included plug-in +
+
+Use plugin@ to add additional plug-ins that weren't part of the +original feature to the generated source feature. This is useful +for documentation plug-ins. The feature@ together with a source +template can be used to nest source features (see below). +
+ +Source Templates
++The feature from which the source feature is being generated can +provide template files to be included in the generated source feature:
+
features/+
org.foo.rcp/
sourceTemplateFeature/<files to be included in generated source feature>
sourceTemplatePlugin/<files to be included in generated source plugin>
sourceTemplateFragment/<files to be included in generated platform specific fragments>
Any files located in these sourceTemplate folder will be included in +the appropriate generated feature/plug-in/fragment. Specifically, +files from these directories will replace files generated by PDE +build. This can be used to provide a custom feature.xml if there +are requirements for your source feature that PDE build does not +support. +
+Nesting Generated Source Features
+You can nest source features by providing a
+sourceTemplateFeature/build.properties file for your generated source
+feature that contains a generate.feature property for the nested source
+feature. You will also need to ensure that your top source
+feature.xml includes the nested source feature, do this either by using
+feature@ or by providing a template feature.xml:
+
features/+
org.foo.sdk/
sourceTemplateFeature/
build.properties: generate.feature@org.foo.nested.source = org.foo.nested
feature.xml: <includes id="org.foo.rcp" />
<includes id="org.foo.rcp.source" />
build.properties: generate.feature@org.foo.rcp.source = org.foo.rcp, feature@org.foo.nested.source
org.foo.rcp/...
org.foo.nested/...
Generating a Source Plug-in
+It is also possible to generate a single source plug-in based on a +feature instead of generating an entire source feature. The +property to do this is:
+generate.plugin@<source plug-in +id>=<feature-in id>
+Be aware that these old-style source plug-ins (one plug-in containing +the source for all plug-ins of the feature) must be installed in folder +form. Therefore you have to set the unpack="true" attribute +in the file feature.xml.
+Example: +features/+
org.foo.sdk/
feature.xml: <plugin id="org.foo.rcp" />
<plugin id="org.foo.sdk.source" unpack="true" />
build.properties: generate.plugin@org.foo.sdk.source = org.foo.sdk
+
+ + diff --git a/org.eclipse.pde.doc.user/tasks/pde_version_qualifiers.htm b/org.eclipse.pde.doc.user/tasks/pde_version_qualifiers.htm new file mode 100644 index 0000000000..4370160fe2 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/pde_version_qualifiers.htm @@ -0,0 +1,95 @@ + + + + + + + +
Using Version Qualifiers
+Eclipse bundles and features have version numbers of the form major.minor.micro.qualifier. The qualifier
+segment of the version is often used to indicated a specific
+build. If you set your feature or plug-in version qualifier to
+"qualifier" (i.e. a version of 1.0.0.qualifier),
+then PDE build
+will
+automatically replace the word "qualifier" with a generated qualifier.
+
Controlling the Generated Qualifier
+A feature or plug-in can control its qualifier by setting the property "qualifier" in its build.properties file. There are are a couple of different cases for the value of this property:
+| qualifier = none | Sets the qualifier to be empty. (i.e. "1.2.3.qualifier" becomes "1.2.3") |
| qualifier = context | Sets the qualifier to be the context qualifier. See below for the value of the context qualifier. |
| not set | If the "qualifier" property is not set, this is equivalent to setting qualifier = context. |
| qualifier = v12345 | Any other value sets the qualifier to be that value. |
The Context Qualifier
+The value of the generated context qualifier is determined by the first of the +following items that apply:+
-
+
- If the property forceContextQualifier is set in your builder's
+configuration build.properties file, then the value of this
+property is used as the qualifier. This property can also be set
+on the command line with -D when invoking ant.
+-
+
- When exporting from the UI, forceContextQualifier is set according to the "Qualifier replacement" value on the options tab of the "Deployable plug-ins and fragments" export wizard. +
+ - If you are using map files to fetch your bundles from a +repository, +then the tag that was used to fetch the bundle will be used as the +qualifier. +
- If neither forceContextQualifier nor map files are used, then the
+qualifier will be a time stamp in the form YYYYMMDDHHMM (i.e.
+200605121600)
+
+
Feature Version Suffixes
+You can turn on the generation of qualifier suffixes for features by +setting the property generateFeatureVersionSuffix=true +in the build configuration build.properties file.+
+The idea of a version is that it should increment each time something +changes, the version qualifier increments and captures changes from +build to build. Features rarely change, however, they do contain +plug-ins which may change often. When version suffixes are turned +on, a feature version will have the form major.minor.micro.qualifier-suffix. +The suffix is in effect the sum of the version qualifiers of all the +features and plug-ins included by the feature. This means that +when one of the included plug-ins increments its version, then the +version of the feature will automatically increment as well. This +is particularly useful when the feature is deployed via an update site.
+
+
Final Versions
++Occasionally there may be custom build steps that may require the +actual final version used in the build. When the property generateVersionsLists is set, PDE Build will generate +properties files containing the versions of the features and plug-ins +that were built. These properties files can be loaded using the ant property task.
++The files are named: +finalPluginsVersions.properties, +finalPluginsVersions.<config>.properties, +finalFeaturesVersions.properties, and +finalFeaturesVersions.<config>.properties. +finalPluginsVersions.properties and finalFeaturesVersions.properties +contain the versions for all of the plug-ins and features that were +built. The <config> properties files contain the versions +of plug-ins and features for specific build configurations.
+
+The properties in these files have the form:
+
<bundleSymbolicName> = <version>+If more than one versions of a plug-in or feature exists, then +<bundleSymbolicName>=<version> refers to the plug-in or +feature with the highest version. +Example:
<bundleSymbolicName>_<first 3 segments of version> = <version>
+
org.eclipse.pde.build = 3.3.0.v20070524+ \ No newline at end of file diff --git a/org.eclipse.pde.doc.user/tasks/ui_export_install_into_host.htm b/org.eclipse.pde.doc.user/tasks/ui_export_install_into_host.htm new file mode 100644 index 0000000000..b0850a5df3 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/ui_export_install_into_host.htm @@ -0,0 +1,37 @@ + + + + + + + +
org.eclipse.pde.build_3.3.0=3.3.0.v20070524
org.eclipse.pde.build_3.2.1=3.2.1.r321_v20060823
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) +
Related references
+Eclipse Application Launcher+Export Wizards
+Plug-in Export Wizard
+Feature Export Wizard + + diff --git a/org.eclipse.pde.doc.user/tasks/ui_import_from_cvs.htm b/org.eclipse.pde.doc.user/tasks/ui_import_from_cvs.htm new file mode 100644 index 0000000000..10341b5b21 --- /dev/null +++ b/org.eclipse.pde.doc.user/tasks/ui_import_from_cvs.htm @@ -0,0 +1,56 @@ + + + + + + + +
Import Projects from a Repository
++The Plug-in Import Wizard allows you to create projects in the workspace by importing plug-ins from the active +target platform, a directory, or a target definition. If the plug-ins you are importing contain appropriate source +reference information, the import wizard allows you to import the projects associated with those bundles from +a repository. +
++For example, the plug-ins in the Eclipse SDK contain Eclipse-SourceReference: headers identifying the CVS +repository and projects the plug-ins originated from. You can import the specific version of a project that a plug-in +was built from or you can import the associated project from HEAD. +
+ +To import plug-ins from a repository do the following:
+-
+
- Open the import wizard:
+
+File > Import... > Plug-in Development > Plug-ins and Fragments
+
+
- In the Import From section, select a source of plug-ins such as the active target platform.
+
+
+
+ - In the Import As section select Projects from a repository.
+
+
+
+ - Press Next. A list of plug-ins in the target platform that can be imported from a repository will be +shown. Select the plug-ins you want to import and press Next. + +
- The next page allows you to import specific versions of the associated projects (the versions used to build the
+target platform), or from HEAD. Select the desired option and press Finish. The projects
+will be imported and appear as projects in the workspace.
+
+
+
You can also import plug-ins from a repository from the Plug-ins View. Select the plug-ins you want +to import and use the Import As > Project from a Repository... action.
+
Related references
+Import Wizards+Plug-in Import
+ + diff --git a/org.eclipse.pde.doc.user/tipOfTheDay/pdetips.json b/org.eclipse.pde.doc.user/tipOfTheDay/pdetips.json new file mode 100644 index 0000000000..3b8be2b02c --- /dev/null +++ b/org.eclipse.pde.doc.user/tipOfTheDay/pdetips.json @@ -0,0 +1,25 @@ +{ + "provider": { + "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAYAAABXAvmHAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4gQaFCYB8oq5DAAAAB1pVFh0Q29tbWVudAAAAAAAQ3JlYXRlZCB3aXRoIEdJTVBkLmUHAAAJ+klEQVRo3tWa228cdxXHP7+Z2avtdeIktnNxkqaX9EbUkBZEpTSlQICCaAsSqlokxFMLL0g8ABJvSCAhBP8AiCckhBASFyFUELdyKbSJoGmhkDSx4zSOE8exvd7d2Znf73cODzO73nUTYtMYhZVWHo88M+d7Lt/zPWdsVJX/m4+CV3BeSFIl9Ur0/2C3KHivpFZJrGB95nRjzM0NQBVSJ3ivJE6xVlmdL9HN6nHnBe/BebBOcXL1VL/pADivWK+orByLXLtOo5spXRIrdGx1oqROrntddLN43bmV/HZOu4V6UwBIrEdECQNDsRD2ed16xfcY67zg/NrvHW1sMSqTM3X9w4nzNGPLQLnAw2/fxZ7xmoGM03v97IV1GQ9gNrKRvfiPWf35n//J4UN3UC4ELLcWeP74HM8c3Uo89TNUPKP738/g2EFjnZA6yQDlwDq2aQfoKsDGGIKNjMCvjk3zocN7uX9/xD17K9y9t4y4Nr/5/ueJF88gdoFXfvJp6hdPqKgBs/5nbEgKxYnjb6cuaakUMTG2HZs22TQYcnlxkDhuUxnexX1PfBNIuHC8yqlffZnxA0/q1tsfNY4i68mJNURAUZXrfjvBnVuMj33ze8f1R78/wx17tnBpoYEXJXWeIEgwxmTX+AbYJpt2HGRg0yDzJ3/I2T9+XcPA3LgI2KTBxelj2m7MUygP9YkqyCKe5apQKA4wvvd+88KrM4du3b2Z3eMlysUB5pcaDJRaJHYrzTjGYAFBfQoaU6gMMXrLQYq13bzw3c+w5/CXMMZco1foOgCo8tLPv6LV4TGGttzGuXlDK3FgwOTdRpFusdUvv8y2WdEzM0N86KFbOD19jpEdNd643Gb2SpVyKaHRKiBayCmqjfplAmlTLJUpV4bwSZOzf/yGElW6xZu5yIAJGbv74yYobUZ6gPQBcNYiIhgM8xdOqAkiDjz0DFeWE770jefYtnmMdmrR3PeBMQR5yFX2o5NNRrdGGKCdBjTbjmYcUI4U5z3tVMjalYBvgL2CuAVqW3dhfXbX5fO/ICoOAIoJI8JiiXjpChenZ6jWtmvt9seMuo68UCIRIY5jRJR/nDijSwvLgJDO/Zgjjz2LunmMDxmpVRkeKlO0Ja5dZYZNQwWabYeTCC9KM7FUigGiAYnV3HuKuiU0vQQuxhRqkLbAwL4HHqc6PNp31+bCPJ4/ZfdIBJtLjCAwRK1Wi+PHj+niUoOLl8oU579NsWjYObGDUrSAbbRx7S3cNrGTxRiq1+GtIDA0Wo7ZhTbj24QkEZoFj/NZIXeFmdRRV0e8J9IUnzZAhahQIixU+u45tG0ne+59B1qpstp7kYhQKBR5+MgR89xzJ/XDj38OZxcIghD1bUxgaNgyUxfmqLfs9WlhtMpi0zK30MJaQURoxJa4bbDe41yeQgjiPc7GmOYs6kNUlelXfk2xMvSmyKbNZQZ3DVEdWwWgVqvx4IMPGms9qlAd2U66lKKSgljAMDrc5t0HqmtQh4bJS0LqlIvzTRLrcV6QXFl6L3iRnppLca06CcsYUwaU0siDmKi64mfJfF4cNAzufgQnpi8KfQnhu+FNwSfd80V5g0cPrIGfTcgP/jKIKIhkDc15RVVptixeJHuGZtRr42XS5gzLdY9P2gRRhbFDz5okzWKEaiYjcgmRArJKpUa9yrDrHbG597sdgTAAY/S6Q/fdE8P86KUZ4tiy2EhQFOuEZtsStx3OC4HxhIGQtuawS1NcOv0GcQx3Hv1q3luFvNb7AFxNtkU90c8joKi4LAo5MsHwixfLvH6+AAY6zTL7mWkYk39LVeHKrKe+EHDi1TphYEitpxFLRqN2gJML9/HTPw1QPz+BpoNcnL2L0shdTF14H8n0lB5+YNwM14rr7MSaDRadFFJJEVHmlwz1OOT00h6eeOqufg7Q/vwHMAG8t7cB9bbs7gVHCYxBeSQ/laFXhb//8wrH/jqp9x/Y8rXa8MgXr6fwVtVATwr5lLOznvNLo7wyWWL3fTshjNYmGHNhqZoN6KIgRrvHvTue1WlxanKJt43HnH395S/ce/DIF00QrhWArqqBlFrJ46qX+NbJ23n0YzVGSlc3lu4cC6mQrUBE8ZoVY18e9+Syrgpi3HJUgoBbbrvTzM/N6LU00TUAmC5DdABsqcGLJ4scfvg2Ng2ErF4OOIHEKy2rNK2SylVxrXmq/91vp3nobSOUSmXGd+0zHRZaEwDNNwGgXQDWGV67MMIHnhwlMnRFVGyVepoZ3nY3ZqJbrqdIyzGxY8D8l3I6H65NpwYsF+YjGsW9bBsIULL13kxDqCeKl57yMm/NeBVhemqJh945ShgY1jPl9hex+m4NqCR855cTHHz/diqRoZUq5xY9TSvc6E+aWmbP1Tl63+Z1u6KPRrvrDbWcnQ2ZcXv5xK3DtFLl9cuWOL3xCwBV4eyZRbZvLlIohG9tJs4AKOotz/99mEeO7mewZDh1ydJIbrznRZU0bvOvVy/z2af3G2NgvUuS/iLOr15swLGLd/L0zgHmm54rDY8xN9rzYNOExStN7tk3RLVsEC89VKsrUgKTM5q5XgSyyvzda9vYPHELY8MRr11I1r1sWsuiwKUJaZIwdWqBj7xrlLSdrPQG7W30BkyACUKu5sU3d2IHv3ztVj761DjnLlsasdxQ76uCd5a0HdNYbrM422Jsc2hcuqK9tCuuAoIwzHWWuWpfeZOcPj3t2bZnB4OVkKk52zdAv/WPyT0fI94ydbrOE+/egroEJx31ZCDIDA/CgCAIMVGUgdLrsFA78fzsD3Um9uygGXvsW6bMldWgiGQDTNrGeYttW4LUsnc8MjaxnV1hZrgJCAoRUaGMCcP/WNg9clppteH5ly2f+mSVNy5b1u987dvfqAoiHnEe51LEe7x3eG+Zn4vZNQxpkmAUTBgSFgqEhQLFcpWgWMyXYGtlIQUxNQ49sJ3FhuC8rDu5FUUlow6R3HjJjBbvEWfx3uKc5fS/Grzng5vwzhEVSxTKZQqVKoVSmSCM0DVyaheAiFKuDOK8cvLUYt/Ofg3Lxy6vZwJM0B4AIh71Hu894i2NpmXftpDxrSVTKJUoDgxQrFSJCkVMEKxso9faB1QVSe2+9xwa5PT0HOWeqPznZLn232nPPEOQH0chEBHVqhx5+5CpDlcoVipE5TJhGPXPPOt9PyAiqGg+hKzI2BXjtJ+fO8pbO2Nn91xBFdtxTN9uX7V7LPRMYpg8BVfm4KsN9asdFQQ974mDIEBzpjJ6NWO17wVD58YmN9SsPMj2gI8Udd0BnRUQQd+5dfDwqhgFq1PiJv/XA732+wGFDbB9w70RbPCT5H8CYAOzZsMjEE1OTg7lrOFX6n7l0cqbmafzgkA7P1GT16bRnvNo/+/aZYOVdxfaVc79D+xloWs5OQhD82/McZm8zj6rsgAAAABJRU5ErkJggg==", + "description": "PDE Tips", + "expression": "
Tips and Tricks
+ + +| New Spies in PDE | +
+ The following spies has been added and can be accessed by Windows > Spies :
+
+
+ |
+
| Reference an existing target inside another one | +
+ It is now possible to reference an existing target file inside another target:
+
+
|
+
| Show Command Line button in PDE Launch Configuration | +
+ You can view the command line used for launching the application by clicking the Show Command Line button on the PDE launch configuration dialog.
+
+ |
+
| Disable API analysis builder | +
+ You can disable the API analysis builder on the Plug-in Development preference page.
+
+ + |
+
| Layout Spy tool | +
+ To debug SWT layouts, you can activate the Layout Spy tool by using the shortcut Ctrl+Alt+Shift+F9 from any window.
+
+ Usage: +
|
+
| Change problem severity | +
+ You can configure the severity of an API tools problem or PDE compiler problem by invoking the Quick Fix (Ctrl+1) which opens the
+ corresponding preference page and highlights the configurable problem.
+
+ |
+
| Workspace plug-ins overriding target plug-ins | +
+ On the Plug-in Development preference page, there is an option to specify if workspace plug-ins should override target platform plug-ins
+ with the same id. By default, this option is enabled. When disabled, all plug-in versions from workspace and target platform will
+ be used and for a plug-in id, the best available plug-in will be chosen.
+
+ |
+
| Support for OSGi Declarative Services Annotations | +
+ OSGi Declarative Services provide a powerful mechanism for developing complex, service-oriented
+ applications. With proper tooling, annotations added to Declarative Services make it easy
+ to generate and maintain the required component descriptor files.
+ + When enabled, PDE automatically generates and updates Declarative Services component + descriptor files from appropriately annotated Java source. This is done without requiring + any additional builder to be configured in your project. + +
+ When you annotate your component implementation classes with + In addition, PDE also maintains the project's MANIFEST.MF and build.properties file + -- generated component descriptor files are automatically added to the manifest + and included in the build. + ++ To enable this feature, go to Preferences or Project Properties > Plug-in Development > DS Annotations + and check Generate descriptors from annotated sources. + + |
+
| Convert API Tools Javadoc tags to annotations | +
+ Plug-ins using API Tools can add restrictions to API Java types (such as No Reference, No Extend)
+ using Javadoc tags or annotations. It is recommended that projects use annotations, so PDE
+ provides a conversion wizard that will replace the tags with the equivalent PDE annotations.
+ + The wizard is available by right clicking on an API Tools enabled plug-in project and selecting + Plug-in Tools > Convert API Tools Javadoc Tags. + ++ A list of the available restrictions is available on the API Tools + wiki page. + + |
+
| Show the current target platform in status bar | ++ If you regularly switch between target platforms, PDE provides an option to show the current target + platform in the status bar. On the Plug-in Development preference page, select + Show current target platform in status bar. The status bar entry will show the name of + the active target definition and will show an error icon if there are problems with the target. + | +
| Find a feature by entering a plug-in name in the feature selection dialog | ++ When adding a feature to a product, feature or launch configuration, you can enter the name of a plug-in in the filter text box + of the feature selection dialog. Features that include that plug-in will match the filter and be displayed. + | +
| Reload button in target editor | ++ In scenarios where the target editor is left in inconsistent state due to issues like unstable network connection and + it is impossible to resolve the condition without manually editing the target editor file, you can use the Reload button in the Locations section of Target editor. + It clears the cached p2 profile and then resolves the target. + | +
| Set default preference values for your product | ++ In order to set default preference values for your product, instead of manually adding the preferences to product's customization file, you can use the + Convert Preferences wizard in the Customization section of your Product editor. + | +
| Create an API Baseline from a Target Definition | ++ To avail API tooling functionalities for any target definition, you can create an API Baseline in the Plug-in Development > API Baselines preference page. + | +
| Quickly search for any plug-in artifact | ++ Use the Open Plug-in Artifact dialog to quickly find and open plug-in artifacts. Search + by the name of the plug-in, feature or product, or search for a specific package, extension point + or extension. The icons can be used to see whether the artifact is available in the workspace or + if it comes from the target platform. You can press Ctrl-Shift-A to open the dialog. + | +
| 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. |
+
| Importing with linking | +Importing external plug-ins and + fragments can be time consuming and may result in large workspaces, + depending on the content of the plug-ins being imported. Therefore, + the 'Import External Plug-ins and Fragments' wizard gives you the option to + import with linking. This means that the import operation will not + copy the resources being imported into your workspace. It will simply + create links to the files being imported. You will be able to browse + these linked resources, as if they had been copied into your workspace. + However, they are physically not there on your file system, so you will not + be able to modify them. Beware of operations that depend on files + being physically in your workspace, as they will not work on linked + resources. | +
| Templates | +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. | +
| Plug-in dependency extent | +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 Plug-in 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. |
+
| Finding unused dependencies | +Minimizing a plug-in's number of + dependencies is certain to improve performance. As your plug-in + evolves, its list of dependencies might become stale, as it might be still + containing references to plug-ins that it no longer needs. A quick way + to check that all dependencies listed by your plug-in are actually used by + the plug-in is to run the 'Find Unused Dependencies' utility, which is + available through the context menu of the 'Dependencies' page of PDE's + manifest editor. | +
| 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 Workspace Scope
+ from the context menu. This is handy for remaining
+ aware of other plug-ins that depend on ones you're working on.
+ On the Plug-in Development preference page you can also turn on + Include all plug-ins from target in Java workspace scope, which will add every + plug-in in your target platform to the search scope. |
+
| + 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.
+ |
+
+ 
+ 
+ 
+ 
+ 
+ 
+ What's New in 4.30 (PDE)
+Here are descriptions of some of the more interesting or significant changes made to the Plug-in Development Environment (PDE) +for the 4.30 release of Eclipse. They are grouped into:
+-
+
+
- Editors + + + + + +
Editors |
+ |
| Support for names of product update repositories | +
+ The PDE Product Editor now supports in its Updates section to specify the Name of each update repository.
+ In the assembled product the names will be presented to a user in the preferences under Available Software Sites.
+
|
+
| Removed support for unnecessary attributes in Features and Products | +
+ The Feature editor has its support for the following attributes of plugin elements removed:
+
feature.xml file.
+ They are ignored when present in an existing Feature and removed by the editor upon the next modification through the editor.
+
+ The
.product file.
+ They are ignored when present in an existing Product and removed by the editor upon the next modification through the editor.
+
+ |
+
