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

OCL/Dev/Setup

< OCL
Revision as of 10:04, 10 December 2012 by Ed.willink.me.uk (Talk | contribs) (→‎Getting the Sources from GIT)

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 GIT repository at git://git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git contains all the code, tests and release engineering for the Eclipse OCL project. Recommended working practices for EGit may be found in EGit guidelines.

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)
  • 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 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 alone will automatically pull in the minimum requirements for execution, but building and general development often requires more.)

Until the new null analysis facilities are incorporated into the Eclipse platform it is necessary to use Help->Install New Software... to install it from http://www.eclipse.org/jdt/core/beta-null-annotations-for-fields/4.3milestones as described in JDT Core/Null Analysis/Beta.

Eclipse OCL source code is available from git://git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git, http://git.eclipse.org/c/mdt/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://eclipse.org/modeling/mdt/ocl/resources/ocl.psf as the URL for import. Be patient; the repository clone takes a while, and there are no obvious progress indicators during the third phase while projects are actually created.

If you do plan to make changes, you are strongly recommended to create a public fork on GitHub so that your changes may be 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.*.
  • The branches are tagged to identify 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/EMF Examples
  • Modeling/EMF SDK (or Eclipse Modeling Framework SDK)
  • Modeling/QVT Operational SDK
  • Modeling/UML2 Extender SDK

(EMF Examples does not seem to be in the current Kepler distribution, so you may need to try the Juno distribution.)

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

Getting the Sources from CVS (obsolete)

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

The PSFs make overlapping contributions to working sets, so respond by clicking Merge when prompted to resolve the working set collision.

Installing the Xtext development environment (for Helios)

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.

[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.]

Installing the Xtext development environment (for Indigo)

Various aspects of the Pivot and Editor support are generated by MWE2 launch configurations in the org.eclipse.ocl.examples.build project.

  • GeneratePivotModel.mwe2 regenerates the pivot model from its UML definition.
  • GenerateAllEditors.mwe2 regenerates all four editors from their xtext definitions.
  • GenerateOCLstdlibModel.mwe2 regenerates the precompiled default OCL standard library from its oclstdlib definitions.

These launches use MWE2, MWE2-lang, Acceleo, Xtext 2.0, all of which should be part of Indigo as from M5. The unit tests additionally use EMF Compare.

Installing the Documentation development environment (for Indigo)

The documentation is generated from textile sources. You should therefore install the Mylyn Wikitext support from the Indigo releases repository. The documentation is generated by the org.eclipse.ocl.doc/textileBuild.xml script that uses XSL transformations. You should therefore install Xalan-Java and Apache Commons XML Serialiser from the org.apache category of the Orbit repository update site; e.g from http://download.eclipse.org/tools/orbit/downloads/drops/S20110523182458/repository/.

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:

  • 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.
Retrieved from "https://wiki.eclipse.org/index.php?title=OCL/Dev/Setup&oldid=324117"

Back to the top