|
|
| (24 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| − | This document is directed to the '''[[Eclipse Modeling Framework Technologies]]''' ('''EMFT''') [http://www.eclipse.org/modeling/emft/] component owners and was created help them to set up and run their builds. It describes the existing procedures that all EMFT components are required to adopt, describing, for example, how the files should be organized, what the build files are, and the Integration and Milestone release process. | + | This document is directed at [[Modeling Project]] component leads, including those in [[EMF]], [[EMFT]], [[M2M]], [[M2T]] & [[MDT]]. This system has also been used for [[GEF]] and [[TM_and_RSE_FAQ|DSDP-TM-RSE]], and with a little effort, can be used for other non-Modeling projects and components. |
| | | | |
| − | Note that many of the tips and tricks described herein apply to EMF, MDT, and M2T builds as well.
| + | It describes the existing procedures that components are required to adopt, describing, for example, how the files should be organized, what the build files are, and the Integration and Milestone release process. |
| | | | |
| − | Throughout this document are references to releng (Release Engineering) files which need to be configured along the way. When a project is first starting, these steps are normally skipped until after all the plugin content is in CVS. Then, and only then, the [[Modeling Project Releng Module]] can be created for the new project, and builds can begin. | + | Throughout this document are references to releng (Release Engineering) files which need to be configured along the way. When a project is first [[Modeling_Project_Releng/Component_Creation | being created]], these steps are normally not started until after all the plugin content is in CVS. Then, and only then, the [[Modeling Project Releng/Releng Module | Releng Module]] can be created for the new project, and builds can begin. |
| | | | |
| | + | <blockquote> |
| | | | |
| − | ---- | + | * Creation |
| | + | :1. [[Modeling_Project_Releng/Component_Creation | Component Creation]] -- includes workflow and TODOs by assignee |
| | + | :2. [[Modeling_Project_Releng/Website_Maintenance | Website Maintenance]] -- includes how to control web content and [[Modeling_Project_Releng/Component_Creation/Build_Server_Setup|add users]] |
| | + | :3. [[Development_Resources/Project_Plan/Modeling_Project|Project Plan]] -- includes how to create your plan.xml and set up Bugzilla queries |
| | | | |
| | + | *Setup |
| | + | :4. [[Modeling Project Releng/Releng Module | Releng Module]] -- how to get started working with PDE's releng.basebuilder |
| | + | :5. [[Modeling Project Releng/Plugin And Feature Files | Plugin And Feature Files]] -- includes structure & layout for your plugin/feature files |
| | + | :6. [[Modeling Project Releng/Building Zips And Jars | Building Zips And Jars]] -- includes Incubation status, 3rd party jars, compiler settings, [[Modeling_Project_Releng/Building_Zips_And_Jars#Built_features_.26_plugins_have_.22HEAD.22_in_their_version_qualifier|tagging & releasing code]], [[Modeling_Project_Releng/Plugin Version Auditing|plugin version auditing]] and build/test troubleshooting |
| | | | |
| − | <blockquote>
| + | *Publication |
| − | '''''Overwhelmed yet?'''''
| + | :7. [[Modeling Project Releng/Releasing | Releasing]] -- schedules, reviews, promoting builds, and generating project meta-information (release notes, RSS feeds, newsgroup announcements) |
| − | | + | :8. [[Modeling Project Releng/Maintenance | Maintenance]] -- cleanup tips |
| − | | + | :9. [[Modeling Project Releng/Branching | Branching]] -- how to branch |
| − | Well, you're in luck. As of 2006-07-12, there is a new module template which can be used as a starting point. For more on creating and configuring a Modeling Project Releng Module, see [[Modeling Project Releng Module]]. Go there, start with that, then come back here for tips and tricks if necessary.
| + | |
| | </blockquote> | | </blockquote> |
| | | | |
| | + | ===See Also=== |
| | | | |
| − | ----
| + | * [[Modeling_Project_Releng/Cheat_Sheet|Modeling Project Releng Cheat Sheet]] -- quick reference guide for running and promoting builds by hand and by schedule |
| − | | + | * [[Modeling Project Releng Plan]] -- what's the plan? |
| − | | + | * [https://bugs.eclipse.org/bugs/buglist.cgi?product=Modeling&component=Releng&component=Website&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&order=bugs.bug_status,bugs.target_milestone,bugs.bug_id&query_format=advanced Open Modeling Project Releng Bugs / RFEs] |
| − | This is a live document! We will be enriching it as questions are raised.
| + | * Server configuration for [[EMF_Build_Server_Setup|emf.torolab]] & [[EMFT_Build_Server_Setup|emft.eclipse]] |
| − | | + | * [[Platform-releng-faq|Platform Releng FAQ]] |
| − | ==Plugin and Feature Files==
| + | * [[:Category:Releng]] |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | | + | |
| − | ===Directory Structure===
| + | |
| − | | + | |
| − | <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf 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:
| + | |
| − | | + | |
| − | <table cellpadding="2" cellspacing="2" border="1"><tr><td colspan="3"><b style="color:darkred">OLD Style -- features intermixed</b></td><td colspan="3"><b style="color:darkgreen">NEW Style -- features separated</b></td></tr>
| + | |
| − | <tr valign="top"><td>
| + | |
| − | Old EMFT project (/cvsroot/technology)
| + | |
| − | emft/''[subproject]''/
| + | |
| − | plugins
| + | |
| − | doc
| + | |
| − | tests
| + | |
| − | examples
| + | |
| − |
| + | |
| − | </td><td><br/><br/> - or -
| + | |
| − | </td><td>
| + | |
| − | New EMFT project (/cvsroot/modeling/)
| + | |
| − | org.eclipse.*/org.eclipse.*.''[subproject]''/
| + | |
| − | plugins
| + | |
| − | doc
| + | |
| − | tests
| + | |
| − | examples
| + | |
| − |
| + | |
| − | </td><td>
| + | |
| − | Old EMFT project (/cvsroot/technology)
| + | |
| − | emft/''[subproject]''/
| + | |
| − | plugins
| + | |
| − | doc
| + | |
| − | tests
| + | |
| − | examples
| + | |
| − | features
| + | |
| − | </td><td><br/><br/> - or -
| + | |
| − | </td><td>
| + | |
| − | New EMFT project (/cvsroot/modeling/)
| + | |
| − | org.eclipse.*/org.eclipse.*.''[subproject]''/
| + | |
| − | plugins
| + | |
| − | doc
| + | |
| − | tests
| + | |
| − | examples
| + | |
| − | features
| + | |
| − | </td></tr>
| + | |
| − | <tr valign="top"><td colspan="3">
| + | |
| − | # 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)
| + | |
| − | # doc:
| + | |
| − | #* the doc plugins (with the build scripts)
| + | |
| − | #* the features that include these plugins + the branding plugins for these features
| + | |
| − | # 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 features that include these plugins + the branding plugins for these features
| + | |
| − | # examples:
| + | |
| − | #* any plugin you want to use as example
| + | |
| − | #* the features that include these plugins + the branding plugins for these features
| + | |
| − | </td><td colspan="3">
| + | |
| − | # plugins:
| + | |
| − | #* the plugins that provide the function
| + | |
| − | # doc:
| + | |
| − | #* the doc plugins (with the build scripts)
| + | |
| − | # 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])
| + | |
| − | # examples:
| + | |
| − | #* any plugin you want to use as example
| + | |
| − | # features:
| + | |
| − | #* the SDK feature (to generate a bundle that includes source + the plugins)
| + | |
| − | #* all main, source, test, doc, and example features
| + | |
| − | | + | |
| − | </td></tr></table>
| + | |
| − | | + | |
| − | 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 [[#Source Plugin & Feature <example>|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. <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>
| + | |
| − | * 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]
| + | |
| − | ** 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>
| + | |
| − | * 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:
| + | |
| − | ** 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>
| + | |
| − | ** 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/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/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/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/about.html?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
| + | |
| − | * 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>====
| + | |
| − | | + | |
| − | * 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'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].
| + | |
| − | | + | |
| − | ====Qualifiers (1.0.0.qualifier)====
| + | |
| − | | + | |
| − | * To add qualifiers to features and plugins, you must have '''4''' 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>
| + | |
| − | ::* 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>
| + | |
| − | ::* 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]'''.
| + | |
| − | ::* 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
| + | |
| − | ::* 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>
| + | |
| − | | + | |
| − | <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>
| + | |
| − | | + | |
| − | <eclipse.versionReplacer
| + | |
| − | path="${destination.temp.folder}/org.eclipse.''[subproject]''.doc_\
| + | |
| − | ${pluginVersion}.${forceContextQualifier}"
| + | |
| − | version="${pluginVersion}.${forceContextQualifier}"/>
| + | |
| − | | + | |
| − | : 4. Releng
| + | |
| − | ::* 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>
| + | |
| − | | + | |
| − | <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 <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 />
| + | |
| − | : 5. Releng
| + | |
| − | ::* 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>
| + | |
| − | ::* 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>
| + | |
| − | 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.
| + | |
| − | * 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:
| + | |
| − | | + | |
| − | * [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/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.xsd/features/org.eclipse.xsd.sdk-feature/sourceTemplatePlugin/about.ini?root=Tools_Project&view=co org.eclipse.xsd.sdk-feature/sourceTemplatePlugin/about.ini]
| + | |
| − | | + | |
| − | # Property "featureImage" contains path to feature image (32x32)
| + | |
| − | 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]
| + | |
| − | | + | |
| − | ===Branding Plugin <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf 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.
| + | |
| − | * 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 <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore example]></span>===
| + | |
| − | | + | |
| − | ====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 [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 ''.''.
| + | |
| − | 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>
| + | |
| − | * 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):
| + | |
| − | | + | |
| − | <pre>
| + | |
| − | /**
| + | |
| − | * <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>
| + | |
| − | */
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | * 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
| + | |
| − | * 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:
| + | |
| − | {| cellpadding="2" border="1" style="border: 1px black"
| + | |
| − | | valign="top" | <tt style="color: DarkGreen">NLS_MESSAGEFORMAT_ALL</tt>
| + | |
| − | | <nowiki>Each string is assumed to be processed by the MessageFormat class (single quote must be coded as 2 consecutive single quotes '').</nowiki>
| + | |
| − | |-
| + | |
| − | | valign="top" | <tt style="color: DarkGreen">NLS_MESSAGEFORMAT_NONE</tt>
| + | |
| − | | All strings are assumed to NOT be processed by the MessageFormat class (single quote must be coded as 1 single quote ').
| + | |
| − | |-
| + | |
| − | | valign="top" | <tt style="color: DarkGreen">NLS_MESSAGEFORMAT_VAR</tt>
| + | |
| − | | <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>
| + | |
| − | | + | |
| − | ====Core Features====
| + | |
| − | | + | |
| − | ''This is a stub. Contribute to this wiki by adding content here.''
| + | |
| − | | + | |
| − | | + | |
| − | ===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 the script for the documentation plugins. The easiest way of creating the script (called ''build.xml'') is: | + | |
| − | *# 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>
| + | |
| − | *# 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.
| + | |
| − | *# Open the ''build.properties'' editor and select the "Custom Build" check box at the top of the page
| + | |
| − | *# 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>====
| + | |
| − | | + | |
| − | * Creating javadoc in your plugin requires a number of files & 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 & 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/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/toc.xml 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/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build/antJavadoc.sh 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/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build/overview.html 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/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/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/tutorials/ tutorials/] (folder, ref'd in build.xml#build.jars)
| + | |
| − | <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.
| + | |
| − | | + | |
| − | ====Javadoc Indexed By Eclipse Help====
| + | |
| − | | + | |
| − | 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]
| + | |
| − | <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): [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/build.xml 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 [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]
| + | |
| − | <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: [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/plugin.xml 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===
| + | |
| − | | + | |
| − | ''This is a stub. Contribute to this wiki by adding content here.''
| + | |
| − | | + | |
| − | | + | |
| − | ===Examples Plugin & Feature===
| + | |
| − | | + | |
| − | ''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.''
| + | [[Category:Modeling]] [[Category:Releng]] |
It describes the existing procedures that components are required to adopt, describing, for example, how the files should be organized, what the build files are, and the Integration and Milestone release process.
Throughout this document are references to releng (Release Engineering) files which need to be configured along the way. When a project is first being created, these steps are normally not started until after all the plugin content is in CVS. Then, and only then, the Releng Module can be created for the new project, and builds can begin.
