Xtext/DeveloperFAQ

[General] Main themes

Xtext is designed along the mantra "We aim to make simple things simple and complex things possible." from Alan Kay. This is not because we're fans of Alan Kay but because the sentence pretty much nails it down.

In addition to that we believe in the values defined in the Agilo Manifesto and have some Xtext project specific extensions to that:

1. We value quality over quantity (That is while we like to have lots of cool features it is more important to have the things we already have in a good shape).

[General] Team philosophy

The Xtext team works on a colaborative basis. This means that by becoming a comitter you take responsibility not only for your own code but for the whole project.

Code ownership is explicitly not desired!

You are allowed to do what ever you think is necessary to bring the project closer to the main themes. Generally, this means that it is important to get a feel for when things need to be discussed and when you can do the changes without up-front discussion. When new to the team it's best to watch how the others act in order to get that feel.

[General] What do I have to do before committing any code?

1. Synchronize and Update
2. Ensure all the tests are green. (Tests projects can be identified by their '*.tests' suffix. All tests have to be executed as plug-in unit tests.)
3. Ensure the reference documentation is up to date (i.e. reflects your changes) (Documentation is maintained in project 'org.eclipse.xtext.doc').

[General] How to do the bootstrapping

Xtext eats its own dogfood, i.e. the DSLs we use in Xtext are designed with Xtext. In order to regenerate the infrastructure for the Xtext grammar language, you need to run the generator from 'org.eclipse.xtext.bootstrap'. It uses a jared version of the Xtext runtime.

We talk of bootstrapping when you recreate the jar (there's a *.jardesc) with the latest code and then regenerate the grammar language infrastructure using that newly created jar. It's best to do this twice so that you're really sure that the code has been generated with the same code which has been generated, which has been generated, which has been generated... :-)

Of course you'll have to run all tests to validate that the bootstrapping was successful.

[UI programming] How do I get access to the model and the parse tree?

In the editor the model and parse tree is loaded and managed by an implementation of IXtextDocument which extends IDocument. It is important, that you refer to the parsed information in transactions only. Therefore the IXtextDocument defines two methods: readOnly(UnitOfWork<T>) and readWrite(UnitOfWork<T>). Usually one only wants to read the parsed information in order to compute completion proposals, build outline view, etc. To do so you have to use the API like so:

 return document.readOnly(new UnitOfWork<ICompletionProposal[]>(){
   public ICompletionProposal[] exec(XtextResource resource) throws Exception {
     // compute proposals
     return proposals;
   }
 });

It is very important that state from the passed resource is never ever returned!