Difference between revisions of "OCL/Dev/Setup"
(Dev setup and procedures summary)
Revision as of 22:59, 13 January 2009
The development environment consists of the following:
- Eclipse SDK (latest stable milestone build)
- EMF (latest stable milestone build)
- UML2 (latest stable milestone build)
- LPG 1.1 parser generator executable (Windows only; VMWare Fusion runs it very well on Mac)
- 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.
Getting the Sources
To check out the OCL source projects from CVS, use the psf/ocl-all.psf in the org.eclipse.ocl.releng project. The ocl-core.psf is a subset suitable for clients of the OCL API. Ensure, whenever checking in a new project, that it appears in the all-PSF and, if necessary, core-PSF. Obsolete projects should be removed from the PSFs.
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())
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:
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:
- 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).
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
Occasionally, the OCL development team tests its code. :-)
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 need 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
Milestone candidate builds are additionally tested in a run-time workbench, covering:
- OCL Console example:
- Ecore and UML metamodels
- M2 queries and M1 constraints
- 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)
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 . 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.