Git Repository Layout
The source code will be in a single Git repository, organized in the following directories:
- plugins: source code for all the plug-ins of EATOP itself;
- doc: the documentation plug-ins;
- examples: example EATOP modelers and sample metamodel definitions used by the examples and/or the tests. Furthermore the sources for a graphical EAST-ADL editor are here;
- tests: automated tests (JUnit);
- features: feature definitions (including doc, examples and test features);
- releng: parent project (for the root POM and shared files), update-sites definitions;
- tools: target platform definitions and source code for development tools that contributors must install in their development environment. These are not part of EATOP but are required to develop EATOP.
General Rules About Code Organization
The general criteria used to define the plug-ins boundaries are:
- Core vs Eclipse-specific vs UI
- Core code is pure library code with no dependency on any runtime framework (or maybe juste OSGi), and can be run headless and outside of an Eclipse runtime;
- Eclipse-Specific code depends on the Eclipse framework, but not on the UI; it can still be run headless;
- UI code requires a complete Eclipse Workbench (and provides the integration inside of it).
- API vs internal API vs SPI vs internal (this is more for package boundaries than plug-in boundaries)
- API is the official API that can be used by non-EATOP code;
- internal API is technically API (i.e. exported by the OSGi bundles) but reserved for internal usages inside of EATOP itself. It can be used by non-EATOP code but it does not have the same kind of guarantees in terms of backward compatibility;
- SPI (Service Provider Interface) is specifically targeted for systems which want to extend EATOP. This typically includes extension points and interface definitions that extender must implement. These may be used by EATOP itself, for example to provide default implementations.
- internal is all the rest, and is not accessible outside of EATOP.
Note that these criteria should not dictate the final architecture, but simply allow a better control and understanding of the dependencies. Simply creating a bundle for each combination of these criterion and put each existing piece of code in the correct plug-in bucket would not result in any kind of meaningful architecture. However, the existing code base is more or less organized along such semi-technical boundaries and a good first step would be to ensure this structure is actually correctly enforced (this is not the case currently).
In addition to other Eclipse projects, EATOP depends on the following:
- Java-SE 1.7.
- OSGi R4. Note that 99.9% of the code should be independent on OSGi APIs, but the plug-ins should be well-behaved OSGi bundles and some APIs will probably be exposed as OSGi service.
And for the automated tests:
- JUnit 4 (the latest version included in Eclipse).
The code for automated tests will be isolated in separate plug-ins, one or two for each EATOP plug-in. For example, say we have a EATOP plug-in named org.eclipse.eatop.serialization. Its automated JUnit tests would be in org.eclipse.eatop.serialization.tests.
- Test plug-ins can share common code (custom asserts, setup helpers etc.) in plug-ins named org.eclipse.eatop.testutil.
- A test plug-in can depend on:
- the plug-in it tests (obviously);
- JUnit, EasyMock and/or SWTbot;
- any test support plug-in which does not add another dependency;
- the dependencies of the plug-in it tests and their own test plug-ins;
- example projects (in the examples directory of the Git repo) or even external projects like UML for its test fixtures.
Note: There may be limitations in the way Maven/Surefire/Tycho handle unit and integration tests which impact the way we organize test code.
New Plug-in Check List
- appropriate copyright headers based on EATOP copyright headers in Java source files, plugin.properties and plugin.xml.
- no invalid UI dependencies. The non-UI plug-in does not depend on any UI plug-ins.
- no imported packages. The required plug-ins are preferred than imported packages.
- Java package name prefix equals plug-in name.
- plug-in name/provider exported to plugin.properties.
- plug-in provider is "Eclipse EATOP".
- appropriate plug-in versions. The current version is "0.5.0.qualifier".
- presence of required legal files in plug-ins (about.html) and correctly checked build.properties.
- Java 7 as minimum Java execution environment.
- update of project settings.
- appropriate EMF/EMF UI activator classes in internal package. The activator class is located in "internal" package. The actual implementation of UI activator extends EclipseUIPlugin, while that of the non-UI activator extends EclipsePlugin.
- elimination of compiler warnings as far as possible, e.g., add missing @override annotations, externalize the strings, etc.
New Feature Check List
- presence of license feature. The feature shares the license feature org.eclipse.eatop.license.
- feature name/provider/description exported to feature.properties.
- feature provider is "Eclipse EATOP".
- appropriate feature versions. The current version is "0.5.0.qualifier".
- presence of required legal files in features (license.html and epl-v10.html) and correctly checked build.properties.