How to contribute to the toolset

If you plan to contibute to the Orcc toolset, you should suscribe to the mailing list of the developpers to stay tuned, and create an account to Github, in case you do not have one yet, to share your work. 

 

Setup the environment

First, download and install Eclispe Neon with the Xtext, EMF and Graphiti plugins. Then, get the source code by cloning the Orcc repository and build it using Maven:

git clone git@github.com:orcc/orcc.git

cd orcc/eclipse/plugins

mvn install 

Next, import the plugins in eclipse from the following folder:

  • <workspace>/orcc/eclipse/plugins/

To do this, click on File > Import > General > Existing projects into Workspace, then locate the directory.

Contribute to Orcc

Your development environment is now ready. You are free to contribute!

Here is some comments to make your (and our) life easier:

  • We only develop within Eclipse. Obviously the main reason is Orcc is an Eclipse plugin. And besides, Eclipse is a great IDE :-)
  • Keep in mind that Orcc is already a large software, resulting of several years of (intensive) development. To help you with its software architecture, the javadoc of the project is available here.
  • If you do not know anything about EMF, perhaps you should start with this tutorial.
  • We use Git as a version control system. Everything you have to know about Git is summary in the  Pro Git book, written by Scott Chacon and available here.
  • Commit often and incrementally: Because we are a small team, it is easier for us to review small pieces of code committed incrementally rather than having entire packages dropped at once. Think "commit early, commit often" (inspired by Linus's "release early, release often"). Note that the code is not required to work yet, but it must compile.

At the beginning of your involvment in the development of Orcc, you may not be an official developper and, consequently, you may not have the permission to push your contributions directly to the repository. So, when you feel ready to merge your work with the main branch, ask for a pull request and we will consider it.

Coding standards

If you would like to contribute to Orcc, here are the coding standards we are using. These coding standards are based on the Code Conventions for the Java(TM) Programming Language by Sun, therefore we recommend that you read them, and then continue reading this document.

Naming conventions

  • All names but constants follow the camelCaseConvention.
  • Please only use ASCII characters for names, because accentuated characters are not handled so well on some platforms.
  • A getter of a field `fff` is named `isFff` when the field is boolean, otherwise it is named `getFff`.
  • A setter of a field `fff` is named `setFff`.
  • Class names begin with an uppercase letter
  • Constants ARE_NAMED_LIKE_THIS.
  • All non-public methods must be '''private''' by default, the reason for doing otherwise must be stated explicitly in the Javadoc.
  • All non-public attributes must be '''private''' by default, the reason for doing otherwise must be stated explicitly in the Javadoc.

Source code formatting

  • Use the Source Format feature in Eclipse. Right-click (in the editor or on a Java source file) > Source > Format.
  • Use the Organize Imports feature in Eclipse. Right-click (in the editor or on a Java source file) > Source > Organize Imports.
  • Use the Sort Members feature in Eclipse. Right-click (in the editor or on a Java source file) > Source > Sort Members.

Comment formatting

  • Before package declaration, put the copyright statement (copy/paste from another file). Replace IETR/INSA Rennes by your organization. Add yourself to the list of @author directives.
  • Write Javadoc comments for classes, methods, and attributes.
  • Within methods, write single-line comments where necessary (e.g. tricky pieces of code). Single-line comments must start with //

Compiling

  • Code compliance is Java 7.
  • No warnings. Warnings are potential errors, please pay attention to them!

Use interfaces

  • Use interface type rather than implementation type when declaring an object. In particular, declare lists and maps as List and Map rather than the particular implementation used (e.g. ArrayList, LinkedHashMap). This helps having an implementation-independent code.

Exceptions

  • Throw OrccException when an exception is likely to happen.
  • When an exception is unexpected and you do not want to have to declare "throws OrccException" everywhere (e.g. in visitors), use OrccRuntimeException.

Other rules

  • Always put braces. Always.
  • No unnessary newlines in functions.

As an example, the following functions should not be written like this:

public void f()
{
	System.out.println();
}
	
public void g()
{
	if (...)
		System.out.println();
}

but should be written as follows:

public void f() {
	System.out.println();
}
	
public void g() {
	if (...) {
		System.out.println();
	}
}

 

Notes

  • If you are behind a proxy you must edit the Run configuration of the MWE2 Workflow by adding -Dhttp.proxyHost=<server> -Dhttp.proxyPort=<port> to the VM arguments.
  • If you get an OutOfMemoryError, add -Xmx1024m to the VM arguments of the Run Configuration. In some case, you may also add -XX:MaxPermSize=256m to prevent PermSize OutOfMemoryError.

Quick install

Install Orcc from the update site http://orcc.sf.net/eclipse/
More information

Contact

Whether you need (or want to offer) help or advice, or if you just want to discuss/chat about Orcc, feel free to contact us!

Most of the team is based in Europe, so you might expect people to be connected and answer mail during the day (GMT+1).


This website is hosted by Get Open RVC-CAL Compiler at SourceForge.net