Jump to: navigation, search

OCL/Dev/Setup

< OCL

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:

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

The OCL committers and contributors use the mdt-ocl.dev mailing list for discussion about

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

Bugzilla

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. The development area forms a [prefix] to each Bugzilla summary.

The project plan is partitioned into themes each of which has an associated planning item bug that depends on all bugs in the theme so that a Mylyn task for a planning bug shows a hierarchical tree of themed activity.

When a bug has a patch awaiting review, the author of a patch developed by the team or the first reviewer of a contributed patch sets their email as the QA contact so that a Mylyn task searching for open bugs with an '@' in the QA contact will identify all patches awaiting review.

The bug assignment is normally left as mdt-ocl-inbox@eclipse.org so that all committers see all bug activity.

GIT

The Engage tab of https://projects.eclipse.org/projects/modeling.mdt.ocl provides all the locations for the Eclipse OCL project.

The GIT repository is at git://git.eclipse.org/gitroot/ocl/org.eclipse.ocl.git. It contains all the code, tests and release engineering for the Eclipse OCL project. You may browse it at http://git.eclipse.org/c/ocl/org.eclipse.ocl.git. You may make contributions with Gerrit.

Recommended working practices for EGit may be found in EGit guidelines.

(The GIT repository was once at git://git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git. This should redirect to the current repository.)

CVS (Obsolete)

The CVS repository at org.eclipse.mdt/org.eclipse.ocl on :pserver:anonymous@dev.eclipse.org:/cvsroot/modeling was used up to and including the 3.1.0 (Indigo) release. From 3.1.1 onwards the source code is maintained using GIT.

Development Environment

The development environment consists of the following:

  • Eclipse SDK (latest stable milestone build)
  • EMF (latest stable milestone build)
  • EMFv just the Validation feature (latest stable milestone build)
  • UML2 (latest stable milestone build)

Classic

  • (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)

Pivot/Unified

  • MWE2 all (latest stable milestone build)
  • Xpand just the Xtend feature (latest stable milestone build)
  • Xtext (latest stable milestone build)
  • MWE2-lang all (latest stable milestone build)
  • QVTo all (latest stable milestone build)
  • ASM 3.x from Orbit e.g. 3.3.1
  • ASM 5.x from Orbit e.g. 5.0.1

Releng

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 from GIT

(If you have not already got an Eclipse installation, an easy way to create one is to first unzip a suitable Eclipse platfirm installation then use Help->Install New Software to install either a downloaded OCL Tools ZIP or to use the latest release site such as http://download.eclipse.org/releases/kepler to install at least

  • Modeling->OCL Examples and Editors

and probably

  • Collaboration->EGit
  • Modeling/EMF Examples
  • Modeling/EMF SDK (or Eclipse Modeling Framework SDK)
  • Modeling/QVT Operational SDK
  • Modeling/UML2 Extender SDK
  • Modeling/Xtext SDK

Installing OCL Examples and Editors alone will automatically pull in the minimum requirements for execution, but building and general development often requires more.)

Eclipse OCL source code is available from git://git.eclipse.org/gitroot/ocl/org.eclipse.ocl.git, http://git.eclipse.org/c/ocl/org.eclipse.ocl.git and github Network.

If you do not plan to make changes, you may clone the Eclipse repository and checkout all projects by Import...->Team->Team Project Set, then entering http://git.eclipse.org/c/ocl/org.eclipse.ocl.git/plain/releng/org.eclipse.ocl.releng/psfs/ocl-all.psf?h=master as the URL for import. Be patient; the repository clones take a while, and there are not always obvious progress indicators.

If you do plan to make changes, you are strongly recommended to use Gerrit so that your changes may be reviewed and contributed back to Eclipse more easily.

  • The master branch contains the code for the current nightly builds leading up to the next milestone and release.
  • Branches such as maintenance/R4_0 contain the code for the maintenance builds leading up to the service release of 4.0.*.
  • A branch tag such as Luna_M3 identifies the exact contributions to each milestone, release candidate and release.

The projects are partitioned into Working Sets to facilitate closing down, and perhaps deleting, what may not be of interest to you.

  • The OCL Core Working Set contains the plugins for the basic Ecore and UML support.
  • The OCL Examples Working Set contains additional examples plugins, not including the Pivot support.
  • The OCL Pivot Working Set contains the new experimental Pivot support.
  • The OCL Releng Working Set contains additioal facilities used to build and distribute Eclipse OCL.

You will probably want to suppress API Baseline errors by navigating to Window->Preferences->Plugin Development->API Baselines and setting the Missing API Baselines severity to Ignore.

If you get build errors, first make sure that you have refreshed and rebuilt your workspace, then close any projects that do not seem interesting to you. Check that you have selected Java 1.5 compliance in Window->Preferences->Java->Compiler options.

The build plugin uses facilities not imported by default, so you need to Help->Install New Software... for each of

  • Modeling/Acceleo
  • Modeling/EMF Examples
  • Modeling/EMF SDK (or Eclipse Modeling Framework SDK)
  • Modeling/QVT Operational SDK
  • Modeling/UML2 Extender SDK

There should be no build errors, and relatively few (50ish) warnings. If you have problems, refresh all and rebuild all. If the problems persist, check

  • that you have not accidentally installed an obsolete 'archive' plugin - just delete it
  • that a new plugin has not been omitted from your working set - Import it from the GIT working directory

Once there are no build errors, you may verify the installation by running for instance Run->Run Configurations... JUnit Tests org.eclipse.ocl.ecore.tests (Standalone).

Documentation builds

The documentation is generated from textile sources. You should therefore install the Mylyn Wikitext support from the prevailing releases repository and Xalan-Java and Xerces from Orbit.

The build is performed by executing the "OCL Documentation" exteral tools launch. As of October 2014 and the installation of the shell shock patches for bash, this launch no longer works on HIPP and so doumentation is built manually and committed to GIT for inclusion within subsequent Hudson builds.

Mylyn EGit/Gerrit integration

OCL project uses GIT as source code repository and Gerrit as code review facility. It's recommended for Eclipse OCL committers to use EGit and Gerrit tools. Likewise, it's also recommended to use mylyn Git/Gerrit integration to benefit from cool features that this technology provides. The following is a gathering of useful information to configure your IDE to work with these technologies.

  • Some information about how to install Mylyn/EGit integration may be found here
  • Some information about Mylyn/Gerrit integration and how to install it may be found here
Important!: At the time of writing the gerrit connector shipped in the last release (Kepler SR0) 
doesn't allow you to connect to Eclipse Gerrit server. The feature needs to be updated from 
their project repostiory : http://download.eclipse.org/mylyn/snapshots/weekly/ 
  • The Mylyn/Git integration allows you to configure a commit template, which will help you every time you need to do a new commit. Some information about how to configure them is here.
    • The template for OCL committers should looks like as follows:
[${task.key}] -

- ${task.url} 
- Bug ${task.key}
Note: Having the bugzilla URL (${task.url}) in the commit is to allow bug navigation from web based UI,
whereas the final "Bug ${task.key}" is to allow bug navigation from mylyn tasks editor.
  • Regarding Mylyn/Gerrit integration there is little documentation in their project. However, following mylyn user guider about tasks repositories should easily allow you to connect to Eclipse Gerrit server and then you should be able create queries about changes pending to review.
Note: Gerrit queries have their specific wizard to create them. An OCL committer should 
at least have the following query "Open changes by project: ocl/org.eclipse.ocl"

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 GIT location:

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).

Encoding

The use of UTF-8 rather Eclipse default file encoding is encouraged, since this is the simplest format that is common to Windows and Unix environments.

The use of Unix line endings is required since EGIT does not support content-dependent line normalization.

These preferences are set on each plugin and feature so that they are inherited by all files within each project.

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, run one of the launch configurations

  • org.eclipse.ocl.ecore.tests (Standalone) for the Ecore binding
  • org.eclipse.ocl.uml.tests (Standalone) for the UML binding
  • org.eclipse.ocl.examples.xtext.tests (standalone) for the Pivot binding

For the classic bindings the same tests may be run using the backtracking parser instead

  • org.eclipse.ocl.ecore.tests (Standalone Backtracking) for the Ecore binding
  • org.eclipse.ocl.uml.tests (Standalone Backtracking) for the UML binding

The above tests run as standalone Java applications (but with an Eclipse computed classpath). They may also be run within Eclipse together with a few additional UI exercises.

  • org.eclipse.ocl.ecore.tests (Plugin) for the Ecore binding
  • org.eclipse.ocl.uml.tests (Plugin) for the UML binding
  • org.eclipse.ocl.examples.xtext.tests (plugin) for the Pivot binding

All of the above form part of the automated builds on Hudson.

The Pivot/Xtext have limited memory which provides some detection of memory leaks. Hudson may not have the same architecture as your development machine so it may fail even if tests pass on your machine. Running

  • org.eclipse.ocl.examples.xtext.tests (standalone) (64M)

performs a more aggressive test that is more likely to fial on your machine.

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. A strict standalone test may be executed by

  • org.eclipse.ocl.ecore.tests (Standalone Classpath) for the Ecore binding
  • org.eclipse.ocl.uml.tests (Standalone Classpath) for the UML binding
  • org.eclipse.ocl.examples.xtext.tests (Standalone Classpath) for the Pivot binding

These tests variously require dependent projects to be imported into your workspace or regular updates for exact Jar filenames; these tests are therefore not run on Hudson.

The Code Generator tests are slow and so are not run on Hudson. You may run them by:

  • org.eclipse.ocl.examples.xtext.tests (CG) for the Pivot binding

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.