-
Notifications
You must be signed in to change notification settings - Fork 7
Getting started as a contributor
Welcome, we aim here to give a good guide to getting started as a developer on Eclipse Free BIRD Tools.
Feedback is always welcome! please post questions or feedback on the forum for Eclipse Free BIRD Tools at https://www.eclipse.org/forums/index.php/f/518/
Eclipse Free BIRD Tool is written in 2 parts, a Java part and a Python part.
Depending upon what you would like to do with Eclipse Free BIRD Tools you might use only the Python part or the Java part or both.
The Python part does all the translation from the official BIRD artefacts into the RegDNA model and then the RegDNA language. The Python code makes heavy use of the open source PyEcore library to convert from the SMCubes Information Model representation of BIRD artefacts into the RegDNA representation . Extracts from the official ECB BIRD website follow the SMCubes information model.
The Java part provides a domain specific language for RegDNA using the open source XText technology, and provides an Xtext Generator (written with Xtend templates ) which converts RegDNA to Xcore (and in future will convert to Python Django and other frameworks).
XText makes heavy use of the java implementation of Ecore from the Eclipse Modelling Framework and defines RegDNA also as an Ecore model…the same Ecore model for RegDNA is used in the Python part via PyEcore.
In summary Xtext allows us to easily translate to and from RegDNA as a language, into RegDNA as an instance of an Ecore model in Java (which is representing the AST of the language) and then to easily translate from the AST to other useful frameworks using Xtext’s Xtend templates
Ecore is standard for model driven engineering , which is similar to UML class diagrams but with some extra features to assist on dealing with objects as well as classes. It is based on an open standard from OMG (EMOF) and has lots of tools in Java (such as the Eclipse modelling framework) and also tools in Python (PYecore) and other technologies like Javascript. It is very stable and mature and used in the basis on many software projects and standards including swift iso 20022 messages ubiquitous in the financial industry. Ecore models files can be stored in a standardised XML format called XMI or in a more readable version called Xcore .
It is a bit mind blowing, but Ecore can be described in Ecore, here is a wonderful summary by Obeo of the Ecore metamodel, described using free Ecore tooling.
The part of RegDNA language that describes data models is just a slightly cut-down version of Xcore, the part of the model of RegDNA which deals with data models as just a cut down version of the Ecore meta model removing anything not needed (it is called EcoreLite)
For Python we recommend VSCode or github codespaces (which is effectively VSCode running in the web browser and using the cloud), but you can use any Python development tooling . you will need to install a few prerequisites via
pip install pyecore,
pip install unidecode, and
pip install pyecoregen.
For Java developement we recommend the Eclipse IDE. Eclipse Free BIRD Tools aims to ease the generation of many types of application, but as a first example we create a plugin for the Eclipse IDE. So for this reason Java development is easiest done in the Eclipse IDE. Also we make use of Eclipse technologies such as Ecore and Xtext which have good tool support in the Eclipse IDE.
This wiki https://github.com/eclipse/efbt/wiki/Setting-up-a-development-and-debug-environment shows how to easily install the Eclispe IDE preconfigured with all the setup needed for development on Eclipse FreeBIRD Tools
[TODO -ETA 15/04/2024 ] -document the process to create and edit ecore files and generate Python or Java code from them] Creating and editing ecore files in Eclipse Creating and editing ecore files in VSCode Generating Java files from Ecore files Generating Python files form Ecore
[TODO -ETA 15/04/2024 ] -document the process to change the .xtext grammar definition and rebuild]
Generators are described here
This project provides one example generator which creates Xcore code for use in an Eclipse Desktop IDE, it is described here
See the wiki page here wiki page here
se an overview of the file structure here
We will improve it slightly for Python and give a more detailed breakdown.
For the Java build we use Maven as described here
[TODO document more clearly by 15th April 2024]
‘build clean’ vs build automatically in Eclipse IDE
What is Tycho?
The Java part is based on Eclipse Plugins, these might take some time to understand if you need to make a new part of a plugin, we will provide some links here, and advice on what you need to know and what you don’t need to know unless you are doing very specific tasks.
The Eclipse IDE gets an upgrade every 3 months, with a compatible version of Ecore and Xtext and MWE2 (which is used to automate some Ecore and Xtext tasks)
The latest version of Xtext has latest dependencies on Tycho and Junit.
We so we do an update process every 3 months to make sure we are in line with the latest versions of these. [TODO - We will describe that in more detail here]
The python code creates a set of useful scripts that can be run, there is no visual aspect to it.
Documentation on how to run the scripts is available here
This video shows a very high level overview of using the application, it also includes an advanced visual representation which is an add-on and not part of the open source platform, we will document the process in more detail below soon
Documentation in progress [TODO below]
see Creating-the-executable-transformations-from-RegDNA-logical-transformations
https://github.com/eclipse/efbt/wiki/Running-Transformations