Skip to main content
Jump to: navigation, search

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.

[General] How to run the generators

We have several samples and lots of test languages for which we need to generate infrastructure code. If you've changed the generator (org.eclipse.xtext.generator) somehow and check the generated code back in (yes, we check the generated code in, due to too big challenges in the build infrastructure).

Search the workspace for *.mwe files and you'll find one called 'GenerateAllLanguages.mwe'. Just run that workflow and all the language infrastructures will be generated. If you need a new language for unit testing, you should add it to the *.mwe file in the corresponding project.

Note that the GenerateAllLanguages uses the code in the workspace (not from the bootstrapped jar) to load the grammars and generate the code. The Xtext grammar itself is not generated. To regenerate the Xtext grammar see the previous section about bootstrapping.

[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!

Back to the top