Team Project Set Each component should provide its own componentName.psf file in order to facilitate the way (for newcomers or external contributors) to set up a workspace with the necessary plugins fetched from CVS: File > Import/Export... and then select Team Project Set. Configuration Management (CVS or SVN) Currently, all Topcased projects utilize CVS for their source repository. There is an excellent CVS plug-in provided with the Platform SDK that has been enhanced to work with the automated build process using this tool. This section focuses on some common CVS use cases and this tool's usage in TOPCASED to facilitate our release engineering. Repository Structure The structure of TOPCASED's repository is shown below. In short, you'll likely be primarily interested in the plugins directory although anyone using anonymous pserver access can read from all of the modules. Committers using extssh can write to every module. /topcased-mf/ CVSROOT (gforge.enseeiht.fr) TOPCASED MODELING FRAMEWORK subproject /doc Project documentation
/features TOPCASED features
/plugins TOPCASED plugins
/tests TOPCASED unit tests /topcased-mm/ CVSROOT (gforge.enseeiht.fr) TOPCASED META MODELING project
/releng Build procedure scripts, update site, etc.
/maps Map files used during the build process to fetch plugins
and features from the repository
/psf Team Project Set files used to quickly set up a workspace
by fetching necessary plugins Creating a Patch It's likely the second thing you'll do with CVS is create a patch (the first was to obtain the TOPCASED sources). To do this is quite straightforward : -
When you have made the changes or additions to a plug-in, simply right-click the project (or resource) and select Team > Create Patch... -
In the wizard, select the option to "Save in the file system" and create a patch file named after the plug-in.txt (e.g. org.topcased.modeler.txt). Note: the naming convention is important to the IP tracking scripts in use by the project, as is the importance of not zipping your patch files, as the size of the file is used to indicate the size of the contribution. -
Submit the patch through the Bug Tracker. Don't send it directly to a Committer, or to the mailing list, or to the newsgroup. As described in another section of this document, the Bug Tracker is the best means by which to submit a contribution. Release Engineering -
Tagging the CVS : The CVS repository should be tagged before a release is built. Currently, this is only done manually. -
Updating the my_project.map file : there is a map file created for each project in the "topcased-mm/releng/org.topcased.releng project". The project leader must ensure that all the plugins that are part of its component are defined in the associated map file. This file is used during the build to retrieve plugins from the CVS. In order to edit these map files, you must have right access on the topcased-mm repository, if this is not the case, please join that project. -
Updating features : The project leader must also ensure that all the features into which its component is included are updated. At the moment, interesting features are located under the "topcased-mm/features" directory. -
Writing the Release Note : About one week before each official release, each project leader should communicate on the release note of its component (bugs fixed, features implemented, dependencies, ...) Commit Process Coding The items here relate to coding standards, best practices and style concerns to maintain TOPCASED code to the high standards expected from a TOPCASED project. Copyright In accordance with EPL projects, as described here (http://www.eclipse.org/legal/copyrightandlicensenotice.php), all source files need to have the appropriate copyright notice. To set this, navigate to Preferences... > Java > Code Style > Code Templates, use something similar to the following. /***********************************************************************
* Copyright (c) 2007, 2008 Anyware Technologies
*
* 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:
* Jacques Lescot (Anyware Technologies) - initial API and implementation
**********************************************************************/ Adding or Removing a Plug-in Adding a plug-in project is fairly straightforward : -
Create a project name that clearly indicates the component the plug-in is part of (runtime, codegen, map, etc.), all lower case and matching the plug-in ID. -
Stick with the default 'src' and 'bin' locations for source and binaries. -
Make sure you check 'Create an OSGi bundle manifest'. With that, if your plug-in has no extension-points defined, or contributes to another's, there is no need to maintain an empty plugin.xml file. -
The plug-in properties should contain localized Name and Provider strings, found in an accompanying plugin.properties file. Note that the Plug-in Provider name is always 'Topcased' for TOPCASED plug-ins. -
Be sure to add '.qualifier' to the end of the version number to allow for automatic generation of fully-qualified plug-ins during the build process. -
All package names (regardless of whether they are ‘internal' or not) should be listed as Exported Packages (Runtime tab of manifest.mf editor) with “visible to downstream plug-ins” visibility option. Visibility of internal packages should be set to hidden. Don't forget to list the package there as soon as it's created! -
Be sure to include your plug-in in the appropriate feature. Features are used for the automated build, so if they are not listed here, they will not be included. -
For javadoc to be run on your plug-in, add it to the buildDoc.xml file in the org.topcased.doc.sdk plug-in in the topcased-mf project. -
Add your plug-in to the appropriate map file (in org.topcased.releng/maps/your_project.map). You will find other plug-ins listed, so just use them as an example of how to create a map entry.
 -
Update the appropriate *.psf files (in org.topcased.releng/psf/your_project.map) maintained in the releng project to include your new plug-in. -
When checking in your new plug-in, be sure to specify the correct path in the CVS Team > Share Project... dialog. A plug-in will go into /org.topcased.xxx/plugins/org.topcased.my.plugin. -
Here is an example of the configuration of a new plugin : Removing a plug-in also introduces a few things to watch out for : -
Be sure to remove your plug-in from the feature(s) it is included in, and don't forget to update the Dependencies tab on the feature.xml editor. In fact, be sure to remove all traces of dependencies to your plug-in! -
Do not attempt to delete the empty folder from CVS yourself. Instead, submit a bug to the GForgeN7 component to request its removal by the webmaster. It's recommended that old plug-ins are moved to the /archive module and not deleted. Adding a Class There's not much to say about adding a class, but for completeness: -
Don't forget to export the package on the Runtime tab of the manifest editor, if you're creating a new one. -
Add the appropriate JavaDoc comments, especially for API classes and Interfaces. -
For generated classes, if modifying a method that contains a '@generated' tag, be sure to place NOT after it to prevent it from being overwritten : note that it is preferable to create @generated NOT tags, rather than removing the '@generated' tag completely. -
For generated classes, if adding a method or a new class, be sure to add @custom tag in the associated comment. It should be then used to retrieve easily the code that were customized. Packaging -
It was already mentioned that plugin.xml files that reference no extension points should be eliminated. These plug-ins will only need the OSGi MANIFEST.MF file. -
Whenever possible, favor plug-ins deployed as a single JAR. This means your plug-in as listed in a feature.xml file should contain the unpack="false" attribute value. Note that some plug-ins will need to be unpacked upon installation. -
With that, there should be no JAR listed for your plug-ins in the Classpath section of the Runtime tab in the manifest editor. There should be a single '.' entry listed in the Runtime Information section of the Build tab, with the default 'src' source folder specified (hint, you need to select the library in order for the source folder to be visible). Note that without the '.' library specified and pointing to the 'src' folder, the generated build.xml file needed during the automated build will have no compilation target. -
Be sure that your MANIFEST.MF contains no Bundle-ClassPath entry. -
Here is an exemple of a valid configuration where only needed resources are included (do not add neither the bin folder nor the src folder in the binary build) : 
Extension-Points Create your schema first when authoring a new extension-point. There is a wizard for this supplied by the PDE. It is extremely important to create proper extension-points that are well-documented. Java Compilation In Windows > Preferences... > Java > Compiler, be sure to set your options to use JDK Compliance to 1.5, with default settings below. We used 1.5 for compiler, generated .class file compatibility, and source compatibility settings. Coding Style The TOPCASED Development Resources area contains links to convention and guideline documents for coding in general, like this one. Below are just a few quick notes: -
On the topic of formatting, the standard Eclipse settings for Java code are fine. The one exception is the (anachronistic?) line length limit of 80 characters. Feel free to bump this up to something more "reasonable" (say, 200). -
A set of format settings is maintained here for you to import into your workspace from Window > Preferences > Java > Code Style > Formatter > Import... -
Package naming policies for Eclipse projects are fairly standardized. Below are some examples for TOPCASED (when in doubt, look at what's been done before): org.topcased.<component> The "root" of the plug-in namespace for TOPCASED
org.topcased.tests.<component> The "root" of the test plug-in namespace for TOPCASED
org.topcased.internal.<component> The location of non-API code (note that 'internal' comes before the component).
Debug Printout The use of System.out and System.err is to be discouraged within committed code. Rather, utilize assertions, the Platform Log, or exceptions instead. Permanent debug output should be achieved using Platform.getDebugOption() and corresponding .option files placed in the plug-in root. It's important to add descriptive comments for options you've added.
|
