Aconite

March 25, 2025 · View on GitHub

Introduction

Aconite is a tool that generates graphical modelling notations from an annotated Ecore metamodel, targeting Eclipse Sirius. It is inspired on the approach followed by Eugenia, which targeted the Graphical Modeling Framework tooling (now archived).

Aconite allows you to add EAnnotations to an Ecore based metamodel to generate a Sirius editor for models that conform to the metamodel. Aconite is designed to expose as many Sirius features as possible, while providing sane defaults that act as a gentle introduction to Sirius and the Acceleo Query Language.

Requirements

Eclipse Modeling Tools 2023-09 or newer
Java 17+
Eclipse Epsilon 2.5.0+
Eclipse Emfatic 1.1+ (To use textual notation)
Eclipse Sirius 7.x

Quickstart guide

Setting up the Eclipse IDE

First, install Eclipse through the Eclipse installer, by choosing "Eclipse Modeling Tools" from its main window. The first time Eclipse is launched, it will show a "Welcome" tab: close it by clicking on the X button of the tab.

To install Aconite, go to the menu bar and click "Help > Install new software...", then replace the contents of "Work with:" with https://nwxrichardson.github.io/aconite/updates/ and press Enter. Once the "Aconite" category appears in the list, click on "Select All" and then "Next". It should then list that the "Aconite Feature" is going to be installed. Accept the terms of the Eclipse Public License, indicate that you trust the update site (as it is currently unsigned), and let Eclipse restart once prompted.

Once it has restarted, we are going to use "Help > Install new software..." twice more:

First, to install Epsilon from http://download.eclipse.org/epsilon/updates/2.5. Select "Epsilon Core", "Epsilon EMF Integration - Epsilon EMF Integration", and "Epsilon Sirius Integration". Trust the org.apache.commons.math3 library if required to do so.
Next, install Emfatic from http://download.eclipse.org/emfatic/update. Select the "Emfatic" category.

Finally, for Sirius we are going to go to "Help > Eclipse Marketplace", search for "Sirius" and click on "Install" before a final restart.

Trying out Aconite on one of the provided examples

Initial setup

Clone the repository. We will use the example in its examples/siriusfamily folder.

Import the projects in that folder into your Eclipse workspace, by clicking on the "File > Import" menu item and selecting "General > Existing Projects into Workspace". Find the downloaded subdirectory and import these four projects:

uk.ac.york.aconite.family
uk.ac.york.aconite.family.edit
uk.ac.york.aconite.family.editor
uk.ac.york.aconite.family.tests

Once imported, right-click on uk.ac.york.aconite.family and click "Run As... > Eclipse Application". This will open a nested ("runtime") Eclipse, into which we import only uk.ac.york.aconite.family by clicking on the "File > Import" menu item and selecting "General > Existing Projects into Workspace" unticking the other projects.

Experimenting with Aconite annotations

Within the "Model Explorer" view of the runtime eclipse, expand the uk.ac.york.aconite.family project and its description folder, and right-click on its basicfamily.emf file. Select "Aconite - Generate Odesign" to produce the basicfamily.odesign in the same folder.

To experiment with Aconite, edit the basicfamily.emf file using Emfatic and the annotations documented below, while regenerating the .odesign file as described above after any changes. To view the results of these changes on the diagrams themselves, expand the model folder in the "Model Explorer" view, then select family.aird:

Pre-existing representations can be viewed from the "Representations" list in the .aird editor, by double-clicking on their contents. One of the predefined representations is shown below.
To generate a new representation, double-click on those preceded by , then select a valid model element (those for which the Finish button is enabled).
Representations can only be created for models .aird is aware of; to create views for a new model, you need to go to "Add > Browse Workspace" and then find the relevant model.

The expected family representation

QuickStart guide for a new Aconite Project

Initial Setup

First step is to create a new empty project by going "File > New > Project > Project".

Then right-click on the new project "New > Other > Emfatic File" which will create an Emfatic file in which you can specify your metamodel. The next step is to generate the code metamodel, which starts by right-clicking the .emf file and clicking "Generate Ecore Metamodel". We then right-click the new .ecore file and go "New > Other > EMF Generator Model" and click through the wizard till the button greys out and click load before continuing to click through. This will create a .genmodel, open the file and right-click the top level element and select "Generate All".

This should generate the projects below from the project original.project.name we then right click the top project and go to "Run As > Eclipse Application".

original.project.name.edit
original.project.name.editor
original.project.name.tests

Within the nested ("runtime") Eclipse, into which we import only original.project.name by clicking on the "File > Import" menu item and selecting "General > Existing Projects into Workspace" unticking the other projects.

To allow us to be able to experiment with Aconite in this new project as in the example project (see above section) we need to create an instance of the model and the .aird file. To do this right click on the project "New > Other > Package Name Model" this will create a model conforming to your metamodel. Then right-click on this new file "New > Representation File" and click through the the wizard.

Making structural changes to the metamodel

To make structural changes to the metamodel (for example, changing the EClasses or their features), please follow these steps:

Close the "runtime" Eclipse instance.
Make the changes to the .emf file from the main Eclipse instance.
Regenerate the .ecore file by right-clicking on the .emf file and using "Generate Ecore Package".
Open the .genmodel file and regenerate the model/edit/editor code by right-clicking on the root of the tree.
Launch the "runtime" Eclipse instance as above.

Wider Context

In order to simplify this QuickStart section we have ignored the underlying technologies that have been used. As Aconite is based on the generation of the Sirius VSM it is based on the Eclipse Modelling Framework EMF which will be the source if you want to further customise your models. This is also true of Sirius which has more customisation options than Aconite currently allows for with full range to be found here.

Table of annotations and properties

@aconite

For Aconite to work, each Ecore file must contain exactly one @aconite annotation:

@aconite(iconFolder = "uk.ac.york.aconite.family/icons/")
package basicfamily;

Properties	Description	Required	Default
iconFolder	This sets the location of a folder from which all icon paths and image paths start from.	❎	""

@aconite.diagram

@aconite.diagram ( name = "Project Diagram")
class Project { /* ... */ }

Properties	Description	Required	Default
name	The name of the diagram used at the UID within Sirius and Aconite	✅	N/A
abstract	Sets the diagram to be abstract, therefore it will not be created. This can be used to store information to be used by other annotations through extend.	❎	false

@aconite.container, @aconite.node, and @aconite.border Properties

@aconite.container ( name = "Task Container", container = "Project Diagram")
class Task { /* ... */ }

@aconite.node ( name = "Deliverable Node", container = "Task Container")
 class Deliverable { /* ... */ }

@aconite.border ( name = "Lead Border Node",  container = "Deliverable Node")
class Person { /* ... */ }

Property	Description	Required	Default
name	The name of the element used at the UID within Sirius and Aconite	✅	N/A
container (@aconite.container and @aconite.node)	This point to the contain of the node. This can be either a @aconite.diagram or @aconite.container, using their name property as their ID. This can contain multiple value (container = "XXX, YYY, ZZZ") a copy of this container would then be contained in each.	✅	N/A
container (@aconite.border)	The only distinction of the border node is the way that it works with container. As you can select any @aconite.container or @aconite.node to which it will then be attached to the border.	✅	N/A
label	This sets the label of this mapping within Sirius, effecting how it will appear in the VSM and effect the naming of some tools.	❎	property: name
abstract	Sets the diagram to be abstract, therefore it will not be created. This can be used to store information to be used by other annotations through extend.	❎	false
createElements	Sets whether the Sirius editor is able to create elements of this description. This does not automatically create the tools to do so if set to true.	❎	true
createable	When set to true Aconite will attempt to create a tool which allows for that element to be created. It does this be checking whether the container within the diagram is it container and if so it will create a tool.	❎	true
directlyEditable	When set to true Aconite will attempt to create tool which is able to directly edit the text of the label shown for this within the diagram.	❎	true
sce / semanticCandidateExpression	This allows you to take over the Semantic Candidate Expression from Aconite. (Expression current begins aql:self. )	❎	an sce generated by Aconite
childrenPresentation (@aconite.container specific)	Set how all of the nodes and containers within the container at to be displayed. {freeForm, horizontalStack, list, verticalStack}	❎	freeFrom

@aconite.container.description, @aconite.node.description, and @aconite.border.description

The following are also properties of @aconite.container, @aconite.node, and @aconite.border focused on presentation. They should be used in the @aconite.node form for simple annotations, but the .description version can be used if, for example, the annotation is too long or to contrast multiple designs without duplication.

@aconite.node ( name = "Deliverable Node", container = "Task Container")
@aconite.node.description (node = "Deliverable Node , color = "red")
 class Deliverable { /* ... */ }

@aconite.node ( name = "Deliverable Node", container = "Task Container", color = "red")
 class Deliverable { /* ... */ }

Property	Description	Required	Default
node	This property is how @aconite.XXX.description is connected. Using the node or container's name as UID.	✅	N/A
shape	The property shape selects from the list of possible ways that the element can be represented each of which include new properties to be set which can be found after this table.	❎	@aconite.container: flat @aconite.node & @aconite.border: square
color	This sets the color of the element will be in general. However the shape selected might mean that isn't shown.	❎	light_yellow
hideLabelByDefault	If set to true the label text will be hidden by default until manually shown.	❎	false
iconPath	For setting a file path in which the icon is stored. This works by adding the folder path to the front of the file path.	❎	""
heightComputationExpression	Sets how the height of the element is to be calculated. The value -1 means that it will just leave it to the user to resize the element.	❎	-1
widthComputationExpression	Sets how the width of the element is to be calculated. The value -1 means that it will just leave it to the user to resize the element.	❎	-1
borderColor	Set the color of the border of the element.	❎	black
borderLineStyle	Set the line style between {dot, dash, dashDot, solid}.	❎	solid
borderSize	Sets the size of the border.	❎	3
labelAlignment	How the label will be aligned within the element between {center, left, right}.	❎	center
labelColor	The color of the text label.	❎	black
labelValue	Allow the user full control of the SCE used to generate the label. For new users this is the property to allow you to manually set the string for a set of elements. (" 'Siblings' ")	❎	aql:self. (property labelExpression)
labelExpression	This is a helper property and is only used if labelValue is not set. It sets up the beginning of the expression for an SCE.	❎	name
labelFormat	Allow you to select multiple formatting for the text from {italic, bold, underline, strikeThrough}.	❎	""
labelSize	Sets the size of the label.	❎	12
showIcon	Whether the element will attempt to show the icon it is assigned or not.	❎	false
tooltip	Sets a SCE the returns a String which is a text that will show up if the user hovers over the element for a time. This can be set to a single string for all of the elements also similar to labelValue.	❎	""
@aconite.container.description specific properties
roundedCorner	Sets whether to round the corners of the element.	❎	false
arcHeight	Sets the arc height of the rounded corner.	❎	1
arcWidth	Sets the arc width of the rounded corner.	❎	1

@aconite.container shapes

Flat - A rectangle which can have a gradient

Property	Description	Required	Default
backgroundStyle	This sets the way the colors are represented. {gradientLeftToRight, gradientRightToLeft, liquid}	❎	gradientLeftToRight
backgroundColor	This sets the background color if the flat style is set to a gradient option.	❎	Property: color
foregroundColor	This sets the foreground color if the flat style is set to a gradient option.	❎	Property: color

Property	Description	Required	Default
height	Sets the height that the element will start as when put into the diagram.	❎	0
width	Sets the width that the element will start as when put into the diagram.	❎	0

Dot - Creates a circle element.

Ellipse - Creates a circle element.

Property	Description	Required	Default
horizontalDiameterComputationExpression	Sets the width that the element will start as when put into the diagram.	❎	2
verticalDiameterComputationExpression	Sets the height that the element will start as when put into the diagram.	❎	2

Workspace Image - create a image node

Property	Description	Required	Default
imagePath	Sets the file location of an image which is used as the element. Similar to icon this is added to the folder location set by @aconite.	✅	N/A

@aconite.edge table

@aconite.edge General Properties	Description	Required	Default
name	The name of the edge used at the UID within Sirius and Aconite	✅	N/A
label	This sets the label of this mapping within Sirius, effecting how it will appear in the VSM and effect the naming of some tools.	❎	property: name
createable	This when set to true will mean Aconite will attempt to create a tool to create that edge.	❎	true
reconnectable	This when set to true will attempt to create the tools to be able reconnect either end of the edge to similar elements.	❎	true

Reference edges - those connected to an EReference

class Deliverable {
 @aconite.edge ( name ="Lead Edge", container = "Leader Diagram")
 ref Person lead ;
 }

@aconite.edge Reference Properties	Description	Required	Default
targetNode	Target node is used to change the set of elements that this edge can be pointing at. As by default it will pick everything that reference could point at.	❎	generated
targetFinderExpression	This allows a user to take control of the target expression which works like a SCE to get the element to point at. In general this should only be used to filter down the references as the other will be set by default as if that were the case.	❎	generated
target	A special case of the target finder expression which adds aql:self. automatically. Use this if you are just doing a path through references and it will generate targetNode for you.	❎	generated

Element edges - those connected to an EClass

@aconite.edge ( name = "Effort Edge",
 container ="Effort Diagram",
 labelExpression = "percentage",
 source ="person", target ="task")
class Effort {
 ref Task [1]# effort task ;
 ref Person person ;
 attr int percentage = 100;
 }

@aconite.edge Reference Properties	Description	Required	Default
sce / semanticCandidateExpression	An SCE like for @aconite.node which is an element the rest of the properties point out from.	❎	generated
sourceFinderExpression	This allows a user to take control of the source expression which works like a SCE to get the element to point at. In general this should only be used to filter down the references as the other will be set by default as if that were the case.	❎	generated
targetFinderExpression	This allows a user to take control of the target expression which works like a SCE to get the element to point at. In general this should only be used to filter down the references as the other will be set by default as if that were the case.	❎	generated
source	A special case of the source finder expression which adds aql:self. automatically. Use this if you are just doing a path through references and it will generate sourceNode for you.	✅	N/A
target	A special case of the target finder expression which adds aql:self. automatically. Use this if you are just doing a path through references and it will generate targetNode for you.	✅	N/A
sourceNode	Source node is used to change the set of elements that this edge can be pointing from. As by default it will pick everything that source reference could point at.	❎	generated
targetNode	Target node is used to change the set of elements that this edge can be pointing at. As by default it will pick everything that the target reference could point at.	❎	generated