Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Modeling Project Releng/Plugin And Feature Files"

(Directory Structure: remove old emft styles because they are now obsolete)
(Documentation Plugin & Feature)
 
(20 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
The contents of your features and plugins directories should mimic what is available in the [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/ EMF] and [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.uml2/ UML2] projects. Although this section tries to summarize the important points, "learning by example" is the recommended approach.
 
The contents of your features and plugins directories should mimic what is available in the [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/ EMF] and [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.uml2/ UML2] projects. Although this section tries to summarize the important points, "learning by example" is the recommended approach.
  
 +
===Incubation Status===
 +
 +
New components must be tagged as "incubating", until such time as they graduate. '''This is mandatory.''' To conform to incubation rules and learn more about component graduation, see [[Modeling_Project_Releng/Building_Zips_And_Jars#Incubation_Status | Incubation Status]].
  
 
===Directory Structure===
 
===Directory Structure===
  
<span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf example]></span>
+
<span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/?root=Modeling_Project example]></span>
  
We will ask you to organize your files as we've done for [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/ EMF] and [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.uml2/ UML2]. Basically you will need to create the following directory structure for each subdirectory you own under the EMFT module:
+
We will ask you to organize your files as we've done for [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/?root=Modeling_Project EMF] and [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.uml2/?root=Modeling_Project UML2]. Basically you will need to create the following directory structure for each subdirectory you own under the EMFT module:
  
 
<table cellpadding="2" cellspacing="2" border="1"><tr><td colspan="1"><b style="color:darkred">OLD Style -- features intermixed</b></td><td colspan="1"><b style="color:darkgreen">NEW Style -- features separated</b></td></tr>
 
<table cellpadding="2" cellspacing="2" border="1"><tr><td colspan="1"><b style="color:darkred">OLD Style -- features intermixed</b></td><td colspan="1"><b style="color:darkgreen">NEW Style -- features separated</b></td></tr>
 
<tr valign="top"><td>
 
<tr valign="top"><td>
 
  /cvsroot/modeling/
 
  /cvsroot/modeling/
   org.eclipse.*/org.eclipse.*.''[subproject]''/
+
   org.eclipse.*/org.eclipse.''[subproject]''/
 
     plugins
 
     plugins
 
     doc
 
     doc
Line 21: Line 24:
 
</td><td>
 
</td><td>
 
  /cvsroot/modeling/
 
  /cvsroot/modeling/
   org.eclipse.*/org.eclipse.*.''[subproject]''/
+
   org.eclipse.*/org.eclipse.''[subproject]''/
 
     plugins
 
     plugins
 
     doc
 
     doc
Line 37: Line 40:
 
#* the features that include these plugins + the branding plugins for these features
 
#* the features that include these plugins + the branding plugins for these features
 
# tests:
 
# tests:
#* the test plugins (with the Eclipse test framework artifacts - such as  [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/tests/org.eclipse.emf.test.core/test.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup this one])
+
#* the test plugins (with the Eclipse test framework artifacts - such as  [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/tests/org.eclipse.emf.test.core/test.xml?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup this one])
 
#* the features that include these plugins + the branding plugins for these features
 
#* the features that include these plugins + the branding plugins for these features
 
# examples:
 
# examples:
Line 48: Line 51:
 
#* the doc plugins (with the build scripts)
 
#* the doc plugins (with the build scripts)
 
# tests:
 
# tests:
#* the test plugins (with the Eclipse test framework artifacts - such as  [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/tests/org.eclipse.emf.test.core/test.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup this one])
+
#* the test plugins (with the Eclipse test framework artifacts - such as  [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/tests/org.eclipse.emf.test.core/test.xml?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup this one])
 
# examples:
 
# examples:
 
#* any plugin you want to use as example
 
#* any plugin you want to use as example
Line 64: Line 67:
  
 
* Each feature and plugin directory should be also an Eclipse project, containing all the necessary files such as, for example, ''.project''.
 
* Each feature and plugin directory should be also an Eclipse project, containing all the necessary files such as, for example, ''.project''.
* The ''.project'' must only refer to builders available to the open-source community. Also, since Eclipse 3M2, it should not refer to other plugin projects. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/.project?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
* The ''.project'' must only refer to builders available to the open-source community. Also, since Eclipse 3M2, it should not refer to other plugin projects. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/.project?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
 
* We use CVS to backup the files, so...
 
* We use CVS to backup the files, so...
 
** You can, and probably should, use the ''$Id$'' CVS tag. For more details and other tags read the [http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Keyword_substitution CVS documentation]
 
** You can, and probably should, use the ''$Id$'' CVS tag. For more details and other tags read the [http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Keyword_substitution CVS documentation]
** Add a ''.cvsignore'' file to keep unnecessary files (such as the output directory) out of CVS. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/.cvsignore?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** Add a ''.cvsignore'' file to keep unnecessary files (such as the output directory) out of CVS. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/.cvsignore?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
 
* Don't add unnecessary files to your plugins and features. If you use a "non-Eclipse standard" file, please ensure that it has a purpose and that that purpose is clear.
 
* Don't add unnecessary files to your plugins and features. If you use a "non-Eclipse standard" file, please ensure that it has a purpose and that that purpose is clear.
 
* All plugins should provide the following files:
 
* All plugins should provide the following files:
** META-INF/MANIFEST.MF <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/META-INF/MANIFEST.MF?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** META-INF/MANIFEST.MF <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/META-INF/MANIFEST.MF?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
** plugin.xml <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/plugin.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** plugin.properties <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/plugin.properties?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
** plugin.properties <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/plugin.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** build.properties <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/build.properties?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
** build.properties <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/build.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** about.html <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/about.html?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
** about.html <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/about.html?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
* The ''[http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/feature_manifest.html build.properties]'' file is extremely important and must be accurate to allow PDE to build your plugins and features. Please review other components' ''[http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/feature_manifest.html build.properties]'' files for plugins with code, documentation and branding plugins, and features. To learn more about how to configure this file, [http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tasks/pde_feature_build.htm search the help system].
* The ''build.properties'' file is extremely important and must be accurate to allow PDE to build your plugins and features. Please review the EMF ''build.properties'' files for plugins with code, documentation and branding plugins, and features.
+
  
====Features <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature example]></span>====
+
====Features <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/features/org.eclipse.emf-feature/?root=Modeling_Project example]></span>====
  
 
* The PDE build process is based on features, so all your plugins must be referenced by a feature.
 
* The PDE build process is based on features, so all your plugins must be referenced by a feature.
* A feature directory can contain the definition of other features and plugins. As you can see in the [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature example], we use this to define "derived" elements, like EMF's SDK feature, source feature and source plugin.
+
* A feature directory can contain the definition of other features and plugins. As you can see in the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/features/org.eclipse.emf-feature/?root=Modeling_Project example], we use this to define "derived" elements, like EMF's SDK feature, source feature and source plugin.
* A feature's ''build.properties'' file can specify that the source plugin and feature should be generated. In EMF, this is done in the [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature/org.eclipse.emf.sdk/build.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup SDK feature's build.properties].
+
* A feature's ''build.properties'' file can specify that the source plugin and feature should be generated. In EMF, this is done in the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/features/org.eclipse.emf.sdk-feature/build.properties?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup SDK feature's build.properties].
  
 
====Qualifiers (1.0.0.qualifier)====
 
====Qualifiers (1.0.0.qualifier)====
  
* To add qualifiers to features and plugins, you must have '''4''' pieces set up correctly.<br />
+
* To add qualifiers to features and plugins, you must have '''3''' (or more) pieces set up correctly.<br />
: 1. Plugins <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm/META-INF/MANIFEST.MF example]></span>
+
: 1. Plugins <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm/META-INF/MANIFEST.MF?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
 
::* Append <tt style="color: DarkGreen">.qualifier</tt> as the 4th field of the plugin version in every <tt style="color: DarkGreen">MANIFEST.MF</tt> file. <br />
 
::* Append <tt style="color: DarkGreen">.qualifier</tt> as the 4th field of the plugin version in every <tt style="color: DarkGreen">MANIFEST.MF</tt> file. <br />
: 2. Features <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/feature.xml example]></span>
+
: 2. Features <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm-feature/feature.xml?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
 
::* Append <tt style="color: DarkGreen">.qualifier</tt> as the 4th field of the feature version in every <tt style="color: DarkGreen">feature.xml</tt> file.
 
::* Append <tt style="color: DarkGreen">.qualifier</tt> as the 4th field of the feature version in every <tt style="color: DarkGreen">feature.xml</tt> file.
 
::* Ensure that if you have comments before the <tt style="color: DarkGreen"><feature></tt> tag, they do NOT include the word "feature". If they do, <tt style="color: DarkGreen">1.0.0.qualifier</tt> will not be replaced by PDE with the build's timestamp/id. This is documented in '''[https://bugs.eclipse.org/bugs/show_bug.cgi?id=129868 bug 129868]'''.
 
::* Ensure that if you have comments before the <tt style="color: DarkGreen"><feature></tt> tag, they do NOT include the word "feature". If they do, <tt style="color: DarkGreen">1.0.0.qualifier</tt> will not be replaced by PDE with the build's timestamp/id. This is documented in '''[https://bugs.eclipse.org/bugs/show_bug.cgi?id=129868 bug 129868]'''.
 
::* Change the versions in all plugins included in <tt style="color: DarkGreen">feature.xml</tt> files to <tt style="color: DarkGreen">0.0.0</tt>. PDE will replace <tt style="color: DarkGreen">0.0.0</tt> by the appropriate version during the build. <br />
 
::* Change the versions in all plugins included in <tt style="color: DarkGreen">feature.xml</tt> files to <tt style="color: DarkGreen">0.0.0</tt>. PDE will replace <tt style="color: DarkGreen">0.0.0</tt> by the appropriate version during the build. <br />
 
: 3. Doc
 
: 3. Doc
::* Ensure that <tt style="color: DarkGreen">org.eclipse.''[subproject]''.doc/build.xml</tt> uses <tt style="color: DarkGreen">${pluginVersion}.${forceContextQualifier}</tt> instead of <tt style="color: DarkGreen">${pluginVersion}</tt> or a hard-coded version like <tt style="color: DarkGreen">1.0.0</tt>. You may need to add a new property. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build.xml example]></span>
+
::* Ensure that <tt style="color: DarkGreen">org.eclipse.''[subproject]''.doc/build.xml</tt> uses <tt style="color: DarkGreen">${pluginVersion}.${forceContextQualifier}</tt> instead of <tt style="color: DarkGreen">${pluginVersion}</tt> or a hard-coded version like <tt style="color: DarkGreen">1.0.0</tt>. You may need to add a new property. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/build.xml?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
  
 
  <property name="pluginVersion" value="1.0.0"/>
 
  <property name="pluginVersion" value="1.0.0"/>
  
::* Add these lines to the end of the <tt style="color: DarkGreen">gather.bin.parts</tt> target in <tt style="color: DarkGreen">org.eclipse.''[subproject]''.doc/build.xml</tt> (line break added in path attribute). <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build.xml example]></span>
+
::* Add these lines to the end of the <tt style="color: DarkGreen">gather.bin.parts</tt> target in <tt style="color: DarkGreen">org.eclipse.''[subproject]''.doc/build.xml</tt> (line break added in path attribute). <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/build.xml?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
  
 
  <eclipse.versionReplacer
 
  <eclipse.versionReplacer
Line 104: Line 106:
 
   version="${pluginVersion}.${forceContextQualifier}"/>
 
   version="${pluginVersion}.${forceContextQualifier}"/>
  
: 4. Releng
+
<table><tr bgcolor="#EEEEEE"><td>
::* Add the following lines to the <tt style="color: DarkGreen">create.label.properties</tt> target of <tt style="color: DarkGreen">releng/''[subproject]''/buildAll.xml</tt>. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/eodm/buildAll.xml example]></span>
+
: OPTIONAL: If you want all your features and plugins to have the SAME qualifier, eg., v200804251234, rather than qualifiers specific to the released tags in your map file(s), add the following lines to the <tt style="color: DarkGreen">create.label.properties</tt> target of <tt style="color: DarkGreen">releng/''[subproject]''/buildAll.xml</tt>. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm.releng/buildAll.xml?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
 
+
 
  <property name="forceContextQualifier" value="v${timestamp}"/>
 
  <property name="forceContextQualifier" value="v${timestamp}"/>
 
+
 
  <echo file="${buildDirectory}/label.properties" append="true" >
 
  <echo file="${buildDirectory}/label.properties" append="true" >
 
   forceContextQualifier=${forceContextQualifier}
 
   forceContextQualifier=${forceContextQualifier}
 
  </echo>
 
  </echo>
  
* OPTIONAL: If you would like your features' versions to be suffixed with a dash followed by a random string of letters and numbers, you must also add a line to your <tt style="color: DarkGreen">build.properties</tt> files. Why would you want this? It is apparently calculated from the CVS tags to ensure that the version for the features will change if the source changes in the build.<br />
+
::* See also [[Modeling_Project_Releng/Building_Zips_And_Jars#Built_features_.26_plugins_have_.22HEAD.22_in_their_version_qualifier|Built features & plugins have "HEAD" in their version qualifier]].
: 5. Releng
+
</td></tr>
::* Add <tt style="color: DarkGreen">generateFeatureVersionSuffix=true</tt> to all <tt style="color: DarkGreen">build.properties</tt> files in every <tt style="color: DarkGreen">releng/''[subproject]''/builder/</tt> directory. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/eodm/builder/sdk/build.properties example]></span>
+
<tr><td> </td></tr>
::* If available, add <tt style="color: DarkGreen">generateFeatureVersionSuffix=true</tt> to any <tt style="color: DarkGreen">build.properties.template</tt> files in <tt style="color: DarkGreen">releng/''[subproject]''/templateFiles/</tt>. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/templateFiles/build.properties.template example]></span>
+
<tr bgcolor="#EEEEEE"><td>
Tip: due to property file parser limitations in Eclipse, it is recommended that you '''''always''''' leave an empty line at the end of .properties (and .properties.template) files.
+
: OPTIONAL: If you would like your [[Modeling_Project_Releng/Building_Zips_And_Jars#Features_do_not_include_extended_suffixes|features' versions to be suffixed]] with a dash followed by a random string of letters and numbers, you must also add a line to your <tt style="color: DarkGreen">build.properties</tt> files. Why would you want this? It is apparently calculated from the CVS tags to ensure that the version for the features will change if the source changes in the build.<br />
* For more on plugin versioning, see http://www.eclipse.org/equinox/documents/plugin-versioning.html.
+
  
 +
::* Add <tt style="color: DarkGreen">generateFeatureVersionSuffix=true</tt> to all <tt style="color: DarkGreen">build.properties</tt> files in every <tt style="color: DarkGreen">releng/''[subproject]''/builder/</tt> directory. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm.releng/builder/sdk/build.properties?root=Modeling_Project&rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
 +
::* If available, add <tt style="color: DarkGreen">generateFeatureVersionSuffix=true</tt> to any <tt style="color: DarkGreen">build.properties.template</tt> files in <tt style="color: DarkGreen">releng/''[subproject]''/templateFiles/</tt>.
 +
::* '''NOTE''': due to property file parser limitations in Eclipse, it is recommended that you '''''always''''' leave an empty line at the end of .properties (and .properties.template) files.
 +
::* For more on plugin versioning, see http://www.eclipse.org/equinox/documents/plugin-versioning.html.
 +
</td></tr>
 +
</table>
  
 
===Branding Icon In About Eclipse Dialog===
 
===Branding Icon In About Eclipse Dialog===
Line 125: Line 131:
 
If you want to use the Eclipse Modeling icon in the About Eclipse dialog, you must reference it correctly in ALL your about.ini files, eg:
 
If you want to use the Eclipse Modeling icon in the About Eclipse dialog, you must reference it correctly in ALL your about.ini files, eg:
  
* [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.xsd/doc/org.eclipse.xsd.doc/about.ini org.eclipse.xsd.doc/about.ini]
+
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.xsd/doc/org.eclipse.xsd.doc/about.ini?root=Modeling_Project&rev=HEAD&view=markup org.eclipse.xsd.doc/about.ini]
* [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.xsd/plugins/org.eclipse.xsd/about.ini org.eclipse.xsd/about.ini]
+
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.xsd/plugins/org.eclipse.xsd/about.ini?root=Modeling_Project&rev=HEAD&view=markup org.eclipse.xsd/about.ini]
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.xsd/features/org.eclipse.xsd.sdk-feature/sourceTemplatePlugin/about.ini?root=Tools_Project&view=co org.eclipse.xsd.sdk-feature/sourceTemplatePlugin/about.ini]
+
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.xsd/features/org.eclipse.xsd.sdk-feature/sourceTemplatePlugin/about.ini?root=Modeling_Project&rev=HEAD&view=markup org.eclipse.xsd.sdk-feature/sourceTemplatePlugin/about.ini]
  
 
  # Property "featureImage" contains path to feature image (32x32)
 
  # Property "featureImage" contains path to feature image (32x32)
 
  featureImage=modeling32.png
 
  featureImage=modeling32.png
  
Note that the latest Eclipse Modeling icon is modeling32.png, as decided by [https://bugs.eclipse.org/bugs/show_bug.cgi?id=154906 bug 154906]. You can copy this new icon from here:  [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.query/plugins/org.eclipse.emf.query.sdk-feature/modeling32.png?revision=1.1&root=Modeling_Project modeling32.png]
+
Note that the latest Eclipse Modeling icon is modeling32.png, as decided by [https://bugs.eclipse.org/bugs/show_bug.cgi?id=154906 bug 154906]. You can copy this new icon from here:  [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.query/plugins/org.eclipse.emf.query.sdk-feature/modeling32.png?rev=HEAD&root=Modeling_Project&view=markup modeling32.png]
  
===Branding Plugin <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf example]></span>===
+
===Branding Plugin <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf/?root=Modeling_Project example]></span>===
  
 
* The "branding plugin" is the plugin that provides specific files to describe a feature - check the example to see what these files are.
 
* The "branding plugin" is the plugin that provides specific files to describe a feature - check the example to see what these files are.
Line 140: Line 146:
 
* The "branding plugin" may also contain source, so you don't need to create an additional plugin just to hold the branding files.
 
* The "branding plugin" may also contain source, so you don't need to create an additional plugin just to hold the branding files.
  
===Core Plugins & Features <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore example]></span>===
+
===Core Plugins & Features <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/?root=Modeling_Project example]></span>===
  
 
====Core Plugins====
 
====Core Plugins====
Line 149: Line 155:
 
* DO commit all generated code. This makes it easier to run your plugin from the workspace.
 
* DO commit all generated code. This makes it easier to run your plugin from the workspace.
 
* The source files should be placed in "source folders" and each "source folder" should have a different "output folder".
 
* The source files should be placed in "source folders" and each "source folder" should have a different "output folder".
* The plugins with code should be deployed as jarred plugins. In order to tip the PDE build to jar a plugin, you need to set the MANIFEST.MF's ''Bundle-ClassPath'' attribute to ''.'' and use ''.'' in the ''build.properties'' file. As an example, look at the ecore's [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/META-INF/MANIFEST.MF?rev=HEAD&content-type=text/vnd.viewcvs-markup manifest] and [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/build.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup build.properties] mentally replacing ''ecore.jar'' by ''.''.
+
* The plugins with code should be deployed as jarred plugins. In order to tip the PDE build to jar a plugin, you need to set the MANIFEST.MF's ''Bundle-ClassPath'' attribute to ''.'' and use ''.'' in the ''build.properties'' file. As an example, look at the ecore's [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/META-INF/MANIFEST.MF?rev=HEAD&content-type=text/vnd.viewcvs-markup&root=Modeling_Project manifest] and [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/build.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup&root=Modeling_Project build.properties] mentally replacing ''ecore.jar'' by ''.''.
 
Right now you are probably asking yourself why the ecore files are declaring a jar instead of using ''.''. To make a long story short, this is necessary for EMF to bootstrap itself during development (required when you use EMF to develop EMF). When developing, we can easily zip the contents of the output folder into the appropriate jar and restart Eclipse. Our build "fixes" the files before the plugins are packaged.
 
Right now you are probably asking yourself why the ecore files are declaring a jar instead of using ''.''. To make a long story short, this is necessary for EMF to bootstrap itself during development (required when you use EMF to develop EMF). When developing, we can easily zip the contents of the output folder into the appropriate jar and restart Eclipse. Our build "fixes" the files before the plugins are packaged.
Btw, to jar your plugin, you will also need to add ''unpack="false"'' to the plugin reference in your feature. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature/feature.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
Btw, to jar your plugin, you will also need to add ''unpack="false"'' to the plugin reference in your feature. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/features/org.eclipse.emf-feature/feature.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup&root=Modeling_Project example]></span>
 
* Almost all files should have a copyright. This is what is used for the Java files in EMF (please check the other types of files in the example):
 
* Almost all files should have a copyright. This is what is used for the Java files in EMF (please check the other types of files in the example):
  
Line 173: Line 179:
 
* The ''META-INF/MANIFEST.MF'' must end with an empty line. Also, don't forget to add the following line to the manifest to ensure the plugin classes are properly initialized:
 
* The ''META-INF/MANIFEST.MF'' must end with an empty line. Also, don't forget to add the following line to the manifest to ensure the plugin classes are properly initialized:
 
   
 
   
  Eclipse-LazyStart: true
+
  Bundle-ActivationPolicy: lazy
 
* The ''.classpath'' files should only contain references to the JDK and PDE container and the definition of the source and output folders.
 
* The ''.classpath'' files should only contain references to the JDK and PDE container and the definition of the source and output folders.
 
* In order to ensure that your ''plugin.properties'' files can be translated, you will need to add the following "directives" to them. All strings after a given directive are supposed to conform to its rules:
 
* In order to ensure that your ''plugin.properties'' files can be translated, you will need to add the following "directives" to them. All strings after a given directive are supposed to conform to its rules:
Line 186: Line 192:
 
| <nowiki>Strings which contain replacement variables are processed by the MessageFormat class (single quote must be coded as 2 consecutive single quotes ''). Strings which do NOT contain replacement variables are NOT processed by the MessageFormat class (single quote must be coded as 1 single quote ').</nowiki>
 
| <nowiki>Strings which contain replacement variables are processed by the MessageFormat class (single quote must be coded as 2 consecutive single quotes ''). Strings which do NOT contain replacement variables are NOT processed by the MessageFormat class (single quote must be coded as 1 single quote ').</nowiki>
 
|}
 
|}
* Add a schema for each extension point you define in your plugin. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/schema/generated_package.exsd?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
* Add a schema for each extension point you define in your plugin. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.ecore/schema/generated_package.exsd?rev=HEAD&content-type=text/vnd.viewcvs-markup&root=Modeling_Project example]></span>
  
 
====Core Features====
 
====Core Features====
 +
 +
Features are used to group functionality. This can be very simple (runtime, sdk, doc, examples, tests) or very complex (see [[EMF_2.3_New_Features_Migration_Guide | EMF]]).
 +
 +
For every group of functionality, you need a corresponding feature to collect that function, which must be in turn contributed (included) in its parent feature(s). For example, you might have a ui and a core feature, both of which are part of the runtime feature, and that runtime feature (along with doc, source, and optionally examples) needs to be included in your SDK feature. For more on how Update Manager behaves with respect to feature nesting, see [[EMF_2.3_New_Features_Migration_Guide#If_you_depend_on_features... | this page]].
  
 
''This is a stub. Contribute to this wiki by adding content here.''
 
''This is a stub. Contribute to this wiki by adding content here.''
  
 +
===Documentation Plugin & Feature ===
  
===Documentation Plugin & Feature <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/doc/org.eclipse.emf.doc example]></span>===
+
* While the PDE build is able to automatically create the Ant build script for the plugins with source code, you will need to hard code and maintain [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/doc/org.eclipse.emf.doc/?root=Modeling_Project the scripts] for the documentation plugins.
 +
::'''UPDATE:''' Instead of using a custom build.xml (by marking it as such in build.properties), you can customize a particular build step. See [[#Customizing Doc Build]].
 +
* If you don't already have a doc plugin/feature, you can use [http://dev.eclipse.org/viewcvs/index.cgi/releng-common/templates/?root=Modeling_Project these templates] as a starting point.
  
* While the PDE build is able to automatically create the Ant build script for the plugins with source code, you will need to hard code and maintain the script for the documentation plugins. The easiest way of creating the script (called ''build.xml'') is:
+
* If you already have a doc plugin/feature, here's how to quickly creating your build.xml script:
 
*# After adding all the files to the plugin directory and configuring the ''build.properties'' file, right click the ''plugin.xml'' file and select ''PDE Tools->Create Ant Build File''.
 
*# After adding all the files to the plugin directory and configuring the ''build.properties'' file, right click the ''plugin.xml'' file and select ''PDE Tools->Create Ant Build File''.
 
*# Open the ''build.xml'' file and delete the tasks in the ''gather.bin.parts''<nowiki>; target.</nowiki>
 
*# Open the ''build.xml'' file and delete the tasks in the ''gather.bin.parts''<nowiki>; target.</nowiki>
Line 202: Line 215:
 
*# Every time you start code a new release, you will need to manually update this build script. See the "[[#Release Process|Release Process]]" section for more details on new releases.
 
*# Every time you start code a new release, you will need to manually update this build script. See the "[[#Release Process|Release Process]]" section for more details on new releases.
  
====Javadoc <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/doc/org.eclipse.emf.doc example]></span>====
+
====Customizing Doc Build====
 +
 
 +
PDE Build provides a mechanism for customizing plugin build process. This allows you to perform custom actions during the build while letting PDE take care of the rest (i.e., you don't have to maintain the entire build.xml file). See [http://help.eclipse.org/ganymede/topic/org.eclipse.pde.doc.user/tasks/pde_custom_callbacks.htm Feature and Plug-in Custom Build Steps] for more information.
 +
 
 +
In order to inject custom steps into your documentation plugin's build you must provide an Ant script with the required callbacks, such as [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.mint/plugins/org.eclipse.emf.mint.doc/customBuildCallbacks.xml?root=Modeling_Project&view=markup Mint's Doc] plugin. When building the doc plugin you need to invoke an external shell scripts to build your Javadoc content. You can do this before the plugin's bin parts are gathered:
 +
<target name="pre.gather.bin.parts">
 +
    <property name="eclipseDir" location="../.."/>
 +
    <chmod perm="754" file="build/antJavadoc.sh"/>
 +
    <exec executable="bash" dir="build">
 +
      <arg line="./antJavadoc.sh ${eclipseDir}"/>
 +
    </exec>
 +
    <help.buildHelpIndex manifest="plugin.xml" destination="."/>
 +
</target>
 +
Note that the other callback targets must be defined but may remain empty.
 +
 
 +
Next, you must tell the builder that you wish to receive callbacks during the build. Add the following lines to your build.properties:
 +
customBuildCallbacks=customBuildCallbacks.xml
 +
customBuildCallbacks.failonerror=true
 +
 
 +
That's it! If you are migrating from a custom build.xml, don't forget to remove it from CVS. Also, make sure you update your build.properties (see [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.mint/plugins/org.eclipse.emf.mint.doc/build.properties?root=Modeling_Project&view=markup Mint's build.properties] for an example).
 +
 
 +
====Javadoc====
  
 
* Creating javadoc in your plugin requires a number of files &amp; folders:
 
* Creating javadoc in your plugin requires a number of files &amp; folders:
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build.xml build.xml] (including all source), or<br />[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/jet/doc/org.eclipse.jet.doc/build.xml build.xml] (excluding internal packages &amp; classes)
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/build.xml?root=Modeling_Project&rev=HEAD&view=markup build.xml] (including all source), or<br />[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.m2t/org.eclipse.jet/doc/org.eclipse.jet.doc/build.xml?root=Modeling_Project&rev=HEAD&view=markup build.xml] (excluding internal packages &amp; classes)
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/plugin.xml plugin.xml]
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/plugin.xml?root=Modeling_Project&rev=HEAD&view=markup plugin.xml]
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/toc.xml toc.xml] (table of contents)
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/toc.xml?root=Modeling_Project&rev=HEAD&view=markup toc.xml] (table of contents)
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build.properties build.properties]
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/build.properties?root=Modeling_Project&rev=HEAD&view=markup build.properties]
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build/antJavadoc.sh build/antJavadoc.sh]
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/build/antJavadoc.sh?root=Modeling_Project&rev=HEAD&view=markup build/antJavadoc.sh]
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build/javadoc.xml.template build/javadoc.xml.template]
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/build/javadoc.xml.template?root=Modeling_Project&rev=HEAD&view=markup build/javadoc.xml.template]
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build/overview.html build/overview.html]
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/build/overview.html?root=Modeling_Project&rev=HEAD&view=markup build/overview.html]
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/images/ images/] (folder, ref'd in build.xml#build.jars)
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/images/?root=Modeling_Project images/] (folder, ref'd in build.xml#build.jars)
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/references/ references/] (folder, ref'd in build.xml#build.jars)
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/references/?root=Modeling_Project references/] (folder, ref'd in build.xml#build.jars)
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/tutorials/ tutorials/] (folder, ref'd in build.xml#build.jars)
+
*# [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/tutorials/?root=Modeling_Project tutorials/] (folder, ref'd in build.xml#build.jars)
 
<br />
 
<br />
* Note that unless you have images, references, or tutorials at the time you're creating these files, you'll have to toss a placeholder into them so they won't be pruned (ignored) when extracting from CVS. A simple (blank) [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/references/.cvsignore .cvsignore] file will do nicely.
+
* Note that unless you have images, references, or tutorials at the time you're creating these files, you'll have to toss a placeholder into them so they won't be pruned (ignored) when extracting from CVS. A simple (blank) [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/doc/org.eclipse.eodm.doc/references/.cvsignore?root=Modeling_Project&rev=HEAD&view=markup .cvsignore] file will do nicely.
  
 
====Javadoc Indexed By Eclipse Help====
 
====Javadoc Indexed By Eclipse Help====
Line 222: Line 256:
 
To get Eclipse to index your javadoc in the Help system, you must revise the following files (see also [https://bugs.eclipse.org/bugs/show_bug.cgi?id=142558 bug 142558]):
 
To get Eclipse to index your javadoc in the Help system, you must revise the following files (see also [https://bugs.eclipse.org/bugs/show_bug.cgi?id=142558 bug 142558]):
  
1. Specify where extra topics_*.xml files are attached to the main table of contents entry: [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/toc.xml toc.xml]
+
1. Specify where extra topics_*.xml files are attached to the main table of contents entry: [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/doc/org.eclipse.emf.doc/toc.xml?root=Modeling_Project&rev=HEAD&view=markup toc.xml]
 
  <topic label="Reference">
 
  <topic label="Reference">
 
   <link toc="'''topics_Reference.xml'''"/>
 
   <link toc="'''topics_Reference.xml'''"/>
 
  </topic>
 
  </topic>
  
2. Specify which files to include in the doc plugin (custom build script, not PDE-generated): [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/build.xml build.xml]
+
2. Specify which files to include in the doc plugin (custom build script, not PDE-generated): [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/doc/org.eclipse.emf.doc/build.xml?root=Modeling_Project&rev=HEAD&view=markup build.xml]
 
   <target name="gather.bin.parts" depends="init" if="destination.temp.folder">
 
   <target name="gather.bin.parts" depends="init" if="destination.temp.folder">
 
     ...
 
     ...
Line 235: Line 269:
 
   </target>
 
   </target>
  
3. '''UPDATED''' Configure [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/build/javadoc.xml.template javadoc.xml.template], if required. Doclet is no longer used; instead, generation is done simply in [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/doc/org.eclipse.emf.doc/build/antJavadoc.sh?content-type=text%2Fplain antJavadoc.sh]
+
3. '''UPDATED''' Configure [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/doc/org.eclipse.emf.doc/build/javadoc.xml.template?root=Modeling_Project&rev=HEAD&view=markup javadoc.xml.template], if required. Doclet is no longer used; instead, generation is done simply in [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/doc/org.eclipse.emf.doc/build/antJavadoc.sh?root=Modeling_Project&rev=HEAD&view=markup antJavadoc.sh]
 
  <target name="javadoc" depends="extractPlatformJavadoc">
 
  <target name="javadoc" depends="extractPlatformJavadoc">
 
  ...
 
  ...
Line 244: Line 278:
 
  ...
 
  ...
  
4. Define extension points to allow extra topics_*.xml files to be seen in Eclipse Help: [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/plugin.xml plugin.xml]
+
4. Define extension points to allow extra topics_*.xml files to be seen in Eclipse Help: [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/doc/org.eclipse.emf.doc/plugin.xml?root=Modeling_Project&rev=HEAD&view=markup plugin.xml]
 
   &lt;!-- ============================= -->
 
   &lt;!-- ============================= -->
 
   &lt;!-- Define TOCs                  -->
 
   &lt;!-- Define TOCs                  -->
Line 263: Line 297:
 
===Tests Plugin & Feature===
 
===Tests Plugin & Feature===
  
''This is a stub. Contribute to this wiki by adding content here.''
+
* You need a tests plugin, eg. org.eclipse.emf.foo.tests. Example: [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.query/tests/?root=Modeling_Project emf.query.tests]
 +
* You also need a feature, eg., org.eclipse.emf.foo.tests-feature. Example: [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.query/tests/?root=Modeling_Project emf.query.tests-feature]
  
 +
Until there is a [http://dev.eclipse.org/viewcvs/index.cgi/releng-common/templates/?root=Modeling_Project test plugin/feature template], the best approach is to check out an existing working component's tests' plugin(s) and feature and clone what they have, replacing "query" in the above example with "foo", the name of your component.
 +
 +
''This is a stub. Contribute to this wiki by adding content here.''
  
 
===Examples Plugin & Feature===
 
===Examples Plugin & Feature===
  
''This is a stub. Contribute to this wiki by adding content here.''
+
* You need an examples plugin, eg. org.eclipse.emf.foo.examples. Example: [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.query/examples/?root=Modeling_Project emf.query.examples]
 +
* You also need a feature, eg., org.eclipse.emf.foo.examples-feature. Example: [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.query/examples/?root=Modeling_Project emf.query.examples-feature]
  
 +
Until there is an [http://dev.eclipse.org/viewcvs/index.cgi/releng-common/templates/?root=Modeling_Project examples plugin/feature template], the best approach is to check out an existing working component's examples' plugin(s) and feature and clone what they have, replacing "query" in the above example with "foo", the name of your component.
 +
 +
''This is a stub. Contribute to this wiki by adding content here.''
  
 
===SDK Feature===
 
===SDK Feature===
Line 276: Line 318:
  
  
===Source Plugin &amp; Feature <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature example]></span>===
+
===Source Plugin &amp; Feature <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm-feature/?root=Modeling_Project example]></span>===
  
 
* To create a source plugin and feature, you must have '''5''' pieces set up correctly.<br />
 
* To create a source plugin and feature, you must have '''5''' pieces set up correctly.<br />
: 1. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">feature.xml</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/feature.xml example]></span>
+
: 1. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">feature.xml</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm-feature/feature.xml?root=Modeling_Project&rev=HEAD&view=markup example]></span>
 
:: This will define which *src.zip files will be created - one per plugin include in the feature. If you want source for your examples, do the same in your ''[subproject]''.examples-feature.  
 
:: This will define which *src.zip files will be created - one per plugin include in the feature. If you want source for your examples, do the same in your ''[subproject]''.examples-feature.  
  
:: [update] '''NOTE:''' you must include your branding plugin (eg., org.eclipse.net4j) in your branding feature (eg., [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/net4j/plugins/org.eclipse.net4j-feature/feature.xml org.eclipse.net4j-feature/feature.xml]), even if it contains NO source, in order to properly suppress unpacking src/* in the .source plugin. Ensure that you've set that plugin to be unpack="false":
+
:: [update] '''NOTE:''' you must include your branding plugin (eg., org.eclipse.net4j) in your branding feature (eg., [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.net4j/features/org.eclipse.net4j-feature/feature.xml?root=Modeling_Project&rev=HEAD&view=markup org.eclipse.net4j-feature/feature.xml]), even if it contains NO source, in order to properly suppress unpacking src/* in the .source plugin. Ensure that you've set that plugin to be unpack="false":
  
 
  <plugin
 
  <plugin
Line 291: Line 333:
 
   '''unpack="false"'''/>
 
   '''unpack="false"'''/>
  
: 2. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">sourceTemplateFeature/*</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/sourceTemplateFeature example]></span>
+
: 2. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">sourceTemplateFeature/*</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm-feature/sourceTemplateFeature/?root=Modeling_Project example]></span>
: 3. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">sourceTemplatePlugin/*</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/sourceTemplatePlugin example]></span>
+
: 3. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">sourceTemplatePlugin/*</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm-feature/sourceTemplatePlugin/?root=Modeling_Project example]></span>
 
:: These define the contents that will go into your source feature(s) and plugin(s).
 
:: These define the contents that will go into your source feature(s) and plugin(s).
: 4. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">org.eclipse.''[subproject]''.sdk/feature.xml</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/org.eclipse.eodm.sdk/feature.xml example]></span>
+
: 4. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">org.eclipse.''[subproject]''.sdk/feature.xml</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm-feature/org.eclipse.eodm.sdk/feature.xml?root=Modeling_Project&rev=HEAD&view=markup example]></span>
 
   
 
   
 
  <includes
 
  <includes
Line 302: Line 344:
  
 
:: This connects your SDK to your .source plugins/features so that they will be included in the SDK. For more on match rules, see [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/feature_manifest.html%3Fresultof%3D%22matching%20rule%22 Matching Rules].
 
:: This connects your SDK to your .source plugins/features so that they will be included in the SDK. For more on match rules, see [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/feature_manifest.html%3Fresultof%3D%22matching%20rule%22 Matching Rules].
: 5. org.eclipse.''[subproject]''.*/<tt style="color: DarkGreen">build.properties</tt> (for '''ALL''' applicable plugins) <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm.editor/build.properties example]></span>
+
: 5. org.eclipse.''[subproject]''.*/<tt style="color: DarkGreen">build.properties</tt> (for '''ALL''' applicable plugins) <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm.editor/build.properties?root=Modeling_Project&rev=HEAD&view=markup example]></span>
  
 
<blockquote>
 
<blockquote>
Line 341: Line 383:
 
                 META-INF/
 
                 META-INF/
  
Note that <tt style="color: DarkGreen">''[Bundle-ClassPath]''</tt> is the jar name defined in the matching [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm.editor/META-INF/MANIFEST.MF MANIFEST.MF], such as:
+
Note that <tt style="color: DarkGreen">''[Bundle-ClassPath]''</tt> is the jar name defined in the matching [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.eodm/plugins/org.eclipse.eodm.editor/META-INF/MANIFEST.MF?root=Modeling_Project&rev=HEAD&view=markup MANIFEST.MF], such as:
 
   
 
   
 
  Bundle-ClassPath: eodmeditor.jar
 
  Bundle-ClassPath: eodmeditor.jar
Line 351: Line 393:
 
==== Multiple Namespaces ====
 
==== Multiple Namespaces ====
  
* If you want to contribute sources to your SDK, you must create a source plugin and feature for every feature that will contribute source. If you only have one main feature, eg, org.eclipse.emf.''[subproject]''-feature, there will be one src.zip created for every plugin listed in that feature's feature.xml. If you have more than one, as in the case with [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/transaction/plugins/ org.eclipse.emf.transaction], containing both org.eclipse.emf.transaction-feature and org.eclipse.emf.workspace-feature, each must contain its own sourceTemplateFeature and sourceTemplatePlugin. ''(???)''
+
* If you want to contribute sources to your SDK, you must create a source plugin and feature for every feature that will contribute source. If you only have one main feature, eg, org.eclipse.emf.''[subproject]''-feature, there will be one src.zip created for every plugin listed in that feature's feature.xml. If you have more than one, as in the case with [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.transaction/plugins/?root=Modeling_Project org.eclipse.emf.transaction], containing both org.eclipse.emf.transaction-feature and org.eclipse.emf.workspace-feature, each must contain its own sourceTemplateFeature and sourceTemplatePlugin. ''(???)''
  
* You can also use the generate.feature directive in your SDK's  [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/transaction/plugins/org.eclipse.emf.transaction-feature/org.eclipse.emf.transaction.sdk/build.properties build.properties], if you have source for more than one namespace. ''(???)''
+
* You can also use the generate.feature directive in your SDK's  [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.transaction/plugins/org.eclipse.emf.transaction-feature/org.eclipse.emf.transaction.sdk/build.properties?root=Modeling_Project&rev=HEAD&view=markup build.properties], if you have source for more than one namespace. ''(???)''
  
  
 
[[Category:Modeling]] [[Category:Releng]]
 
[[Category:Modeling]] [[Category:Releng]]

Latest revision as of 16:37, 25 July 2008

Plugin and Feature Files

The contents of your features and plugins directories should mimic what is available in the EMF and UML2 projects. Although this section tries to summarize the important points, "learning by example" is the recommended approach.

Incubation Status

New components must be tagged as "incubating", until such time as they graduate. This is mandatory. To conform to incubation rules and learn more about component graduation, see Incubation Status.

Directory Structure

<example>

We will ask you to organize your files as we've done for EMF and UML2. Basically you will need to create the following directory structure for each subdirectory you own under the EMFT module:

OLD Style -- features intermixedNEW Style -- features separated
/cvsroot/modeling/
  org.eclipse.*/org.eclipse.[subproject]/
    plugins
    doc
    tests
    examples

/cvsroot/modeling/
  org.eclipse.*/org.eclipse.[subproject]/
    plugins
    doc
    tests
    examples
    features
  1. plugins:
    • the plugins that provide the function
    • the features that include these plugins + the branding plugins for these features
    • the SDK feature (to generate a bundle that includes source + the plugins)
  2. doc:
    • the doc plugins (with the build scripts)
    • the features that include these plugins + the branding plugins for these features
  3. tests:
    • the test plugins (with the Eclipse test framework artifacts - such as this one)
    • the features that include these plugins + the branding plugins for these features
  4. examples:
    • any plugin you want to use as example
    • the features that include these plugins + the branding plugins for these features
  1. plugins:
    • the plugins that provide the function
  2. doc:
    • the doc plugins (with the build scripts)
  3. tests:
    • the test plugins (with the Eclipse test framework artifacts - such as this one)
  4. examples:
    • any plugin you want to use as example
  5. features:
    • the SDK feature (to generate a bundle that includes source + the plugins)
    • all main, source, test, doc, and example features

The directories containing features and fragments must be suffixed by -feature and -fragment respectively.

If you want source plugins and features, you will have to create them.

General Recommendations

  • Each feature and plugin directory should be also an Eclipse project, containing all the necessary files such as, for example, .project.
  • The .project must only refer to builders available to the open-source community. Also, since Eclipse 3M2, it should not refer to other plugin projects. <example>
  • We use CVS to backup the files, so...
    • You can, and probably should, use the $Id$ CVS tag. For more details and other tags read the CVS documentation
    • Add a .cvsignore file to keep unnecessary files (such as the output directory) out of CVS. <example>
  • Don't add unnecessary files to your plugins and features. If you use a "non-Eclipse standard" file, please ensure that it has a purpose and that that purpose is clear.
  • All plugins should provide the following files:
  • The build.properties file is extremely important and must be accurate to allow PDE to build your plugins and features. Please review other components' build.properties files for plugins with code, documentation and branding plugins, and features. To learn more about how to configure this file, search the help system.

Features <example>

  • The PDE build process is based on features, so all your plugins must be referenced by a feature.
  • A feature directory can contain the definition of other features and plugins. As you can see in the example, we use this to define "derived" elements, like EMF's SDK feature, source feature and source plugin.
  • A feature's build.properties file can specify that the source plugin and feature should be generated. In EMF, this is done in the SDK feature's build.properties.

Qualifiers (1.0.0.qualifier)

  • To add qualifiers to features and plugins, you must have 3 (or more) pieces set up correctly.
1. Plugins <example>
  • Append .qualifier as the 4th field of the plugin version in every MANIFEST.MF file.
2. Features <example>
  • Append .qualifier as the 4th field of the feature version in every feature.xml file.
  • Ensure that if you have comments before the <feature> tag, they do NOT include the word "feature". If they do, 1.0.0.qualifier will not be replaced by PDE with the build's timestamp/id. This is documented in bug 129868.
  • Change the versions in all plugins included in feature.xml files to 0.0.0. PDE will replace 0.0.0 by the appropriate version during the build.
3. Doc
  • Ensure that org.eclipse.[subproject].doc/build.xml uses ${pluginVersion}.${forceContextQualifier} instead of ${pluginVersion} or a hard-coded version like 1.0.0. You may need to add a new property. <example>
<property name="pluginVersion" value="1.0.0"/>
  • Add these lines to the end of the gather.bin.parts target in org.eclipse.[subproject].doc/build.xml (line break added in path attribute). <example>
<eclipse.versionReplacer
  path="${destination.temp.folder}/org.eclipse.[subproject].doc_\
    ${pluginVersion}.${forceContextQualifier}"
  version="${pluginVersion}.${forceContextQualifier}"/>
OPTIONAL: If you want all your features and plugins to have the SAME qualifier, eg., v200804251234, rather than qualifiers specific to the released tags in your map file(s), add the following lines to the create.label.properties target of releng/[subproject]/buildAll.xml. <example>
<property name="forceContextQualifier" value="v${timestamp}"/>

<echo file="${buildDirectory}/label.properties" append="true" >
 forceContextQualifier=${forceContextQualifier}
</echo>
OPTIONAL: If you would like your features' versions to be suffixed with a dash followed by a random string of letters and numbers, you must also add a line to your build.properties files. Why would you want this? It is apparently calculated from the CVS tags to ensure that the version for the features will change if the source changes in the build.
  • Add generateFeatureVersionSuffix=true to all build.properties files in every releng/[subproject]/builder/ directory. <example>
  • If available, add generateFeatureVersionSuffix=true to any build.properties.template files in releng/[subproject]/templateFiles/.
  • NOTE: due to property file parser limitations in Eclipse, it is recommended that you always leave an empty line at the end of .properties (and .properties.template) files.
  • For more on plugin versioning, see http://www.eclipse.org/equinox/documents/plugin-versioning.html.

Branding Icon In About Eclipse Dialog

If you want to use the Eclipse Modeling icon in the About Eclipse dialog, you must reference it correctly in ALL your about.ini files, eg:

# Property "featureImage" contains path to feature image (32x32)
featureImage=modeling32.png

Note that the latest Eclipse Modeling icon is modeling32.png, as decided by bug 154906. You can copy this new icon from here: modeling32.png

Branding Plugin <example>

  • The "branding plugin" is the plugin that provides specific files to describe a feature - check the example to see what these files are.
  • It is recommended that the branding plugin be given the same name and id as the feature it describes.
  • The "branding plugin" may also contain source, so you don't need to create an additional plugin just to hold the branding files.

Core Plugins & Features <example>

Core Plugins

For plugins with code:

  • The EMF artifacts and model specifications (XML schema, for example) should be located in a models directory in the root of the plugin. Don't forget to include the genmodel to allow users to regenerate your code.
  • DO commit all generated code. This makes it easier to run your plugin from the workspace.
  • The source files should be placed in "source folders" and each "source folder" should have a different "output folder".
  • The plugins with code should be deployed as jarred plugins. In order to tip the PDE build to jar a plugin, you need to set the MANIFEST.MF's Bundle-ClassPath attribute to . and use . in the build.properties file. As an example, look at the ecore's manifest and build.properties mentally replacing ecore.jar by ..

Right now you are probably asking yourself why the ecore files are declaring a jar instead of using .. To make a long story short, this is necessary for EMF to bootstrap itself during development (required when you use EMF to develop EMF). When developing, we can easily zip the contents of the output folder into the appropriate jar and restart Eclipse. Our build "fixes" the files before the plugins are packaged. Btw, to jar your plugin, you will also need to add unpack="false" to the plugin reference in your feature. <example>

  • Almost all files should have a copyright. This is what is used for the Java files in EMF (please check the other types of files in the example):
/**
 * <copyright>
 *
 * Copyright (c) 2005 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 - Initial API and implementation
 *
 * </copyright>
 */
  • The META-INF/MANIFEST.MF must end with an empty line. Also, don't forget to add the following line to the manifest to ensure the plugin classes are properly initialized:
Bundle-ActivationPolicy: lazy
  • The .classpath files should only contain references to the JDK and PDE container and the definition of the source and output folders.
  • In order to ensure that your plugin.properties files can be translated, you will need to add the following "directives" to them. All strings after a given directive are supposed to conform to its rules:
NLS_MESSAGEFORMAT_ALL Each string is assumed to be processed by the MessageFormat class (single quote must be coded as 2 consecutive single quotes '').
NLS_MESSAGEFORMAT_NONE All strings are assumed to NOT be processed by the MessageFormat class (single quote must be coded as 1 single quote ').
NLS_MESSAGEFORMAT_VAR Strings which contain replacement variables are processed by the MessageFormat class (single quote must be coded as 2 consecutive single quotes ''). Strings which do NOT contain replacement variables are NOT processed by the MessageFormat class (single quote must be coded as 1 single quote ').
  • Add a schema for each extension point you define in your plugin. <example>

Core Features

Features are used to group functionality. This can be very simple (runtime, sdk, doc, examples, tests) or very complex (see EMF).

For every group of functionality, you need a corresponding feature to collect that function, which must be in turn contributed (included) in its parent feature(s). For example, you might have a ui and a core feature, both of which are part of the runtime feature, and that runtime feature (along with doc, source, and optionally examples) needs to be included in your SDK feature. For more on how Update Manager behaves with respect to feature nesting, see this page.

This is a stub. Contribute to this wiki by adding content here.

Documentation Plugin & Feature

  • While the PDE build is able to automatically create the Ant build script for the plugins with source code, you will need to hard code and maintain the scripts for the documentation plugins.
UPDATE: Instead of using a custom build.xml (by marking it as such in build.properties), you can customize a particular build step. See #Customizing Doc Build.
  • If you don't already have a doc plugin/feature, you can use these templates as a starting point.
  • If you already have a doc plugin/feature, here's how to quickly creating your build.xml script:
    1. After adding all the files to the plugin directory and configuring the build.properties file, right click the plugin.xml file and select PDE Tools->Create Ant Build File.
    2. Open the build.xml file and delete the tasks in the gather.bin.parts; target.
    3. In the build.jars, use the zip ant tasks to zip up the content of the plugin - this is required since Eclipse expects the documentation files to be in an archive file.
    4. Open the build.properties editor and select the "Custom Build" check box at the top of the page
    5. Every time you start code a new release, you will need to manually update this build script. See the "Release Process" section for more details on new releases.

Customizing Doc Build

PDE Build provides a mechanism for customizing plugin build process. This allows you to perform custom actions during the build while letting PDE take care of the rest (i.e., you don't have to maintain the entire build.xml file). See Feature and Plug-in Custom Build Steps for more information.

In order to inject custom steps into your documentation plugin's build you must provide an Ant script with the required callbacks, such as Mint's Doc plugin. When building the doc plugin you need to invoke an external shell scripts to build your Javadoc content. You can do this before the plugin's bin parts are gathered:

<target name="pre.gather.bin.parts">
   <property name="eclipseDir" location="../.."/>
   <chmod perm="754" file="build/antJavadoc.sh"/>
   <exec executable="bash" dir="build">
      <arg line="./antJavadoc.sh ${eclipseDir}"/>
   </exec>
   <help.buildHelpIndex manifest="plugin.xml" destination="."/>
</target>

Note that the other callback targets must be defined but may remain empty.

Next, you must tell the builder that you wish to receive callbacks during the build. Add the following lines to your build.properties:

customBuildCallbacks=customBuildCallbacks.xml
customBuildCallbacks.failonerror=true

That's it! If you are migrating from a custom build.xml, don't forget to remove it from CVS. Also, make sure you update your build.properties (see Mint's build.properties for an example).

Javadoc


  • Note that unless you have images, references, or tutorials at the time you're creating these files, you'll have to toss a placeholder into them so they won't be pruned (ignored) when extracting from CVS. A simple (blank) .cvsignore file will do nicely.

Javadoc Indexed By Eclipse Help

To get Eclipse to index your javadoc in the Help system, you must revise the following files (see also bug 142558):

1. Specify where extra topics_*.xml files are attached to the main table of contents entry: toc.xml

<topic label="Reference">
  <link toc="topics_Reference.xml"/>
</topic>

2. Specify which files to include in the doc plugin (custom build script, not PDE-generated): build.xml

 <target name="gather.bin.parts" depends="init" if="destination.temp.folder">
   ...
   <fileset dir="${build.result.folder}" 
     includes="about.*,eclipse*.gif,eclipse*.png,eclipse*.jpg,plugin.*,toc*.xml,topics_*.xml,doc.zip,index/**,META-INF/**"/>
   ...
 </target>

3. UPDATED Configure javadoc.xml.template, if required. Doclet is no longer used; instead, generation is done simply in antJavadoc.sh

<target name="javadoc" depends="extractPlatformJavadoc">
...
<javadoc ...>
  <arg value="-J-Xmx256m"/>
  ...
</javadoc>
...

4. Define extension points to allow extra topics_*.xml files to be seen in Eclipse Help: plugin.xml

 <!-- ============================= -->
 <!-- Define TOCs                   -->
 <!-- ============================= -->

 <extension point="org.eclipse.help.toc">
   <toc file="topics_Reference.xml" />
 </extension>

 <!-- ============================= -->
 <!-- Define Javadoc locations      -->
 <!-- ============================= -->
  <extension point="org.eclipse.pde.core.javadoc">
      <javadoc path="references/javadoc"> <!-- defaults to reference/api -->
      </javadoc>
  </extension>

Tests Plugin & Feature

Until there is a test plugin/feature template, the best approach is to check out an existing working component's tests' plugin(s) and feature and clone what they have, replacing "query" in the above example with "foo", the name of your component.

This is a stub. Contribute to this wiki by adding content here.

Examples Plugin & Feature

Until there is an examples plugin/feature template, the best approach is to check out an existing working component's examples' plugin(s) and feature and clone what they have, replacing "query" in the above example with "foo", the name of your component.

This is a stub. Contribute to this wiki by adding content here.

SDK Feature

This is a stub. Contribute to this wiki by adding content here.


Source Plugin & Feature <example>

  • To create a source plugin and feature, you must have 5 pieces set up correctly.
1. org.eclipse.[subproject]-feature/feature.xml <example>
This will define which *src.zip files will be created - one per plugin include in the feature. If you want source for your examples, do the same in your [subproject].examples-feature.
[update] NOTE: you must include your branding plugin (eg., org.eclipse.net4j) in your branding feature (eg., org.eclipse.net4j-feature/feature.xml), even if it contains NO source, in order to properly suppress unpacking src/* in the .source plugin. Ensure that you've set that plugin to be unpack="false":
<plugin
  id="org.eclipse.net4j"
  download-size="0"
  install-size="0"
  version="0.0.0"
  unpack="false"/>
2. org.eclipse.[subproject]-feature/sourceTemplateFeature/* <example>
3. org.eclipse.[subproject]-feature/sourceTemplatePlugin/* <example>
These define the contents that will go into your source feature(s) and plugin(s).
4. org.eclipse.[subproject]-feature/org.eclipse.[subproject].sdk/feature.xml <example>
<includes
  id="org.eclipse.[subproject].source"
  version="1.0.0"
  match="compatible"/> 
This connects your SDK to your .source plugins/features so that they will be included in the SDK. For more on match rules, see Matching Rules.
5. org.eclipse.[subproject].*/build.properties (for ALL applicable plugins) <example>

Bundle-ClassPath With Dot

RECOMMENDED: jarred plugins w/ org/eclipse/.../*.class files

   

Bundle-ClassPath With Jar

NOT RECOMMENDED: jarred plugins with nested jars

# NLS_MESSAGEFORMAT_VAR source.. = src/ output.. = bin/

src.includes = about.html bin.includes = plugin.xml,\ plugin.properties,\ icons/,\ .,\ META-INF/

Use . instead of a jar name; repeat in MANIFEST.MF files:

Bundle-ClassPath: .

   

# NLS_MESSAGEFORMAT_VAR source.[Bundle-ClassPath] = src/ output.[Bundle-ClassPath] = bin/

src.includes = about.html bin.includes = plugin.xml,\ plugin.properties,\ icons/,\ [Bundle-ClassPath],\ META-INF/

Note that [Bundle-ClassPath] is the jar name defined in the matching MANIFEST.MF, such as:

Bundle-ClassPath: eodmeditor.jar

These define what gets packaged in the *src.zip files. You should NOT use src.includes = src/ unless you want your source plugin to include BOTH a *src.zip (containing *.java source files) and the unpacked *.java source files themselves.

Multiple Namespaces

  • If you want to contribute sources to your SDK, you must create a source plugin and feature for every feature that will contribute source. If you only have one main feature, eg, org.eclipse.emf.[subproject]-feature, there will be one src.zip created for every plugin listed in that feature's feature.xml. If you have more than one, as in the case with org.eclipse.emf.transaction, containing both org.eclipse.emf.transaction-feature and org.eclipse.emf.workspace-feature, each must contain its own sourceTemplateFeature and sourceTemplatePlugin. (???)
  • You can also use the generate.feature directive in your SDK's build.properties, if you have source for more than one namespace. (???)

Copyright © Eclipse Foundation, Inc. All Rights Reserved.