Commit 0fe05b5e authored by Kai-Holger Brassel's avatar Kai-Holger Brassel
Browse files

Update documentation

* replace Obeo Designer by Eclipse Modeling Tools
* update to Java 17 and Eclipse 2021-12
* move PDF from git to Kai's web page
parent 8833138c
Pipeline #5731 passed with stage
......@@ -3,7 +3,6 @@ pages:
script:
- mkdir .public
- cp -r ParameterCatalogs2Images .public
- cp ParameterCatalogs.pdf .public
- cp UnitsExamples.md .public
- cp ParameterCatalogs.html .public/index.html
- mv .public public
......
......@@ -10,9 +10,9 @@ image:https://mirrors.creativecommons.org/presskit/icons/by.svg[by,20]
image:https://mirrors.creativecommons.org/presskit/icons/nc.svg[nc,20]
image:https://mirrors.creativecommons.org/presskit/icons/nd.svg[nd,20]
Non-final version: September 7^st^, 2021.
Non-final version: January 31, 2022.
Go to link:ParameterCatalogs.pdf[PDF-Version as of September 7^th^, 2021]
Go to link:https://www.khbrassel.de/parametercatalogs/ParameterCatalogs.pdf[PDF-Version as of January 31, 2022]
include::ParameterCatalogs1Overview.adoc[]
......
This diff is collapsed.
......@@ -90,70 +90,83 @@ That way, we can follow the convention that local Git repositories should all be
`<userhome>/git`.
=== Setup Obeo Designer
=== Setup Eclipse Modeling Tools
.Install Java
Eclipse runs on 64-bit versions of Windows, Linux, and macOS and requires an according Java Development Kit (JDK), version 11 or higher, to be installed on your machine.
Even if such JDK is already installed on your machine, please download the OpenJDK version *16* or newer for your operating system from https://adoptium.net[Adoptium].
Eclipse runs on 64-bit versions of Windows, Linux, and macOS and requires an according Java Development Kit (JDK), version 17 or higher, to be installed on your machine.
Even if such JDK is already installed on your machine, please download the JDK version *17* for your operating system from https://adoptium.net[Adoptium].
Installation process is straight forward, but you can also find links to exhaustive instructions for your operating system.
New Java versions appear every six months, so one could tend to stick with older version 11 that comes with long time support (LTE) until next LTE version 17 arrives in autumn 2021.
However, actual version 16 conforms to the latest security measures built into macOS Catalina, so it is a must if software we build here shall be deployed to these systems, too.
New Java versions appear every six months, but we will stick for the coming years with version 17, since it comes with long time support (LTS).
Note that different versions of Java coexist peacefully.
.Install Obeo Designer, Community Edition
.Install Eclipse Modeling Tools
Our graphical and form based modeling tools, e.g. Insel 9.0 and Parameter Catalogs, run on top of https://www.obeodesigner.com/en/product/sirius[Eclipse Sirius].
Technically, the Eclipse Sirius project provides a set of open source features and plugins that can be added to any Eclipse package to transform it into a very flexible modeling workbench.
Instead of adding these software components manually, we start with a pre-configured Eclipse package named _Obeo Designer_.
Please download and install the latest version (11.5 at the time of writing) available at https://www.obeodesigner.com/en/download[Download Obeo Designer Community].
Our graphical and form based modeling tools, e.g. Insel 9.0 and Parameter Catalogs, run on top of Eclipse Sirius, an open source framework that provides a set of features and plugins that can be added to any Eclipse package to transform it into a very flexible modeling workbench.
[NOTE]
====
Depending on the operating system, several security dialogs have to be acknowledged during installation and first launch of Obeo Designer.
====
In the past, we used the pre-configured Eclipse package _Obeo Designer Community_ from https://www.obeodesigner.com[Obeo], but it wasn't updated for a while and, thus, is stucked at Java version 14.
After the 400 something MB package has arrived, unzip the downloaded file and move the resulting application named `ObeoDesigner-Community` to a suited directory. This would be `Applications` on macOS, similar on Linux, but **not** `Programs` or `Programs (x86)` on Windows!
Instead, we install the Eclipse package _Eclipse Modeling Tools_ first and, then, Eclipse Sirius on top. To get current version 4.22 (2021‑12) of _Eclipse Modeling Tools_, go to https://www.eclipse.org/downloads/packages/[www.eclipse.org/downloads/packages/].
On this page you may see _"Try the Eclipse Installer"_ or similar.
Do *not* follow this advice, since we want more control over what versions of Java and Eclipse shall be installed.
Instead, look for package _Eclipse Modeling Tools_ and follow the link for your operating system and system architecture displayed on the right:
[WARNING]
====
**Special installation note for Windows**: We found that no plug-ins can be added to Obeo Designer, **if** it is installed in folder _Programs_ or _Programs (x86)_. Since we have to add plug-ins for handling units and quantities below, please make sure to unzip the installation package elsewhere, e.g. the Desktop or the user's home directory.
.Download links for Eclipse Modeling Tools package
image::EclipseDownload.gif[EclipseDownload, 500, role="thumb"]
====
Finally, click on `Download` and wait for the 450 something MB package to arrive.
Unzip the downloaded file and possibly rename the resulting application `Eclipse` to something more specific like `EclipseModeling2112`. Then, move the application to a suited directory. This would be `Applications` on macOS, similar on Linux, but **not** `Programs` or `Programs (x86)` on Windows!
[WARNING]
====
**Special installation note for macOS**: As Obeo Designer currently is not code-signed, macOS consideres it as damaged. To work around this security feature, remove the quarantine status of the program like so:
**Special installation note for Windows**: We found that sometimes plug-ins cannot be added to Eclipse, **if** it is installed in folder _Programs_ or _Programs (x86)_. Since we have to add plug-ins for Sirius and for handling units and quantities below, please make sure to unzip the installation package elsewhere, e.g. the Desktop or the user's home directory.
====
. Open a terminal in the folder containing the .app file
. Execute: xattr -d com.apple.quarantine ObeoDesigner-Community.app
. Double click the app to start.
[NOTE]
====
Depending on the operating system, several security dialogs have to be acknowledged during installation and first launch of Eclipse Modeling Tools.
====
After installation has finished launch the application for the first time and you will see a dialog for choosing a new empty directory as its workspace.
After installation has finished, launch the application for the first time and you will see a dialog for choosing a new empty directory as its workspace.
.Initial Dialog to Choose a Workspace Directory
image::SelectWorkspaceDirectory.gif[SelectWorkspaceDirectory, 500, role="thumb"]
More workspaces might come into existence later, so replace the proposed generic directory path and name with a more specific one, e.g.`ObeoDesignerWS`.
More workspaces might come into existence later, so replace the proposed generic directory path and name with a more specific one, e.g.`EclipseWSCatalogs`.
The main window appears with a Welcome Screen open.
Especially under `Documentation` you will find exhaustive documentation on Eclipse that might be of interest later, e.g.:
Especially under `Workbench Basics` you will find exhaustive documentation on Eclipse that might be of interest later, e.g.:
** Workbench User Guide
*** Concepts: perspectives, projects, views, editors, features, resources, ...
*** Tasks: Working with perspectives, views and editors, installing new software. ...
** EGit Documentation
*** Git for Eclipse Users
*** EGit User Guide
** Ecore Tools User Manual: Learn how to use the Ecore diagram editor.
*** Git for Eclipse Users
** Ecore Tools User Manual: Learn how to design Ecore models.
For now, you can dismiss the welcome screen. It can be opened anytime by executing `Help -> Welcome`.
Now you should see the initial window layout with _Model Explorer_ and _Outline_ on the left and a big empty editing area to the right with a _Properties_ view below.
.Install Eclipse Sirius
While package _Eclipse Modeling Tools_ already contains Sirius features that let you create graphical Ecore models, features for specifying your own forms and graphical editors are still missing. You can add these features easily from _Eclipse Marketplace_:
* Open dialog `Help -> Eclipse Marketplace...` and type _Search_ into the search field
* Look for Sirius 6.6 or newer in the list of results and click `Install`
* From the list of features choose `Sirius Specifier Environment` and `Sirius Support for AQL` for installation and unchoose the others (see screen shot)
* Confirm your choice, acknowlege any licenses, and restart Eclipse when asked for.
.Download links for Eclipse Modeling Tools package
image::InstallSirius.png[InstallSirius, 500, role="thumb"]
Above steps added commonly used software components to your Eclipse application, publicly available in the _Eclipse Marketplace_. In the next section, however, you will add features that were created specifically for parameter catalogs and hosted at the transfer portal of _HfT Stuttgart_.
[[quantity-plug-ins]]
.Add Plug-ins to deal with Quantities and Units
......@@ -166,7 +179,7 @@ The reference implementation for this framework is https://unitsofmeasurement.gi
To make Indriya available for use in Ecore data models, the author has created two plug-ins that can easily be added to Eclipse. To do so, open dialog `Help -> Install New Software...` and enter site `https://transfer.hft-stuttgart.de/pages/neqmodplus/indriya-p2/release_target_211/` like depicted below.
.Install Plug-in from Specific Update Site
image::AddUpdateSite.png[Install Plug-in , 500, role="thumb"]
image::AddUpdateSite.png[Install Plug-in, 500, role="thumb"]
Select Indriya plug-in, press `Next >` and acknowledge all following dialogs, including security warnings.
......@@ -175,8 +188,6 @@ Finally, restart Eclipse to complete plug-in installation.
While the first plug-in installs Indriya, the second plug-in adds some specific units for urban simulation and Ecore types used for modeling quantities as attributes of classes.
Now you should see the initial layout of Eclipse with _Model Explorer_ and _Outline_ on the left and a big empty editing area to the right with a _Properties_ view below.
=== Exercise: Modeling a Parameter Catalog with Ecore
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment