Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "ESON"

(ZIP)
(link to bug 500916)
 
(20 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
== Introduction ==
 
== Introduction ==
  
ESON is a textual syntax for EMF models; like XMI is a XML-based syntax, ESON is a more human readable notation. It complements [[Xcore|Xcore]], which as a textual syntax for Ecore can define your EClass & Co.while ESON can represent their instances. (It is also possible to use ESON to create instances of non-Xcore normal/classic *.ecore.)
+
ESON is a textual syntax for EMF models; like XMI is a XML-based syntax, ESON is a more human readable JSON-like notation. It complements [[Xcore|Xcore]], which as a textual syntax for Ecore can define your EClass & Co.while ESON can represent their instances. (It is also possible to use ESON to create instances of non-Xcore normal/classic *.ecore.)
  
 
ESON is implemented based on [https://www.eclipse.org/Xtext/ Xtext], and *.eson files are thus truly textual representations; for example, changes made to your EObject are applied incrementally and preserve comments in or the formatting of the text.  Crucially, users of ESON do *NOT* require any Xtext know-how or code generation for their Ecore models, because ESON is fully dynamic.
 
ESON is implemented based on [https://www.eclipse.org/Xtext/ Xtext], and *.eson files are thus truly textual representations; for example, changes made to your EObject are applied incrementally and preserve comments in or the formatting of the text.  Crucially, users of ESON do *NOT* require any Xtext know-how or code generation for their Ecore models, because ESON is fully dynamic.
Line 11: Line 11:
 
=== Install ===
 
=== Install ===
  
Download the p2 ZIP named something like org.eclipse.emf.eson.repository-*-SNAPSHOT.zip from https://hudson.eclipse.org/xtext/view/Eson/job/eson/ws/git-repo/releng/org.eclipse.emf.eson.repository/target/
+
The easiest is to use the the usual menu Help > Install New Software... Add... Name: ESON, Location: https://hudson.eclipse.org/xtext/job/eson/ws/git-repo/releng/org.eclipse.emf.eson.repository/target/repository/
  
This ZIP can be installed using e.g. the usual menu Help > Install New Software... Add... Archive.. (NOT Local..).
+
Or you can download the p2 ZIP named something like org.eclipse.emf.eson.repository-*-SNAPSHOT.zip from https://hudson.eclipse.org/xtext/view/Eson/job/eson/ws/git-repo/releng/org.eclipse.emf.eson.repository/target/.  This ZIP can then be installed offline using e.g. the usual menu Help > Install New Software... Add... Archive.. (NOT Local..).
  
Alternatively use the Eclipse Installer (Oomph) to get the Src.
+
Alternatively do use the Eclipse Installer (Oomph) and choose the ESON project; this will [http://www.urbandictionary.com/define.php?term=Use+the+Source%2C+Luke get the source, luke], and you'll have a workspace ready made to contribute to ESON itself!  See "How to contribute" below.
  
=== Model ===
+
=== Introduction ===
  
It's best to use the File > New > Example... > ESON to learn how to get started!
+
It's best to use the File > New > Example... > ESON to learn how to get started! Self explanatory? ;-)
  
 
[[File:eson1.png|800px]]
 
[[File:eson1.png|800px]]
  
EClass names can be fully qualified ("Library.Book {"), or import'd with the "use Library.* Book {" syntax.  EObjects from other ESON can be similarly fully qualified ("author: lunar.loony"), or import'd with the "import lunar.* author: loony" syntax (this mechanism is based on Xtext's importedNamespace).  (The "import" keyword should NOT currently be used for EClass, because its implementation as of 2015.05.19 only consults the Xtext index but does not consult the EPackage.Registry like the "use" keyword does, correctly.)
+
=== Syntax ===
 +
 
 +
ESON files start with one or more "use" statements which indicate the EPackage to use, via the namespace URI (nsURI) of the EPackage. This can (must) be escaped by double quotes in case of "traditional" XML like convention starting with an http:// kind of scheme, or can be without escaping in case of the "modern" more Java package like "namespace", which e.g. Xcore creates by default. Optionally, a ".*" suffix following after unquoted "use".  There may be more than one "use" statement, which could be required if the EClass instances contain objects defined in another EPackage than the root object; but note that for "inferred" types of contained EClasses this is not needed.
 +
 
 +
Next comes the name of the root EClass within that EPackage, followed by an opening "{" curly brace. Within that EObject body are listed all its features. EAttribute directly list their values. Contaiment EReference embed more EClass via "{" ... "}" etc. The type of contained objects is optional, and only required if it's a sub-type, as by default ESON will assume the type of the EReference containment. Any "multiplicity many" (i.e. Upper Bound = -1) EReferences go into pairs of "[" .. "]" - just like in JSON.
 +
 
 +
Non-containment references will "refer" to EObject define elsewhere in the same or in another ESON resource.  This is based on the Xtext index infrastructure. Tip: Use Xtext's menu Navigate > Open Model Element (Shift-Ctrl-F3) to see the content of the Xtext index in your workspaceSuch EObjects from other ESON can be fully qualified ("author: lunar.loony"), or import'd with the "import lunar.* author: loony" syntax (this mechanism is based on Xtext's importedNamespace).  (The "import" keyword should NOT currently be used for EClass, because its implementation as of currently only consults the Xtext index but does not consult the EPackage.Registry like the "use" keyword correctly does.)
 +
 
 +
The name of an EObject, in order to be able to reference it from another one (or also simply for "labeling" them for clarity), by default is based on an EAttribute of type EString named "name". It is possible to customize this using the @Name annotation at the top of the ESON file, e.g. "@Name { Book = title }" (this currently has to be repeated in each ESON, not defined centrally).  For convenience and readability, it is possible to put the EObject's name straight after the EClass; for example: 'Book { name: "EMF" }' === 'Book "EMF" { }'.  Contained EObjects have a fully qualified name concatenated with the name of their parent container, if any.
  
 
=== Editor UI ===
 
=== Editor UI ===
  
The ESON Editor shows the DSL source on the left, and a tree view of the model on the right. The Properties view allows to edit the currently selected node. Changes in any of these 3 parts are live auto synchronized to the other (without saving).
+
The ESON Editor shows the DSL source on the left, and a tree view of the model on the right. The Properties view allows to edit the currently selected node. References lead to a "picker" UI. Changes in any of these 3 parts are live auto synchronized to the other (without saving).
  
 
Double clicking on the background in source on the left or the tree on the right maximizes and hides the respective other part, double clicking it again restores the default split sash presentation.
 
Double clicking on the background in source on the left or the tree on the right maximizes and hides the respective other part, double clicking it again restores the default split sash presentation.
  
The traditional read-only Outline view is intentionally disabled, to avoid end-user confusion with the right-hand side of the editor.
+
There is a working inline Ctrl-O Quick Outline. This is particularly useful to jump to named contained objects. The traditional read-only Outline view is intentionally disabled, to avoid end-user confusion with the right-hand side of the editor.
 +
 
 +
Validation Error Checking will mark in red various problems such as invalid EClass or EAttribute names, broken references, etc.
 +
 
 +
Formatting (Ctrl-Shift-F) will reformat ESON text to be correctly spaced, indented etc.
 +
 
 +
Open Declaration Ctrl-Click (F3) can "jump" into referenced EObjects.
 +
 
 +
Auto-Completion (Ctrl-Space) will propose attribute names etc. etc. (This has some room for improvement; your contributions welcome!)
 +
 
 +
There is a File > New > Other > New ESON File wizard, which allows to choose the EPackage from drop-down.  (It should also allow to then choose the root EClass, and fill in some default content - perhaps YOU will contribute that?)
  
 
=== Programmatically ===
 
=== Programmatically ===
Line 39: Line 57:
 
=== Generators ===
 
=== Generators ===
  
Standard Xtext IGenerator support is one per language, registered in the respective *RuntimeModule. So you couldn't easily add an IGenerator for your ESON unless you wanted to patch core ESON sources. However, https://git.eclipse.org/r/#/c/48029/ is adding easy out-of-the-box support for IGenerators; these can be hosted in the run-time projects workspace next to the Xcore & Test ESON, registered via a src/META-INF/services/org.eclipse.xtext.generator.IGenerator, and thus don't need a separate development vs. hosted workspace. The example projects created by the wizard also illustrate JSON and XML generation from ESON. (Remaining major issue is correct support for static Ecore/Xcore models instead of dynamic EMF instances; watch https://git.eclipse.org/r/#/c/48031/.)
+
In standard Xtext, IGenerator support is one per DSL language, registered in the respective *RuntimeModule. So one couldn't easily add an IGenerator for your ESON, unless you wanted to patch core ESON sources.  
  
''TODO: Support IGenerator in your Plug-In registered via new ESON Extension Point instead of via META-INF/services/org.eclipse.xtext.generator.IGenerator in runtime project; please raise a Bugzilla if you're interested in this.''
+
However, https://git.eclipse.org/r/#/c/65282/ has added easy out-of-the-box support for plugging IGenerators into ESON. These can either be:
 +
 
 +
1. hosted in the run-time projects workspace next to the Test ESON, and registered via a src/META-INF/services/org.eclipse.xtext.generator.IGenerator Java Service Loader configuration files (thus don't need a separate development vs. hosted workspace);
 +
 
 +
2. hosted in the Eclipse plugin project, next to the Xcore (or Ecore) model, and registered via a standard Eclipse Extension Point offered by ESON.
 +
 
 +
The library example projects created by the ESON wizard illustrate this, including JSON and XML generation from ESON. (Remaining major issue is correct support for static Ecore/Xcore models instead of dynamic EMF instances; watch https://git.eclipse.org/r/#/c/48031/.)
 +
 
 +
=== Properties view customization ===
 +
 
 +
Since https://git.eclipse.org/r/#/c/67523/ it is possible customize the Properties view. It's always shown tabbed, and by default with a "Basic" section showing all properties in flat list, similarly to the default EMF generated Properties.  The library example projects created by the ESON wizard illustrates how to add your own custom tab sections with a simple example (in real world, perhaps you would like to use other EMF frameworks, such as EEF, to create your custom Properties views for ESON). The same eson.example project also shows illustrates how the default "Basic" section can be suppressed.
  
 
=== Known Issues, Curiosum & Noteworthy ===
 
=== Known Issues, Curiosum & Noteworthy ===
  
The UI (default Tree Editor & Properties) does not yet support the usual add/remove + picker for multiplicity many references, only single ones. This is a UI limitation, the "back-end" (the code which synchronizes the two models) already supports it (DS-8674).  
+
The Xtext Builder sometimes goes into a crazy rebuild loop. This appears to occur for projects containing *.eson of PDE PluginNature and with Plugin Dependencies; but never normal Java projects. The problem was thought to have been related to TODO, but it's actually not. This has been observed with ESON on Xtext 2.8.4, and may have been fixed in more recent Xtext (not ESON) versions.
  
ESON supports EClass, EAttribute etc. names with dots in them (that is dots in the actual name, not dots to separate the name from the EPackage/s). Similarly, names (IDs) can consist of only numbers, or start with numbers. While neither is valid in standard ECore, it was added to ESON to support a particular use case.
+
EMF custom Data Type (EDataType) is not yet supported in the ESON syntax. That is, currently String, Number and Date are hard-coded, instead of supporting conversion via registered "convert" and "create" methods. Contributions adding proper support would be very welcome. Watch [https://bugs.eclipse.org/bugs/show_bug.cgi?id=500916 Bug 500916].
 +
 
 +
Curiosum: ESON supports EClass, EAttribute etc. names with dots in them (that is dots in the actual name, not dots to separate the name from the EPackage/s). Similarly, names (IDs) can consist of only numbers, or start with numbers. While neither is valid in standard ECore, it was added to ESON to support a particular proprietary in-house product use case.
  
 
== How to contribute ==
 
== How to contribute ==
Line 53: Line 83:
 
Support Forum / Mailing List via Google Group https://groups.google.com/forum/#!forum/eclipse-emf-eson-dev
 
Support Forum / Mailing List via Google Group https://groups.google.com/forum/#!forum/eclipse-emf-eson-dev
  
Src: http://git.eclipse.org/c/emf/org.eclipse.emf.eson.git/. The Eclipse Installer (based on Oomph) is great to get it all set up.
+
Source code repository is http://git.eclipse.org/c/emf/org.eclipse.emf.eson.git/. Note branching strategy: master = stable (usually last released Xtext version), nightly = bleeding edge EMF & Xtext master (may be broken some times due to issues such as [https://bugs.eclipse.org/bugs/show_bug.cgi?id=482033 Xtext Bug 482033]), Xtext-v* for maintenance of ESON on older Xtext releases. Gerrit Code review on https://git.eclipse.org/r/#/q/project:emf/org.eclipse.emf.eson
  
Gerrit Code review: https://git.eclipse.org/r/#/q/project:emf/org.eclipse.emf.eson
+
Like for all contributions to eclipse.org hosted projects, you need to get some one time admin done, including: [https://dev.eclipse.org/site_login/createaccount.php set-up an eclipse.org account],  click somewhere to [https://www.eclipse.org/legal/ecafaq.php accept the Eclipse Contributor Agreement] (ECA; formerly "CLA"), get [https://wiki.eclipse.org/Gerrit familiar with Gerrit] if aren't already, perhaps check-out the [https://wiki.eclipse.org/EGit/User_Guide EGit User Guide], etc. Tip: If you're familiar with Git and Git Hub, but are new to Gerrit, make sure you understand the one fundamental difference from a Pull Request to a Gerrit Change - a proposed change in Gerrit is always a single commit, so you have to just keep "amending", instead of pushing new commits to a branch, as is more customary with Pull Requests on Git Hub.  ([http://www.vogella.com/tutorials/EclipsePlatformDevelopment/article.html#create-an-eclipse-user-account This vogella.com article] is a nice general walk through, some of which applies to ESON contributions as well.  Note that "ESON has Oomph" (see below), and this should automate a number of otherwise manual steps including git clone, target platform, etc.)
  
Your contributions are more than welcome! Don't be shy.
+
Your contributions are more than welcome! Edits with clarifications to this Wiki are a great form to start contributing. Don't be shy.
 +
 
 +
=== Oomph ===
 +
 
 +
The [https://wiki.eclipse.org/Eclipse_Installer Eclipse Installer (Oomph)] is great and the recommended way to set up your development environment for contributing to ESON (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=482099 bug 482099]). 
 +
 
 +
There currently is some small problem in the ESON Setup model causing Oomph not to automatically git clone and import (why??), so just manually clone the ESON Git repo yourself and then add as explained in the next paragraph. (This manual step would normally be not necessary; not clear why this doesn't work automatically anymore.)
 +
 
 +
In order to see and test changes made to ESON's Oomph Setup model org.eclipse.emf.eson.releng/ESON.setup in the workspace, remember that one first time you'll have to switch to make it use that, instead of the one from the remote Git repo which it originally used when installing (otherwise you just run the original Setup, without your newest local changes).  This is done via "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace, and "Add user projects", then "Browse Workspace" to the local org.eclipse.emf.eson.releng/ESON.setup.
 +
 
 +
Note that as per [https://www.eclipse.org/forums/index.php/m/1714479/ this Oomph Forum discussion], it is recommended to set up separate installations for the 'master' vs. the 'nightly' streams.
  
 
== History ==
 
== History ==
  
 
ESON was originally born as https://code.google.com/a/eclipselabs.org/p/efactory/, later re-incarnated on https://github.com/vorburger/efactory, and as of 2014-12 the project has been formally accepted and integrated as a sub-project of the official Eclipse Modeling Framework (EMF) on eclipse.org.
 
ESON was originally born as https://code.google.com/a/eclipselabs.org/p/efactory/, later re-incarnated on https://github.com/vorburger/efactory, and as of 2014-12 the project has been formally accepted and integrated as a sub-project of the official Eclipse Modeling Framework (EMF) on eclipse.org.
 +
 +
=== Known Alternatives ===
 +
 +
The [https://www.eclipse.org/epsilon/doc/hutn/ OMG HUTN syntax support available as part of the Eclipse Epsilon project] is somewhat similar to ESON.
  
 
== Further Documentation ==
 
== Further Documentation ==

Latest revision as of 09:00, 15 September 2016

ESON - EMF Simple Object Notation

Introduction

ESON is a textual syntax for EMF models; like XMI is a XML-based syntax, ESON is a more human readable JSON-like notation. It complements Xcore, which as a textual syntax for Ecore can define your EClass & Co.while ESON can represent their instances. (It is also possible to use ESON to create instances of non-Xcore normal/classic *.ecore.)

ESON is implemented based on Xtext, and *.eson files are thus truly textual representations; for example, changes made to your EObject are applied incrementally and preserve comments in or the formatting of the text. Crucially, users of ESON do *NOT* require any Xtext know-how or code generation for their Ecore models, because ESON is fully dynamic.

How to use

Install

The easiest is to use the the usual menu Help > Install New Software... Add... Name: ESON, Location: https://hudson.eclipse.org/xtext/job/eson/ws/git-repo/releng/org.eclipse.emf.eson.repository/target/repository/

Or you can download the p2 ZIP named something like org.eclipse.emf.eson.repository-*-SNAPSHOT.zip from https://hudson.eclipse.org/xtext/view/Eson/job/eson/ws/git-repo/releng/org.eclipse.emf.eson.repository/target/. This ZIP can then be installed offline using e.g. the usual menu Help > Install New Software... Add... Archive.. (NOT Local..).

Alternatively do use the Eclipse Installer (Oomph) and choose the ESON project; this will get the source, luke, and you'll have a workspace ready made to contribute to ESON itself! See "How to contribute" below.

Introduction

It's best to use the File > New > Example... > ESON to learn how to get started! Self explanatory? ;-)

Eson1.png

Syntax

ESON files start with one or more "use" statements which indicate the EPackage to use, via the namespace URI (nsURI) of the EPackage. This can (must) be escaped by double quotes in case of "traditional" XML like convention starting with an http:// kind of scheme, or can be without escaping in case of the "modern" more Java package like "namespace", which e.g. Xcore creates by default. Optionally, a ".*" suffix following after unquoted "use". There may be more than one "use" statement, which could be required if the EClass instances contain objects defined in another EPackage than the root object; but note that for "inferred" types of contained EClasses this is not needed.

Next comes the name of the root EClass within that EPackage, followed by an opening "{" curly brace. Within that EObject body are listed all its features. EAttribute directly list their values. Contaiment EReference embed more EClass via "{" ... "}" etc. The type of contained objects is optional, and only required if it's a sub-type, as by default ESON will assume the type of the EReference containment. Any "multiplicity many" (i.e. Upper Bound = -1) EReferences go into pairs of "[" .. "]" - just like in JSON.

Non-containment references will "refer" to EObject define elsewhere in the same or in another ESON resource. This is based on the Xtext index infrastructure. Tip: Use Xtext's menu Navigate > Open Model Element (Shift-Ctrl-F3) to see the content of the Xtext index in your workspace. Such EObjects from other ESON can be fully qualified ("author: lunar.loony"), or import'd with the "import lunar.* author: loony" syntax (this mechanism is based on Xtext's importedNamespace). (The "import" keyword should NOT currently be used for EClass, because its implementation as of currently only consults the Xtext index but does not consult the EPackage.Registry like the "use" keyword correctly does.)

The name of an EObject, in order to be able to reference it from another one (or also simply for "labeling" them for clarity), by default is based on an EAttribute of type EString named "name". It is possible to customize this using the @Name annotation at the top of the ESON file, e.g. "@Name { Book = title }" (this currently has to be repeated in each ESON, not defined centrally). For convenience and readability, it is possible to put the EObject's name straight after the EClass; for example: 'Book { name: "EMF" }' === 'Book "EMF" { }'. Contained EObjects have a fully qualified name concatenated with the name of their parent container, if any.

Editor UI

The ESON Editor shows the DSL source on the left, and a tree view of the model on the right. The Properties view allows to edit the currently selected node. References lead to a "picker" UI. Changes in any of these 3 parts are live auto synchronized to the other (without saving).

Double clicking on the background in source on the left or the tree on the right maximizes and hides the respective other part, double clicking it again restores the default split sash presentation.

There is a working inline Ctrl-O Quick Outline. This is particularly useful to jump to named contained objects. The traditional read-only Outline view is intentionally disabled, to avoid end-user confusion with the right-hand side of the editor.

Validation Error Checking will mark in red various problems such as invalid EClass or EAttribute names, broken references, etc.

Formatting (Ctrl-Shift-F) will reformat ESON text to be correctly spaced, indented etc.

Open Declaration Ctrl-Click (F3) can "jump" into referenced EObjects.

Auto-Completion (Ctrl-Space) will propose attribute names etc. etc. (This has some room for improvement; your contributions welcome!)

There is a File > New > Other > New ESON File wizard, which allows to choose the EPackage from drop-down. (It should also allow to then choose the root EClass, and fill in some default content - perhaps YOU will contribute that?)

Programmatically

Using ESON, any *.eson file can be loaded as a normal EMF resource. An instance of your "real" EMF model described by the ESON will be available in getContents().get(1); the get(0) will give you the internal Xtext representation which typically you won't be interested in. This resource has bi-directional synchronization of changes made to either of these two models - so you can use it like a "normal" EMF model, save it, and the ESON will be correctly updated.

Generators

In standard Xtext, IGenerator support is one per DSL language, registered in the respective *RuntimeModule. So one couldn't easily add an IGenerator for your ESON, unless you wanted to patch core ESON sources.

However, https://git.eclipse.org/r/#/c/65282/ has added easy out-of-the-box support for plugging IGenerators into ESON. These can either be:

1. hosted in the run-time projects workspace next to the Test ESON, and registered via a src/META-INF/services/org.eclipse.xtext.generator.IGenerator Java Service Loader configuration files (thus don't need a separate development vs. hosted workspace);

2. hosted in the Eclipse plugin project, next to the Xcore (or Ecore) model, and registered via a standard Eclipse Extension Point offered by ESON.

The library example projects created by the ESON wizard illustrate this, including JSON and XML generation from ESON. (Remaining major issue is correct support for static Ecore/Xcore models instead of dynamic EMF instances; watch https://git.eclipse.org/r/#/c/48031/.)

Properties view customization

Since https://git.eclipse.org/r/#/c/67523/ it is possible customize the Properties view. It's always shown tabbed, and by default with a "Basic" section showing all properties in flat list, similarly to the default EMF generated Properties. The library example projects created by the ESON wizard illustrates how to add your own custom tab sections with a simple example (in real world, perhaps you would like to use other EMF frameworks, such as EEF, to create your custom Properties views for ESON). The same eson.example project also shows illustrates how the default "Basic" section can be suppressed.

Known Issues, Curiosum & Noteworthy

The Xtext Builder sometimes goes into a crazy rebuild loop. This appears to occur for projects containing *.eson of PDE PluginNature and with Plugin Dependencies; but never normal Java projects. The problem was thought to have been related to TODO, but it's actually not. This has been observed with ESON on Xtext 2.8.4, and may have been fixed in more recent Xtext (not ESON) versions.

EMF custom Data Type (EDataType) is not yet supported in the ESON syntax. That is, currently String, Number and Date are hard-coded, instead of supporting conversion via registered "convert" and "create" methods. Contributions adding proper support would be very welcome. Watch Bug 500916.

Curiosum: ESON supports EClass, EAttribute etc. names with dots in them (that is dots in the actual name, not dots to separate the name from the EPackage/s). Similarly, names (IDs) can consist of only numbers, or start with numbers. While neither is valid in standard ECore, it was added to ESON to support a particular proprietary in-house product use case.

How to contribute

Support Forum / Mailing List via Google Group https://groups.google.com/forum/#!forum/eclipse-emf-eson-dev

Source code repository is http://git.eclipse.org/c/emf/org.eclipse.emf.eson.git/. Note branching strategy: master = stable (usually last released Xtext version), nightly = bleeding edge EMF & Xtext master (may be broken some times due to issues such as Xtext Bug 482033), Xtext-v* for maintenance of ESON on older Xtext releases. Gerrit Code review on https://git.eclipse.org/r/#/q/project:emf/org.eclipse.emf.eson

Like for all contributions to eclipse.org hosted projects, you need to get some one time admin done, including: set-up an eclipse.org account, click somewhere to accept the Eclipse Contributor Agreement (ECA; formerly "CLA"), get familiar with Gerrit if aren't already, perhaps check-out the EGit User Guide, etc. Tip: If you're familiar with Git and Git Hub, but are new to Gerrit, make sure you understand the one fundamental difference from a Pull Request to a Gerrit Change - a proposed change in Gerrit is always a single commit, so you have to just keep "amending", instead of pushing new commits to a branch, as is more customary with Pull Requests on Git Hub. (This vogella.com article is a nice general walk through, some of which applies to ESON contributions as well. Note that "ESON has Oomph" (see below), and this should automate a number of otherwise manual steps including git clone, target platform, etc.)

Your contributions are more than welcome! Edits with clarifications to this Wiki are a great form to start contributing. Don't be shy.

Oomph

The Eclipse Installer (Oomph) is great and the recommended way to set up your development environment for contributing to ESON (see bug 482099).

There currently is some small problem in the ESON Setup model causing Oomph not to automatically git clone and import (why??), so just manually clone the ESON Git repo yourself and then add as explained in the next paragraph. (This manual step would normally be not necessary; not clear why this doesn't work automatically anymore.)

In order to see and test changes made to ESON's Oomph Setup model org.eclipse.emf.eson.releng/ESON.setup in the workspace, remember that one first time you'll have to switch to make it use that, instead of the one from the remote Git repo which it originally used when installing (otherwise you just run the original Setup, without your newest local changes). This is done via "Import Projects..." in the drop-down of the Perform Setup Tasks reload action in the Oomph toolbar, or via the menu File > Import> Oomph > Projects into Workspace, and "Add user projects", then "Browse Workspace" to the local org.eclipse.emf.eson.releng/ESON.setup.

Note that as per this Oomph Forum discussion, it is recommended to set up separate installations for the 'master' vs. the 'nightly' streams.

History

ESON was originally born as https://code.google.com/a/eclipselabs.org/p/efactory/, later re-incarnated on https://github.com/vorburger/efactory, and as of 2014-12 the project has been formally accepted and integrated as a sub-project of the official Eclipse Modeling Framework (EMF) on eclipse.org.

Known Alternatives

The OMG HUTN syntax support available as part of the Eclipse Epsilon project is somewhat similar to ESON.

Further Documentation

TBD Transfer, and update, old documentation from https://github.com/vorburger/efactory/blob/eclipse.org/org.eclipse.emf.eson.help/help/concepts.mediawiki

Older doc: http://git.eclipse.org/c/emf/org.eclipse.emf.eson.git/plain/README.md

Back to the top