Developers Guide

Project Organization

Code Conventions

Except for the cases enumerated below, the Java source code should follow Google’s Style Guide: https://google.github.io/styleguide/javaguide.html

Method Names

Part of the source code is meant to be specialized by automatically generated code. To avoid naming conflicts, classes that belong to the emf.ecore hierarchy should avoid standard Getter and Setter names.

For instance, access methods for a field named foo should be:

String foo();          // The Getter
void foo(String str);  // The Setter

Access methods from other classes should use standard names.

Each class must manage its own fields. Except for special cases, getters and setters must not return a mutable collection.

Preconditions

Use preconditions instead of assertions or comments for checking conditions that must always be true and invariants in method bodies.

public void foo(int i) {
  Preconditions.checkArgument(i > 0 && i <= 12, "Out of range");
  // Method code
}

Annotations (JSR-305)

Use JSR-305 annotations, such as @Nonnull, @Nullable, @ParametersAreNonnullByDefault, etc. These annotations are not processed at runtime, but are very useful for static code analysis.

Documentation

Every package, classes, method, and field should be properly documented.

The package documentation is located in main/javadoc, next to the main/java directory, and must only contain package-info.java files.

Software Quality

Ideally, all methods should be tested in unit tests. For classes and methods related to data management, tests must also be created in the integration tests.

Design Tips

Supertypes should not depend on subtypes.

More precisely, an interface should not reference its implementation classes. For instance, the following code excerpt should be avoided:

public interface IFactory {
  IFactory eINSTANCE = FactoryImpl.init();
}

How to Contribute

We are constantly looking to improve NeoEMF, and we are happy to receive any contribution that solves a bug, provides a new feature, or improves existing code base. This page summarizes the different solutions you have to help us.

Report Issues

NeoEMF is bundled with a test suite based on our usage experience and the issues we have solved in the past. We are using and testing it every day to improve the quality of the framework. However, we cannot spot all the bugs, or test all the possible application scenarios.

If you experience any trouble when installing or using NeoEMF you can open an issue on the Issue Tracker. Please make sure that a similar issue is not already opened.

You can alternatively contact us directly through our mailing list neoemf@googlegroups.com">neoemf@googlegroups.com.

Contribute to the Code

You have created your own backend implementation or a new fancy feature that should be integrated in NeoEMF? You can submit it in a pull request! In order to facilitate related discussions and speed-up the merge of your pull request make sure to observe the following rules:

  • Create one pull request per feature: it is way easier for us to integrate relatively small pull requests containing a single feature. For example, a pull request can contain code for a new backend or a fix for a bug or a family of related bugs.

  • Provide a description of the changes in your pull request: this will help us to understand and check your code efficiently. This description may be partially reused in NeoEMF changelog for the next release of the tool.

  • Follow the package and class naming conventions: we have a wiki page referencing the package and class naming conventions we use in the project. You can of course replace the package prefix fr.inria.atlanmod with the one of your institution/company.

  • Any question? Contact us! If you have any question regarding the contribution process, or if you want additional information for you pull request please contact us at neoemf@googlegroups.com">neoemf@googlegroups.com.

Discuss with us!

We are always happy to hear about you and how you are using NeoEMF! This helps us to spot the weak points of the framework, and decide which feature should be prioritized in the future. If you want to report your user experience with the tool or discuss about possible collaborations please contact us neoemf@ogooglegroups.com">by email or using our twitter account.

Build

This page details the different steps required to build locally NeoEMF. When built and installed in your local maven repository, you can import it in your project using the following maven dependency:

<dependency>
  <groupId>org.atlanmod.neoemf</groupId>
  <artifactId>neoemf-core</artifactId>
  <version>latest</version>
</dependency>

<dependency>
  <groupId>org.atlanmod.neoemf</groupId>
  <artifactId>neoemf-io</artifactId>
  <version>latest</version>
</dependency>

Alternatively, the local build embeds a zipped update site in the plugins/fr.inria.atlanmod.neoemf.eclipse.update/1.0.2-SNAPSHOT folder you can install in your Eclipse application.

Build with Maven

You can download the source code of the latest release here or clone the master branch using the following git command:

git clone -b master --single-branch  https://github.com/atlanmod/NeoEMF.git

Configure Maven’s JDK to allocate more memory:

export MAVEN_OPTS="-XX:PermSize=256m -XX:MaxPermSize=512m -XstartOnFirstThread"

Build Core Components

NeoEMF core components are bundled as a set of Jar files that can be imported using the maven dependency mechanism. You can build NeoEMF core components by going to the root of the source directory and run the following command:

mvn clean install

(optional) You can also run the tests by using :

mvn test (-pl <neoemf-core|neoemf-data|neoemf-io|...>)

Note that building the core components does not create Eclipse plugins and an local version of the update site. To generate these additional artifacts see the next section.

Build Eclipse Integration Plugins

NeoEMF Eclipse integration plugins provide Eclipse compatible plugins and update site. To build these artifacts, you need to run the following command:

mvn clean install -f plugins/eclipse

NeoEMF plugins and update-site are built and stored in your local workspace at ./plugins/eclipse/releng/update/target/fr.inria.atlanmod.neoemf.eclipse.update-2.1.0-SNAPSHOT.zip.

Build in Eclipse

You can alternatively build NeoEMF directly in Eclipse using the Eclipse Git and Maven integrations plugin.

Requirements

In order to import NeoEMF Git repository in Eclipse, you will need the following plugins in your installation (installable from the software repository of your Eclipse release):

  • EGit : v3.4.2 or later

  • m2e : v1.5.1 or later

And the following m2e connectors (installable through Preferences → Maven → Discovery / m2e Marketplace):

  • Maven SCM Handler for EGit (m2e-egit) : v0.14 or later

  • Tycho Project Configurators (Tycho configurator) : v0.8.0 or later

Note that additional m2e connectors can be required denpending of your specific installation. They can be installed using Eclipse quick fixes available in the pom files.

Import and Build

  • Import the project using File → Import → Maven → Check out Maven Projects from SCM

  • Select "git" in the SCM URL field and paste the repository address (https://github.com/atlanmod/NeoEMF.git)

  • Choose your workspace and working sets setting and finish

The projects project, parent, core, graph, graph.blueprints and map will be imported and built.

If you want to import the projects generating Eclipse specific plugins (features, update-site), you have to import them by hand using File → Import → Maven → Existing Maven Projects, and select the projects under the "plugins" folder in your local repository.

Note that building NeoEMF in Eclipse can take a long time (and a large disk space) because the default SCM connector fetches all the branches of the remote git repository.

Issues

If you experience issues installing or using NeoEMF, you can submit an issue on GitHub or contact us at neoemf@googlegroups.com

Known issues:

  • Only Luna plugins are fetched (the compatibility is not ensured for previous Eclipse versions)

  • The Eclipse plugins can not be built if Maven can not access thr Internet (it is needed to fetch Luna p2 repositories)

  • Sometimes the plugin build crashes and/or freezes during p2 index fetching from Luna repositories. It is generally sufficient to cancel the build (ctrl-c) and to relaunch it.