Difference between revisions of "OCL/Dev/Setup"

Revision as of 03:07, 21 May 2010

The MDT development team has very little process beyond the Eclipse standard Development Process and coding guidelines. What there is is largely assisted by Eclipse tooling.

Communication Channels

The OCL committers watch and respond to the following newsgroups at news.eclipse.org:

• eclipse.modeling.mdt.ocl - the main OCL newsgroup
• eclipse.modeling.mdt.uml2 - OCL questions sometimes arise in the context of UML
• eclipse.tools.emf - and in the context of EMF/Ecore
• eclipse.modeling.mdt - general MDT discussion
• eclipse.modeling - general modeling discussion

The OCL committers subscribe to the mdt hyph ocl hyph inbox at eclipse dot org for notifications of incoming bugs and enhancement requests from the user community.

The OCL committers and contributors use the mdt hyph ocl dot dev at eclipse dot org mailing list for discussion about

• release and feature planning
• software design, models, specifications
• special events
• whatever else

The OCL committers use MDT/OCL/Dev/Areas to partition the project into different development areas and keep track of ongoing activity in each area.

Development Environment

The development environment consists of the following:

• Eclipse SDK (latest stable milestone build)
• EMF (latest stable milestone build)
• UML2 (latest stable milestone build)
• (optional) LPG 1.1 parser generator executable (Windows only; VMWare Fusion runs it very well on Mac and Wine is reported to work on Linux)
• Eclipse Releng Tools plug-in (find it at the bottom of the Eclipse Project build pages)

The API Tooling builder is enabled on all projects that have API (this excludes JUnits, Releng, Doc, and Examples).

An External Tool launch configuration is stored in the org.eclipse.ocl project to run LPG on the OCL grammar. Note that most of the work in the OCL component doesn't involve generating the grammar, so it is quite feasible to work on non-Windows platforms and without LPG. For those occasions where re-generating the parser is required, it is quite easy to transfer changes to and from a Windows system by means of patches (assuming youth you have a Windows system handy).

UTF-8 is set as the Eclipse Window->General->Workspace:Text_file_encoding in order to ensure that the Unicode characters within a few JUnit tests are consistently maintained on Windows as well as Linux systems.

Getting the Sources

To check out the OCL source projects from CVS, use Import Project Set from /www-modeling-mdt-ocl/resources/ocl.psf which is linked as "You can get the latest project source code using this Eclipse project set." on the the MDT/OCL Project Page. This project set provides the Core MDT/OCL plugins and the MDT/OCL releng plugin. The psfs folder of the releng plugin provides additional Project Set Files.

• examples.psf will add the Examples plugins
• features.psf will add the feature plugins
• parser-tools.psf will add the plugins needed to support parser regeneration
• tests.psf will add the Tests plugins
• test-tools.psf will add the plugins needed to support executing the tests
• www.psf will add the web-site and documentation plugins

Installing the Xtext development environment

The Xtext editors are regenerated by the GenerateEditors.mwe2 launch configuration in the releng project. This launch uses the ANTLr parser that is not yet in Orbit. It is therefore necessary to install it fromn the itemis site. The following Eclipse installation procedure is therefore recommended.

• Unzip Eclipse platform
• Select Install New Software from http://download.itemis.com/updates/milestones and install tmf-xtext and xtext-antlr.
• Select Install New Software from http://download.eclipse.org/releases/helios and install emf-xsd excluding the RAP plugins
• Select Install New Software from http://download.eclipse.org/releases/helios and install emf-compare
• Select Install New Software from http://download.eclipse.org/releases/helios and install mdt-uml2

[During the M and RC phases, it may be appropriate to download the relevant All-In-One Update Site Zips and use those to avoid delays in staging repository availability.]

Coding

MDT OCL follows the EMF naming conventions, which deviate from or clarify the Eclipse standard in a few points:

• interface names in plug-ins that support non-Eclipse deployment (e.g., org.eclipse.ocl, org.eclipse.ocl.uml) are not prefixed with I
• acronyms are always uppercase (e.g., OCLUMLUtil) except where names are defined by third party specifications, esp. the OMG OCL specification (e.g., OCLStandardLibrary::getOclAny())

Formatting

Code formatting conventions largely follow Sun's standard, and are quite different from EMF's (in fact, they follow the UML2 project). To a large degree, the JDT's formatter handles the details. However, one aspect does fall outside of the formatter's capability to correct:

• for/do/while loops, if statements, and similar constructs always use braces for statement blocks, even where there is only one statement

The formatter profile used by the OCL project can be imported into JDT from this CVS location:

• dev.eclipse.org:/modeling/org.eclipse.mdt/org.eclipse.ocl.releng/OCLCodeFormatting.xml

JDT Preferences

Project-level JDT preferences make this the default formatter profile for the OCL projects. It need not be the workspace default, so that it will not apply to your other projects.

Other project-level settings include:

• compiler error/warning preferences
• Java classpath based on the J2SE-1.5 execution environment
• API Tooling problem filters (varying by project) - typically applied to int constants in generated interfaces, whose values change from one generation to the next but are generally for internal use (not client use)

These settings are applied to all new projects. A convenient way to ensure consistency is to copy the JDT Core and UI preference files from the .settings/ folder. API Tooling filters are specific to the code in a project, and are not copied to new projects

For a consistent compare/merge experience across the development team, the following actions are applied to changed source files before they are checked in:

• Format
• Organize Imports
• Add missing @Deprecated annotations
• Add missing @Override annotations

Conveniently, JDT implements these functions as Save Actions, although it does not support making exceptions for certain packages (although undo after a save undoes the save actions and re-saves the file; very cool). These actions are not performed on generated code (EMF and LPG).

Modeling

The OCL metamodels are generally defined in, and generated from, UML models (using the *.uml editor from the UML2 project and, in the future, the MST project). The exception is the Ecore metamodel binding in the org.eclipse.ocl.ecore plug-in which, naturally, is modeled in Ecore.

EMF code generation options applied to the OCL models include:

• code formatting is enabled
• NON-NLS markers are enabled
• target Java version is 5.0
• currently, custom templates are used to add API tooling annotations to the generated code, to ensure API compatibility from release to release

Additionally, for the UML-defined models:

• operations classes are enabled
• pluralization of accessor methods is enabled

Testing

Occasionally, the OCL development team tests its code.  :-)

JUnit

The primary vehicle for testing is JUnit, as the OCL component has only non-UI API. As much as possible, new JUnit tests should be added to cover all Bugzilla items, but they are especially important in these circumstances:

• fixes for bugs that are regressions (we don't want another regresion of the same problem!)
• new features (enhancements scheduled on the official plan)
• fixes on the maintenance branch

To run JUnit tests:

• for most *.tests projects, execute the AllTests suite class in the lead package as a JUnit Plug-in Test. These do not need a UI (the workbench application); running headless is fine
• occasionally, it is important to run the stand-alone tests to verify that the OCL parser/interpreter still works outside of the Eclipse environment. This is required for promotion of milestone builds
  • run the External Tool launch configuration in the org.eclipse.ocl.standalone.tests project
  • test results are captured in the test-results.txt file in the same project

Manual Testing

Milestone candidate builds are additionally tested in a run-time workbench, covering:

• OCL Console example:
  • Ecore and UML metamodels
  • M2 queries and M1 constraints
  • Content-assist
  • Error reporting
• Developer Guide documentation (including verification of Javadoc content)

Build Verification Testing

Stable builds are also tested for installability by:

• unzipping the download ZIPs into the dropins/ folder. Test separately:
  • the SDK ZIP
  • the Run-time ZIP
• inspecting the contents of the stand-alone ZIP
• installing using p2 from the ZIPped up update-site
• installing using p2 from the Eclipse update site (after promotion, before contributing to the Release Train build)

Builds

Much of what you need to know about OCL builds is common to all of the Modeling projects, and is well documented on the Modeling Project Releng page.

OCL follows the "release process" in its builds. When changes are ready to be submitted to the build, the plug-ins in question are released using the Eclipse Releng Tools mentioned above. The map file is maps/ocl.map in the org.eclipse.ocl.releng project.

Currently, the OCL builds are built and staged on the emft.eclipse.org virtual server [1]. Contact an OCL committer for the username and password.

N-builds (nightly) are scheduled for weekdays at 13.00, except Tuesday. I-builds (weekly) are scheduled for Tuesdays at 16.00. S-builds (milestone) and M-builds (maintenance) are done on demand via the build web page on the the EMFT vserver. N-builds are not promoted to the Eclipse download server. R-builds (release) are typically just renames of the latest RC (release candidate) build.

The OCL project does not promote builds that have JUnit failures.