Developer Documents - User contributions [en]

Quick Development Environment Setup

2017-06-05T05:26:06Z

Hannu Niemisto:

__TOC__

== Install Java JDK and Eclipse, and Setup the IDE for Simantics Development ==

# Get and install the latest 64-bit ''Java SE Development Kit 8'' (JDK 8). You can download the package from [http://www.oracle.com/technetwork/java/javase/downloads/index.html http://www.oracle.com/technetwork/java/javase/downloads/index.html]. Follow the installation instructions for your operating system. It is recommended to always use the latest JDK update.
# Get and install the latest 64-bit ''Eclipse Classic IDE'' release build. You can find the package from [http://download.eclipse.org/eclipse/downloads/ http://download.eclipse.org/eclipse/downloads/]. You can select freely the installation location for the package, e.g. under your home directory. Just unzip the package to install Eclipse. Alternatively, there is also an [http://www.eclipse.org/downloads/ installer] available.
# After the installation of Eclipse, check that your Eclipse is set to use the right Java Runtime Environment (JRE):
#* In Eclipse platform, open "Window - Preferences".
#* Open page “Java / Installed JREs”.
#* Set the JRE to point to the previously installed JDK 8.
# Install the Simantics Graph Compiler:
#* In Eclipse platform, open “Help / Install New Software...”.
#* Set the installation site to "http://www.simantics.org/update/utils" in the “Work with” field and press “Add...”. Give the installation site link a name when asked.
#* Select from the list the latest "Ontology development / Graph feature" and proceed with the installation. Restart Eclipse after the installation.
# Install the Subversive plug-in to the Eclipse platform:
#* In Eclipse platform, open ''“Help / Install New Software...”''.
#* Select installation site "Neon - http://download.eclipse.org/releases/neon" to the “Work with” field from the preset list.
#* Click open the "Collaboration" folder and select from the list:
#** ''Subversive SVN Team Provider''
#** ''Subversive SVN JDT Ignore Extensions''
#: and proceed with the installation. Restart Eclipse after the installation.
# After restarting Eclipse, open the SVN Repository Exploring perspective:
#* In Eclipse platform, open “Window / Open Perspective / Other...”.
#* Select ''SVN Repository Exploring'' and press “OK”. Eclipse should open the “Install Connectors” dialog.
#* Select latest “SVN Kit 1.x.y” and press “Finish”, and proceed with the installation. Restart Eclipse after the installation.

== Install Latest Simantics Target Platform ==

# In Eclipse platform, activate the ''Plug-in Development'' perspective, either from the tab on the upper right corner of the Eclipse platform or from the “Window / Open Perspective / Other...” menu, and select ''Plug-in Development''.
# Create a new general project in Eclipse by:
#* Selecting “File / New / Project...” menu item.
#* In the "Select a wizard", select “General / Project” and press “Next”.
#* Give the project a name, e.g. "Simantics_target" and press "Finish".
# Copy one of the following files into your system to some temporary location:
#* [http://www.simantics.org/download/latest/simantics.target http://www.simantics.org/download/latest/simantics.target] (for application development on Simantics platform)
#: The Simantics platform source code is available for [https://www.simantics.org/simantics/about-simantics/thth-simantics THTH/Simantics Division] registered members through these alternative target definitions (user name and password are asked during the installation, these are available at the [https://www.simantics.org/members/index.php/Main_Page THTH/Simantics Member Wiki]):
#* [http://www.simantics.org/download/latest/simantics-sdk.target http://www.simantics.org/download/latest/simantics-sdk.target] (for Simantics platform development and application development on Simantics platform)
# In Eclipse ''Package Explorer'' (the view on left side of the Eclipse platform):
#* Right-click your previously created project and select "Import..." from the context menu.
#* In ''Select wizard'', select “General / File System”, and press "Next".
#* Select in the “From directory” the folder where the previously downloaded file(s) are located, and select the downloaded file(s) in the file list below. Press "Finish".
# Set the target platform for the development with Simantics:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* The new target definitions should be available in the list. Activate one of the following:
#** “Simantics x.y” (for application development on Simantics platform)
#** “Simantics SDK x.y” (for Simantics platform development and application development on Simantics platform)
#: and confirm the target platform definition by pressing "Apply" and/or "OK". If you defined a ''Simantics SDK x.y'' target, you are asked for the username and the password.
#* Wait until Eclipse finishes downloading, this may take a while. After the download is completed, there should be several plug-ins starting with "org.simantics.*" in the Eclipse ''Plug-ins'' view (the view on the left side of Eclipse).
# '''Keep your platform up-to-date!''' Updating is as easy as reloading the target platform from ''Target Platform'' preference page:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* Select the active target platform, e.g. ''Simantics SDK x.y'', from the list and press "Reload".
#* Wait until the platform is updated.

== Test Your Installation ==

Test your installation with the [http://dev.simantics.org/index.php/Tutorial:_Ontology_Development Simantics movie tutorial]:

# Download ''Simantics movie tutorial'' plug-ins into your Eclipse workspace:
#* Get [https://www.simantics.org/jenkins/job/Tutorials/job/package-movie-tutorial-head/lastSuccessfulBuild/artifact/movie-tutorial.zip]
#* In Eclipse platform, select “File / Import...” menu item.
#* In the "Select" dialog, select “General / Existing Projects into Workspace” and press “Next”.
#* Select the “Select archive file:” radio button and press “Browse” to find the downloaded movie-tutorial.zip.
#* Press “Select All” and “Finish”.
# Run movie.product:
#* From the ''Package Explorer'' view, open “org.simantics.movie.ui'' / Movie.product”.
#* From the ''Overview'' page of the opened product editor, press “Launch an Eclipse application”.

If you managed to start the ''movie'' product, your development platform should be operational.

'''''Happy developing with Simantics!'''''

Quick Development Environment Setup

2017-06-05T05:24:41Z

Hannu Niemisto: /* Install Java JDK and Eclipse, and Setup the IDE for Simantics Development */

__TOC__

== Install Java JDK and Eclipse, and Setup the IDE for Simantics Development ==

# Get and install the latest 64-bit ''Java SE Development Kit 8'' (JDK 8). You can download the package from [http://www.oracle.com/technetwork/java/javase/downloads/index.html http://www.oracle.com/technetwork/java/javase/downloads/index.html]. Follow the installation instructions for your operating system. It is recommended to always use the latest JDK update.
# Get and install the latest 64-bit ''Eclipse Classic IDE'' release build. You can find the package from [http://download.eclipse.org/eclipse/downloads/ http://download.eclipse.org/eclipse/downloads/]. You can select freely the installation location for the package, e.g. under your home directory. Just unzip the package to install Eclipse. Alternatively, there is also an [http://www.eclipse.org/downloads/ installer] available.
# After the installation of Eclipse, check that your Eclipse is set to use the right Java Runtime Environment (JRE):
#* In Eclipse platform, open "Window - Preferences".
#* Open page “Java / Installed JREs”.
#* Set the JRE to point to the previously installed JDK 8.
# Install the Simantics Graph Compiler:
#* In Eclipse platform, open “Help / Install New Software...”.
#* Set the installation site to "http://www.simantics.org/update/utils" in the “Work with” field and press “Add...”. Give the installation site link a name when asked.
#* Select from the list the latest "Ontology development / Graph feature" and proceed with the installation. Restart Eclipse after the installation.
# Install the Subversive plug-in to the Eclipse platform:
#* In Eclipse platform, open ''“Help / Install New Software...”''.
#* Select installation site "Mars - http://download.eclipse.org/releases/mars" to the “Work with” field from the preset list.
#* Click open the "Collaboration" folder and select from the list:
#** ''Subversive SVN Team Provider''
#** ''Subversive SVN JDT Ignore Extensions''
#: and proceed with the installation. Restart Eclipse after the installation.
# After restarting Eclipse, open the SVN Repository Exploring perspective:
#* In Eclipse platform, open “Window / Open Perspective / Other...”.
#* Select ''SVN Repository Exploring'' and press “OK”. Eclipse should open the “Install Connectors” dialog.
#* Select latest “SVN Kit 1.x.y” and press “Finish”, and proceed with the installation. Restart Eclipse after the installation.

== Install Latest Simantics Target Platform ==

# In Eclipse platform, activate the ''Plug-in Development'' perspective, either from the tab on the upper right corner of the Eclipse platform or from the “Window / Open Perspective / Other...” menu, and select ''Plug-in Development''.
# Create a new general project in Eclipse by:
#* Selecting “File / New / Project...” menu item.
#* In the "Select a wizard", select “General / Project” and press “Next”.
#* Give the project a name, e.g. "Simantics_target" and press "Finish".
# Copy one of the following files into your system to some temporary location:
#* [http://www.simantics.org/download/latest/simantics.target http://www.simantics.org/download/latest/simantics.target] (for application development on Simantics platform)
#: The Simantics platform source code is available for [https://www.simantics.org/simantics/about-simantics/thth-simantics THTH/Simantics Division] registered members through these alternative target definitions (user name and password are asked during the installation, these are available at the [https://www.simantics.org/members/index.php/Main_Page THTH/Simantics Member Wiki]):
#* [http://www.simantics.org/download/latest/simantics-sdk.target http://www.simantics.org/download/latest/simantics-sdk.target] (for Simantics platform development and application development on Simantics platform)
# In Eclipse ''Package Explorer'' (the view on left side of the Eclipse platform):
#* Right-click your previously created project and select "Import..." from the context menu.
#* In ''Select wizard'', select “General / File System”, and press "Next".
#* Select in the “From directory” the folder where the previously downloaded file(s) are located, and select the downloaded file(s) in the file list below. Press "Finish".
# Set the target platform for the development with Simantics:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* The new target definitions should be available in the list. Activate one of the following:
#** “Simantics x.y” (for application development on Simantics platform)
#** “Simantics SDK x.y” (for Simantics platform development and application development on Simantics platform)
#: and confirm the target platform definition by pressing "Apply" and/or "OK". If you defined a ''Simantics SDK x.y'' target, you are asked for the username and the password.
#* Wait until Eclipse finishes downloading, this may take a while. After the download is completed, there should be several plug-ins starting with "org.simantics.*" in the Eclipse ''Plug-ins'' view (the view on the left side of Eclipse).
# '''Keep your platform up-to-date!''' Updating is as easy as reloading the target platform from ''Target Platform'' preference page:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* Select the active target platform, e.g. ''Simantics SDK x.y'', from the list and press "Reload".
#* Wait until the platform is updated.

== Test Your Installation ==

Test your installation with the [http://dev.simantics.org/index.php/Tutorial:_Ontology_Development Simantics movie tutorial]:

# Download ''Simantics movie tutorial'' plug-ins into your Eclipse workspace:
#* Get [https://www.simantics.org/jenkins/job/Tutorials/job/package-movie-tutorial-head/lastSuccessfulBuild/artifact/movie-tutorial.zip]
#* In Eclipse platform, select “File / Import...” menu item.
#* In the "Select" dialog, select “General / Existing Projects into Workspace” and press “Next”.
#* Select the “Select archive file:” radio button and press “Browse” to find the downloaded movie-tutorial.zip.
#* Press “Select All” and “Finish”.
# Run movie.product:
#* From the ''Package Explorer'' view, open “org.simantics.movie.ui'' / Movie.product”.
#* From the ''Overview'' page of the opened product editor, press “Launch an Eclipse application”.

If you managed to start the ''movie'' product, your development platform should be operational.

'''''Happy developing with Simantics!'''''

Quick Development Environment Setup

2017-06-05T05:24:24Z

Hannu Niemisto:

__TOC__

== Install Java JDK and Eclipse, and Setup the IDE for Simantics Development ==

# Get and install ''Java SE Development Kit 8'' (JDK 8). You can download the package from [http://www.oracle.com/technetwork/java/javase/downloads/index.html http://www.oracle.com/technetwork/java/javase/downloads/index.html]. Follow the installation instructions for your operating system. It is recommended to always use the latest JDK update.
# Get and install the latest 64-bit ''Eclipse Classic IDE'' release build. You can find the package from [http://download.eclipse.org/eclipse/downloads/ http://download.eclipse.org/eclipse/downloads/]. You can select freely the installation location for the package, e.g. under your home directory. Just unzip the package to install Eclipse. Alternatively, there is also an [http://www.eclipse.org/downloads/ installer] available.
# After the installation of Eclipse, check that your Eclipse is set to use the right Java Runtime Environment (JRE):
#* In Eclipse platform, open "Window - Preferences".
#* Open page “Java / Installed JREs”.
#* Set the JRE to point to the previously installed JDK 8.
# Install the Simantics Graph Compiler:
#* In Eclipse platform, open “Help / Install New Software...”.
#* Set the installation site to "http://www.simantics.org/update/utils" in the “Work with” field and press “Add...”. Give the installation site link a name when asked.
#* Select from the list the latest "Ontology development / Graph feature" and proceed with the installation. Restart Eclipse after the installation.
# Install the Subversive plug-in to the Eclipse platform:
#* In Eclipse platform, open ''“Help / Install New Software...”''.
#* Select installation site "Mars - http://download.eclipse.org/releases/mars" to the “Work with” field from the preset list.
#* Click open the "Collaboration" folder and select from the list:
#** ''Subversive SVN Team Provider''
#** ''Subversive SVN JDT Ignore Extensions''
#: and proceed with the installation. Restart Eclipse after the installation.
# After restarting Eclipse, open the SVN Repository Exploring perspective:
#* In Eclipse platform, open “Window / Open Perspective / Other...”.
#* Select ''SVN Repository Exploring'' and press “OK”. Eclipse should open the “Install Connectors” dialog.
#* Select latest “SVN Kit 1.x.y” and press “Finish”, and proceed with the installation. Restart Eclipse after the installation.

== Install Latest Simantics Target Platform ==

# In Eclipse platform, activate the ''Plug-in Development'' perspective, either from the tab on the upper right corner of the Eclipse platform or from the “Window / Open Perspective / Other...” menu, and select ''Plug-in Development''.
# Create a new general project in Eclipse by:
#* Selecting “File / New / Project...” menu item.
#* In the "Select a wizard", select “General / Project” and press “Next”.
#* Give the project a name, e.g. "Simantics_target" and press "Finish".
# Copy one of the following files into your system to some temporary location:
#* [http://www.simantics.org/download/latest/simantics.target http://www.simantics.org/download/latest/simantics.target] (for application development on Simantics platform)
#: The Simantics platform source code is available for [https://www.simantics.org/simantics/about-simantics/thth-simantics THTH/Simantics Division] registered members through these alternative target definitions (user name and password are asked during the installation, these are available at the [https://www.simantics.org/members/index.php/Main_Page THTH/Simantics Member Wiki]):
#* [http://www.simantics.org/download/latest/simantics-sdk.target http://www.simantics.org/download/latest/simantics-sdk.target] (for Simantics platform development and application development on Simantics platform)
# In Eclipse ''Package Explorer'' (the view on left side of the Eclipse platform):
#* Right-click your previously created project and select "Import..." from the context menu.
#* In ''Select wizard'', select “General / File System”, and press "Next".
#* Select in the “From directory” the folder where the previously downloaded file(s) are located, and select the downloaded file(s) in the file list below. Press "Finish".
# Set the target platform for the development with Simantics:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* The new target definitions should be available in the list. Activate one of the following:
#** “Simantics x.y” (for application development on Simantics platform)
#** “Simantics SDK x.y” (for Simantics platform development and application development on Simantics platform)
#: and confirm the target platform definition by pressing "Apply" and/or "OK". If you defined a ''Simantics SDK x.y'' target, you are asked for the username and the password.
#* Wait until Eclipse finishes downloading, this may take a while. After the download is completed, there should be several plug-ins starting with "org.simantics.*" in the Eclipse ''Plug-ins'' view (the view on the left side of Eclipse).
# '''Keep your platform up-to-date!''' Updating is as easy as reloading the target platform from ''Target Platform'' preference page:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* Select the active target platform, e.g. ''Simantics SDK x.y'', from the list and press "Reload".
#* Wait until the platform is updated.

== Test Your Installation ==

Test your installation with the [http://dev.simantics.org/index.php/Tutorial:_Ontology_Development Simantics movie tutorial]:

# Download ''Simantics movie tutorial'' plug-ins into your Eclipse workspace:
#* Get [https://www.simantics.org/jenkins/job/Tutorials/job/package-movie-tutorial-head/lastSuccessfulBuild/artifact/movie-tutorial.zip]
#* In Eclipse platform, select “File / Import...” menu item.
#* In the "Select" dialog, select “General / Existing Projects into Workspace” and press “Next”.
#* Select the “Select archive file:” radio button and press “Browse” to find the downloaded movie-tutorial.zip.
#* Press “Select All” and “Finish”.
# Run movie.product:
#* From the ''Package Explorer'' view, open “org.simantics.movie.ui'' / Movie.product”.
#* From the ''Overview'' page of the opened product editor, press “Launch an Eclipse application”.

If you managed to start the ''movie'' product, your development platform should be operational.

'''''Happy developing with Simantics!'''''

Quick Development Environment Setup

2017-06-05T05:23:52Z

Hannu Niemisto:

__TOC__

== Install Java JDK and Eclipse, and Setup the IDE for Simantics Development ==

# Get and install ''Java SE Development Kit 8'' (JDK 8). You can download the package from [http://www.oracle.com/technetwork/java/javase/downloads/index.html http://www.oracle.com/technetwork/java/javase/downloads/index.html]. Follow the installation instructions for your operating system. It is recommended to always use the latest JDK update.
# Get and install the latest ''Eclipse Classic IDE'' release build. You can find the package from [http://download.eclipse.org/eclipse/downloads/ http://download.eclipse.org/eclipse/downloads/]. You can select freely the installation location for the package, e.g. under your home directory. Just unzip the package to install Eclipse. Alternatively, there is also an [http://www.eclipse.org/downloads/ installer] available.
# After the installation of Eclipse, check that your Eclipse is set to use the right Java Runtime Environment (JRE):
#* In Eclipse platform, open "Window - Preferences".
#* Open page “Java / Installed JREs”.
#* Set the JRE to point to the previously installed JDK 8.
# Install the Simantics Graph Compiler:
#* In Eclipse platform, open “Help / Install New Software...”.
#* Set the installation site to "http://www.simantics.org/update/utils" in the “Work with” field and press “Add...”. Give the installation site link a name when asked.
#* Select from the list the latest "Ontology development / Graph feature" and proceed with the installation. Restart Eclipse after the installation.
# Install the Subversive plug-in to the Eclipse platform:
#* In Eclipse platform, open ''“Help / Install New Software...”''.
#* Select installation site "Mars - http://download.eclipse.org/releases/mars" to the “Work with” field from the preset list.
#* Click open the "Collaboration" folder and select from the list:
#** ''Subversive SVN Team Provider''
#** ''Subversive SVN JDT Ignore Extensions''
#: and proceed with the installation. Restart Eclipse after the installation.
# After restarting Eclipse, open the SVN Repository Exploring perspective:
#* In Eclipse platform, open “Window / Open Perspective / Other...”.
#* Select ''SVN Repository Exploring'' and press “OK”. Eclipse should open the “Install Connectors” dialog.
#* Select latest “SVN Kit 1.x.y” and press “Finish”, and proceed with the installation. Restart Eclipse after the installation.

== Install Latest Simantics Target Platform ==

# In Eclipse platform, activate the ''Plug-in Development'' perspective, either from the tab on the upper right corner of the Eclipse platform or from the “Window / Open Perspective / Other...” menu, and select ''Plug-in Development''.
# Create a new general project in Eclipse by:
#* Selecting “File / New / Project...” menu item.
#* In the "Select a wizard", select “General / Project” and press “Next”.
#* Give the project a name, e.g. "Simantics_target" and press "Finish".
# Copy one of the following files into your system to some temporary location:
#* [http://www.simantics.org/download/latest/simantics.target http://www.simantics.org/download/latest/simantics.target] (for application development on Simantics platform)
#: The Simantics platform source code is available for [https://www.simantics.org/simantics/about-simantics/thth-simantics THTH/Simantics Division] registered members through these alternative target definitions (user name and password are asked during the installation, these are available at the [https://www.simantics.org/members/index.php/Main_Page THTH/Simantics Member Wiki]):
#* [http://www.simantics.org/download/latest/simantics-sdk.target http://www.simantics.org/download/latest/simantics-sdk.target] (for Simantics platform development and application development on Simantics platform)
# In Eclipse ''Package Explorer'' (the view on left side of the Eclipse platform):
#* Right-click your previously created project and select "Import..." from the context menu.
#* In ''Select wizard'', select “General / File System”, and press "Next".
#* Select in the “From directory” the folder where the previously downloaded file(s) are located, and select the downloaded file(s) in the file list below. Press "Finish".
# Set the target platform for the development with Simantics:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* The new target definitions should be available in the list. Activate one of the following:
#** “Simantics x.y” (for application development on Simantics platform)
#** “Simantics SDK x.y” (for Simantics platform development and application development on Simantics platform)
#: and confirm the target platform definition by pressing "Apply" and/or "OK". If you defined a ''Simantics SDK x.y'' target, you are asked for the username and the password.
#* Wait until Eclipse finishes downloading, this may take a while. After the download is completed, there should be several plug-ins starting with "org.simantics.*" in the Eclipse ''Plug-ins'' view (the view on the left side of Eclipse).
# '''Keep your platform up-to-date!''' Updating is as easy as reloading the target platform from ''Target Platform'' preference page:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* Select the active target platform, e.g. ''Simantics SDK x.y'', from the list and press "Reload".
#* Wait until the platform is updated.

== Test Your Installation ==

Test your installation with the [http://dev.simantics.org/index.php/Tutorial:_Ontology_Development Simantics movie tutorial]:

# Download ''Simantics movie tutorial'' plug-ins into your Eclipse workspace:
#* Get [https://www.simantics.org/jenkins/job/Tutorials/job/package-movie-tutorial-head/lastSuccessfulBuild/artifact/movie-tutorial.zip]
#* In Eclipse platform, select “File / Import...” menu item.
#* In the "Select" dialog, select “General / Existing Projects into Workspace” and press “Next”.
#* Select the “Select archive file:” radio button and press “Browse” to find the downloaded movie-tutorial.zip.
#* Press “Select All” and “Finish”.
# Run movie.product:
#* From the ''Package Explorer'' view, open “org.simantics.movie.ui'' / Movie.product”.
#* From the ''Overview'' page of the opened product editor, press “Launch an Eclipse application”.

If you managed to start the ''movie'' product, your development platform should be operational.

'''''Happy developing with Simantics!'''''

Development Environment Setup Guide

2017-06-05T05:17:10Z

Hannu Niemisto: /* Install Prerequisites */

== Install Prerequisites ==
=== Register to access source code ===

{{tip|Simantics is an open source software platform, licensed under Eclipse Public License EPL (more information in section [https://www.simantics.org/about/licensing Licensing]). The source code for both semantic database engine Simantics Core and the client Simantics Workbench is available to '''registered users'''. To gain access to the complete Simantics SDK source code, go to the [https://www.simantics.org/members/index.php Simantics Members Wiki] and [https://www.simantics.org/members/index.php/Special:RequestAccount request an account].}}

=== JDK ===
* 64-bit JDK 8.0 (= Java Standard Edition Development Kit) is required. The latest update should always work. Get it [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html here].

=== Eclipse IDE ===

* Get the latest 64-bit Eclipse (currently Neon): http://www.eclipse.org/downloads/
* In the installer, choose ''Eclipse for RCP and RAP Developers''

* Start Eclipse with a new empty workspace. The program will query you for the workspace location.

[[Image:InstalledJREs.png|right|100px|thumb|Java VM selection preference page]]

* If you have multiple JRE/JDK versions installed, check that your Eclipse is using the the right one from ''Window/Preferences'': ''Java/Installed JREs'' as shown below. For example in Windows the active JRE and JDK locations should be something like:
** '''C:\Program Files\Java\jre8_<update number>'''
** '''C:\Program Files\Java\jdk1.8.0_<update number>'''

=== IMPORTANT: HTTP proxy ===
If you are on a network where the only way to access the internet via HTTP is through an HTTP proxy you need to make sure that Eclipse also uses this proxy. Corporate networks tend to be like this. If you do not do this, you cannot install anything using Eclipse's own plug-in installer.

Open the preferences dialog from main menu '''Window/Preferences'''. From the tree on the left go to '''General/Network Connections''' and modify the settings so that HTTP connections are checked to have a proxy.

=== Simantics Tooling ===

Select menu '''Help/Install New Software''' and write http://www.simantics.org/update/utils into the ''Work with'' text field. Install the latest ''Ontology Development/Graph Feature''. This provides the possibility to create ''Simantics Ontology Projects'', i.e. allows IDE integrated development of the ontologies (data models) used in the Simantics application you are developing.

See [[org.simantics.graph]] for the component's documentation.

=== Eclipse plug-in for Subversion ===

{{tip|With Simantics 1.4 and future releases this step is optional.}}

Simantics uses Subversion ([http://subversion.apache.org/ SVN]) as a version control system ([http://en.wikipedia.org/wiki/Revision_control VCS]) for storing all of our source code. To access this data from neatly from Eclipse, you need to install some plug-ins into it. To install the plug-in, follow these instructions:

* Install Subversion plug-in: [http://www.eclipse.org/subversive/ Eclipse Subversive]. Update Site is a part of Helios Update Site. From the main menu, open Help > Install New Software...
*# [[Image:Install_connectors.png|right|100px|thumb|SVN connector installation dialog]] From the ''Work with'' selector, select Helios - http://download.eclipse.org/releases/helios
*#* From the ''Collaboration'' folder, select the following items:
*#** '''Subversive SVN Team Provider'''
*#** '''Subversive SVN JDT Ignore Extensions'''
*#* Select Finish and watch the installation proceed
*#* Click ''Restart Now'' after the installation completes
*# After restarting, open the '''SVN Repository Exploring''' perspective and Eclipse should open a dialog called '''Install Connectors'''. Select '''SVN Kit 1.3.x''' and press finish.

* NOTE: if this installation process fails, this means that Eclipse is offering broken/incompatible packages at the moment. In this case you probably need to install the latest ''early access'' versions using http://www.eclipse.org/subversive/downloads.php#early_access

* Be warned that there has been a bug in Subversive which causes it to use the HTTP proxy for HTTPS addresses too. In order to get your SVN connection to www.simantics.org working, you may need to use direct connection proxy settings after installing the SVN plug-ins.

== Setup IDE ==

* Import Simantics Java formatting rules into your Eclipse: [[Media:Simantics-Java-Formatting.xml | save this XML file]]
** In Eclipse: ''Window/Preferences'' and the ''Java/Code Style/Formatter'' folder, select ''Import...'' and find the XML file you just downloaded.
* From the same preferences dialog also make sure that JDK 6.0 (or JRE 1.6) compliance is enabled:
*: [[Image:java_compiler_preferences.png|400px]]
* Optionally enable Save Actions: ''Java/Editor/Save Actions'':
** enable ''Organize imports''
** enable ''Additional actions''
** enable ''Format source code'' (not always recommendable)
** ''Configure'': ''Code Organizing'': Enable ''Remove trailing whitespace'' and ''Correct indentation''

== Download Simantics ==

=== Simantics 1.4+ Instructions ===

Follow the instructions on the [[Target Platform#Simantics 1.4|Target Platform page]] to set the Simantics 1.4 target platform up for your workspace.

=== Pre-Simantics 1.4 Instructions ===

==== Install Simantics target platform ====
The target platform is a set of Simantics and Eclipse features and plug-ins that constitute the components you can build your Simantics/Eclipse-based software out of. These are needed as base to get working on your own contributions on top of the Simantics platform.

To get the platform one must perform a [http://svnbook.red-bean.com/en/1.5/svn.tour.initial.html''checkout''] from the SVN repository. You can use Eclipse's '''SVN Repository Exploring perspective''' for this task. You can also use other tools, such as [http://tortoisesvn.net TortoiseSVN] or the [http://subversion.tigris.org/getting.html#binary-packages SVN command line client].

<blockquote>
{{questionanswer|'''How do I ''check out'' from SVN in Eclipse in general?'''|
[[Image:new_repository_location.png|right|100px]]
* Switch to the '''SVN Repository Exploring''' perspective.
* In the ''SVN Repositories'' view, from the context menu, select ''New → Repository Location''.
* Enter the SVN repository location in the URL field and enter your repository credentials in the authentication fields.
* Browse the added repository tree, select the directory/project you want to access and edit, and select '''Check out''' from the context menu.
}}
</blockquote>

# '''Checkout the target platform''' for your version into a directory of your choice. See [[Target Platform]] for available versions.
#* Updating your target platform is now a matter of updating your target platform working copy.
#* Upgrading to newer versions of the target platform requires switching to/checking out another branch of the target platform.
# '''Import the target platform into your eclipse IDE''':
#* If you checked out the target platform using another tool besides Eclipse, first import the target platform into your workspace:
#** ''File/Import'': ''General/Existing Project into Workspace'': Select target platform location as ''root directory''. '''Deselect''' ''Copy projects into workspace'' if selected. Press ''Finish''.
#* Select menu item ''Window/Preferences'' from your Eclipse IDE.
#* Open the preference page Plug-in Development/Target Platform.
#* Activate your target platform definition by checking it and press OK.

==== Download Simantics Components ====

===== Add Simantics repositories =====
* Switch to ''SVN Repository Exploring'' perspective in Eclipse.
* Add the main Simantics repository location in the SVN Repository view:
** General tab:
*** URL = https://www.simantics.org/svn/simantics/
*** Authentication =
**** '''Committers:''' your username and password

===== Checkout Simantics sources =====
* Checkout the proper project sets into your workspace. Eclipse will check it out as ''ProjectSets'':
** '''Simantics development version''': ''project-set/trunk''

* Switch to ''Java perspective''.
* To speed up the download, disable automatic building from menu toggle ''Project/Build Automatically''.
* From the ''Package Explorer'' view, pick '''simantics.psf''' file from the ProjectSets folder and select ''Import Project Set'' from the popup menu.
* Re-enable automatic building
* '''IMPORTANT''': If checked out code does not compile/work, consult the [[Plugins|maintainers of the non-working module]].

===== Troubleshooting =====

* If the project set import fails or does not do anything, please update your SVN plug-ins to the latest versions available.

=== Start Development ===

To get started on development, continue to '''[[Tutorial: Ontology Development]]'''.

== Basic IDE Usage ==
=== Running Products from the IDE ===

* Create a '''Product Configuration''' (.product) for your own product.
** You can use '''[https://www.simulationsite.net/trac/simantics/browser/sysdyn/trunk/org.simantics.sysdyn.ui/sysdyn.product sysdyn.product]''' as a starting point for your own product configuration. To get '''sysdyn.product''', import the '''sysdyn.psf''' project-set.
** Be sure to only include the components that you want to have in your product, nothing more.

: [[Image:SimanticsWorkbenchProduct.png|500px]]
* Launch the product from the links under the ''Testing'' section

* When launching the Simantics Workbench application from the IDE, i.e. in development mode, the application will make sure that your application workspace will contain a Simantics database that contains the transferable graphs contained by the ontology project bundles that are included in your product's plug-in configuration.
** Be warned that the application can't handle all cases of modified database contents. This means that sometimes the easiest way to get your application running is clearing your application's workspace and starting with a fresh database.

; IMPORTANT DEVELOPER NOTICE

Remember to always launch your application using the .product configuration editor as described above when you want to make sure that your IDE's application launcher configuration is up-to-date. The launcher configurations contain the set of plug-ins that are installed into the launched application which means which is not updated when the application is launched through the menu or (Ctrl+)F11.

The launcher configurations will most likely require updating when you
# take new plug-ins into use (add them to features included by the product)
# remove plug-ins from use
# plug-ins are moved from the workspace to the target platform or vice versa
# the target platform is updated

=== Testing your own contributions with Simantics ===

; Scenario - Testing a set of new plug-ins

Prerequisites:
# Some of the added plug-ins may contain ontologies.
# You've created your own set of plug-ins based on the Simantics SDK.
# You've defined ''features'' that include your plug-ins.
# You've followed the instructions at [[#Building]]

Steps to follow:
# If you have not already created a product definition for yourself:
## Optionally create a new plug-in project with the name ''product'' in it
## Add a new ''Product Configuration'' to an existing or a new plug-in with basic settings
## Open the new .product file with ''Product Configuration Editor''
## From the ''Overview'' tab, ''Product Definition'' section, select '''org.simantics.workbench.application''' as the application and create a new product extension with the ''New'' button beside the product selector. Also mark the product definition ''feature based''.
# Configure the product to your liking, i.e. add the features you need to it
# Launch your product from the product configuration editor ''Overview'' tab

=== Product Deployment ===

Deploying a product in this context means taking a certain set of features and plug-ins and packaging into an installable and executable application.

; Things to ensure before deploying your product:
# '''Ensure correctness of your build.properties files'''
#* For each of your own bundles (plug-ins and features), check that their ''build.properties'' files contain all the necessary files within each bundle. For example '''adapters.xml''' is often forgotten from the build since there is currently no automation that would add it to the build.
# '''Ensure validity of .product definition:'''
#* Open your .product file in the Eclipse IDE (use Ctrl-Shift-R for searching)
#* On the ''Launching'' page:
#** Set '''Launcher Name''' to set the name of your product executable.
#** Under '''Program Arguments:''', add -fixerrors. This ensures that your product will initialize all new workspaces with a database instead of assuming that a database must already pre-exist.
#** Under '''VM Arguments:''' add at least '''-ea''' to enable VM assertions.

; Deploying Executable Product
* Open .product file in the Eclipse IDE (use Ctrl-Shift-R for searching)
* On the ''Overview'' page of the product editor, select ''Eclipse Product export wizard'' from under '''Exporting'''
* Fill in any missing details in the dialog and select Finish.
** To create a directly executable product, you need to deselect '''Generate metadata repository'''.
** To create a product deployable with [http://wiki.eclipse.org/Equinox/p2/Director_application P2 director] (and in the future [[SPM]]), you need to select '''Generate metadata repository'''. This will generate an [http://wiki.eclipse.org/Equinox/p2 Eclipse P2] repository.

[[Category: Miscellaneous Documents]]

Development Environment Setup Guide

2017-06-05T05:15:53Z

Hannu Niemisto: /* Install Prerequisites */

== Install Prerequisites ==
=== Register to access source code ===

{{tip|Simantics is an open source software platform, licensed under Eclipse Public License EPL (more information in section [https://www.simantics.org/about/licensing Licensing]). The source code for both semantic database engine Simantics Core and the client Simantics Workbench is available to '''registered users'''. To gain access to the complete Simantics SDK source code, go to the [https://www.simantics.org/members/index.php Simantics Members Wiki] and [https://www.simantics.org/members/index.php/Special:RequestAccount request an account].}}

=== JDK ===
* 64-bit JDK 8.0 (= Java Standard Edition Development Kit) is required. The latest update should always work. Get it [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html here].

=== Eclipse IDE ===

* Get the latest 64-bit Eclipse (currently Neon): http://www.eclipse.org/downloads/
* In the installer, choose ''Eclipse for RCP and RAP Developers''

* Start Eclipse with a new empty workspace by launching the executable within the package. The program will query you for the workspace location.

[[Image:InstalledJREs.png|right|100px|thumb|Java VM selection preference page]]

* If you have multiple JRE/JDK versions installed, check that your Eclipse is using the the right one from ''Window/Preferences'': ''Java/Installed JREs'' as shown below. For example in Windows the active JRE and JDK locations should be something like:
** '''C:\Program Files\Java\jre8_<update number>'''
** '''C:\Program Files\Java\jdk1.8.0_<update number>'''

=== IMPORTANT: HTTP proxy ===
If you are on a network where the only way to access the internet via HTTP is through an HTTP proxy you need to make sure that Eclipse also uses this proxy. Corporate networks tend to be like this. If you do not do this, you cannot install anything using Eclipse's own plug-in installer.

Open the preferences dialog from main menu '''Window/Preferences'''. From the tree on the left go to '''General/Network Connections''' and modify the settings so that HTTP connections are checked to have a proxy.

=== Simantics Tooling ===

Select menu '''Help/Install New Software''' and write http://www.simantics.org/update/utils into the ''Work with'' text field. Install the latest ''Ontology Development/Graph Feature''. This provides the possibility to create ''Simantics Ontology Projects'', i.e. allows IDE integrated development of the ontologies (data models) used in the Simantics application you are developing.

See [[org.simantics.graph]] for the component's documentation.

=== Eclipse plug-in for Subversion ===

{{tip|With Simantics 1.4 and future releases this step is optional.}}

Simantics uses Subversion ([http://subversion.apache.org/ SVN]) as a version control system ([http://en.wikipedia.org/wiki/Revision_control VCS]) for storing all of our source code. To access this data from neatly from Eclipse, you need to install some plug-ins into it. To install the plug-in, follow these instructions:

* Install Subversion plug-in: [http://www.eclipse.org/subversive/ Eclipse Subversive]. Update Site is a part of Helios Update Site. From the main menu, open Help > Install New Software...
*# [[Image:Install_connectors.png|right|100px|thumb|SVN connector installation dialog]] From the ''Work with'' selector, select Helios - http://download.eclipse.org/releases/helios
*#* From the ''Collaboration'' folder, select the following items:
*#** '''Subversive SVN Team Provider'''
*#** '''Subversive SVN JDT Ignore Extensions'''
*#* Select Finish and watch the installation proceed
*#* Click ''Restart Now'' after the installation completes
*# After restarting, open the '''SVN Repository Exploring''' perspective and Eclipse should open a dialog called '''Install Connectors'''. Select '''SVN Kit 1.3.x''' and press finish.

* NOTE: if this installation process fails, this means that Eclipse is offering broken/incompatible packages at the moment. In this case you probably need to install the latest ''early access'' versions using http://www.eclipse.org/subversive/downloads.php#early_access

* Be warned that there has been a bug in Subversive which causes it to use the HTTP proxy for HTTPS addresses too. In order to get your SVN connection to www.simantics.org working, you may need to use direct connection proxy settings after installing the SVN plug-ins.

== Setup IDE ==

* Import Simantics Java formatting rules into your Eclipse: [[Media:Simantics-Java-Formatting.xml | save this XML file]]
** In Eclipse: ''Window/Preferences'' and the ''Java/Code Style/Formatter'' folder, select ''Import...'' and find the XML file you just downloaded.
* From the same preferences dialog also make sure that JDK 6.0 (or JRE 1.6) compliance is enabled:
*: [[Image:java_compiler_preferences.png|400px]]
* Optionally enable Save Actions: ''Java/Editor/Save Actions'':
** enable ''Organize imports''
** enable ''Additional actions''
** enable ''Format source code'' (not always recommendable)
** ''Configure'': ''Code Organizing'': Enable ''Remove trailing whitespace'' and ''Correct indentation''

== Download Simantics ==

=== Simantics 1.4+ Instructions ===

Follow the instructions on the [[Target Platform#Simantics 1.4|Target Platform page]] to set the Simantics 1.4 target platform up for your workspace.

=== Pre-Simantics 1.4 Instructions ===

==== Install Simantics target platform ====
The target platform is a set of Simantics and Eclipse features and plug-ins that constitute the components you can build your Simantics/Eclipse-based software out of. These are needed as base to get working on your own contributions on top of the Simantics platform.

To get the platform one must perform a [http://svnbook.red-bean.com/en/1.5/svn.tour.initial.html''checkout''] from the SVN repository. You can use Eclipse's '''SVN Repository Exploring perspective''' for this task. You can also use other tools, such as [http://tortoisesvn.net TortoiseSVN] or the [http://subversion.tigris.org/getting.html#binary-packages SVN command line client].

<blockquote>
{{questionanswer|'''How do I ''check out'' from SVN in Eclipse in general?'''|
[[Image:new_repository_location.png|right|100px]]
* Switch to the '''SVN Repository Exploring''' perspective.
* In the ''SVN Repositories'' view, from the context menu, select ''New → Repository Location''.
* Enter the SVN repository location in the URL field and enter your repository credentials in the authentication fields.
* Browse the added repository tree, select the directory/project you want to access and edit, and select '''Check out''' from the context menu.
}}
</blockquote>

# '''Checkout the target platform''' for your version into a directory of your choice. See [[Target Platform]] for available versions.
#* Updating your target platform is now a matter of updating your target platform working copy.
#* Upgrading to newer versions of the target platform requires switching to/checking out another branch of the target platform.
# '''Import the target platform into your eclipse IDE''':
#* If you checked out the target platform using another tool besides Eclipse, first import the target platform into your workspace:
#** ''File/Import'': ''General/Existing Project into Workspace'': Select target platform location as ''root directory''. '''Deselect''' ''Copy projects into workspace'' if selected. Press ''Finish''.
#* Select menu item ''Window/Preferences'' from your Eclipse IDE.
#* Open the preference page Plug-in Development/Target Platform.
#* Activate your target platform definition by checking it and press OK.

==== Download Simantics Components ====

===== Add Simantics repositories =====
* Switch to ''SVN Repository Exploring'' perspective in Eclipse.
* Add the main Simantics repository location in the SVN Repository view:
** General tab:
*** URL = https://www.simantics.org/svn/simantics/
*** Authentication =
**** '''Committers:''' your username and password

===== Checkout Simantics sources =====
* Checkout the proper project sets into your workspace. Eclipse will check it out as ''ProjectSets'':
** '''Simantics development version''': ''project-set/trunk''

* Switch to ''Java perspective''.
* To speed up the download, disable automatic building from menu toggle ''Project/Build Automatically''.
* From the ''Package Explorer'' view, pick '''simantics.psf''' file from the ProjectSets folder and select ''Import Project Set'' from the popup menu.
* Re-enable automatic building
* '''IMPORTANT''': If checked out code does not compile/work, consult the [[Plugins|maintainers of the non-working module]].

===== Troubleshooting =====

* If the project set import fails or does not do anything, please update your SVN plug-ins to the latest versions available.

=== Start Development ===

To get started on development, continue to '''[[Tutorial: Ontology Development]]'''.

== Basic IDE Usage ==
=== Running Products from the IDE ===

* Create a '''Product Configuration''' (.product) for your own product.
** You can use '''[https://www.simulationsite.net/trac/simantics/browser/sysdyn/trunk/org.simantics.sysdyn.ui/sysdyn.product sysdyn.product]''' as a starting point for your own product configuration. To get '''sysdyn.product''', import the '''sysdyn.psf''' project-set.
** Be sure to only include the components that you want to have in your product, nothing more.

: [[Image:SimanticsWorkbenchProduct.png|500px]]
* Launch the product from the links under the ''Testing'' section

* When launching the Simantics Workbench application from the IDE, i.e. in development mode, the application will make sure that your application workspace will contain a Simantics database that contains the transferable graphs contained by the ontology project bundles that are included in your product's plug-in configuration.
** Be warned that the application can't handle all cases of modified database contents. This means that sometimes the easiest way to get your application running is clearing your application's workspace and starting with a fresh database.

; IMPORTANT DEVELOPER NOTICE

Remember to always launch your application using the .product configuration editor as described above when you want to make sure that your IDE's application launcher configuration is up-to-date. The launcher configurations contain the set of plug-ins that are installed into the launched application which means which is not updated when the application is launched through the menu or (Ctrl+)F11.

The launcher configurations will most likely require updating when you
# take new plug-ins into use (add them to features included by the product)
# remove plug-ins from use
# plug-ins are moved from the workspace to the target platform or vice versa
# the target platform is updated

=== Testing your own contributions with Simantics ===

; Scenario - Testing a set of new plug-ins

Prerequisites:
# Some of the added plug-ins may contain ontologies.
# You've created your own set of plug-ins based on the Simantics SDK.
# You've defined ''features'' that include your plug-ins.
# You've followed the instructions at [[#Building]]

Steps to follow:
# If you have not already created a product definition for yourself:
## Optionally create a new plug-in project with the name ''product'' in it
## Add a new ''Product Configuration'' to an existing or a new plug-in with basic settings
## Open the new .product file with ''Product Configuration Editor''
## From the ''Overview'' tab, ''Product Definition'' section, select '''org.simantics.workbench.application''' as the application and create a new product extension with the ''New'' button beside the product selector. Also mark the product definition ''feature based''.
# Configure the product to your liking, i.e. add the features you need to it
# Launch your product from the product configuration editor ''Overview'' tab

=== Product Deployment ===

Deploying a product in this context means taking a certain set of features and plug-ins and packaging into an installable and executable application.

; Things to ensure before deploying your product:
# '''Ensure correctness of your build.properties files'''
#* For each of your own bundles (plug-ins and features), check that their ''build.properties'' files contain all the necessary files within each bundle. For example '''adapters.xml''' is often forgotten from the build since there is currently no automation that would add it to the build.
# '''Ensure validity of .product definition:'''
#* Open your .product file in the Eclipse IDE (use Ctrl-Shift-R for searching)
#* On the ''Launching'' page:
#** Set '''Launcher Name''' to set the name of your product executable.
#** Under '''Program Arguments:''', add -fixerrors. This ensures that your product will initialize all new workspaces with a database instead of assuming that a database must already pre-exist.
#** Under '''VM Arguments:''' add at least '''-ea''' to enable VM assertions.

; Deploying Executable Product
* Open .product file in the Eclipse IDE (use Ctrl-Shift-R for searching)
* On the ''Overview'' page of the product editor, select ''Eclipse Product export wizard'' from under '''Exporting'''
* Fill in any missing details in the dialog and select Finish.
** To create a directly executable product, you need to deselect '''Generate metadata repository'''.
** To create a product deployable with [http://wiki.eclipse.org/Equinox/p2/Director_application P2 director] (and in the future [[SPM]]), you need to select '''Generate metadata repository'''. This will generate an [http://wiki.eclipse.org/Equinox/p2 Eclipse P2] repository.

[[Category: Miscellaneous Documents]]

File:InstalledJREs.png

2017-06-05T05:09:25Z

Hannu Niemisto: Hannu Niemisto uploaded a new version of "File:InstalledJREs.png"

Development Environment Setup Guide

2017-06-05T05:04:08Z

Hannu Niemisto: /* Install Prerequisites */

== Install Prerequisites ==
=== Register to access source code ===

{{tip|Simantics is an open source software platform, licensed under Eclipse Public License EPL (more information in section [https://www.simantics.org/simantics/about-simantics/licensing Licensing]). The source code for both semantic database engine Simantics Core and the client Simantics Workbench is available to '''registered users'''. To gain access to the complete Simantics SDK source code, go to the [https://www.simantics.org/members/index.php Simantics Members Wiki] and [https://www.simantics.org/members/index.php/Special:RequestAccount request an account].}}

=== JDK ===
* 64-bit JDK 8.0 (= Java Standard Edition Development Kit) is required. The latest update should always work. Get it [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html here].

=== Eclipse IDE ===

* Get the latest 64-bit Eclipse (currently Neon): http://www.eclipse.org/downloads/
* In the installer, choose ''Eclipse for RCP and RAP Developers''

* Start Eclipse with a new empty workspace by launching the executable within the package. The program will query you for the workspace location.

[[Image:InstalledJREs.png|right|100px|thumb|Java VM selection preference page]]

* If you have multiple JRE/JDK versions installed, check that your Eclipse is using the the right one from ''Window/Preferences'': ''Java/Installed JREs'' as shown below. For example in Windows the active JRE and JDK locations should be something like:
** '''C:\Program Files\Java\jre8_<update number>'''
** '''C:\Program Files\Java\jdk1.8.0_<update number>'''

=== IMPORTANT: HTTP proxy ===
If you are on a network where the only way to access the internet via HTTP is through an HTTP proxy you need to make sure that Eclipse also uses this proxy. Corporate networks tend to be like this. If you do not do this, you cannot install anything using Eclipse's own plug-in installer.

Open the preferences dialog from main menu '''Window/Preferences'''. From the tree on the left go to '''General/Network Connections''' and modify the settings so that HTTP connections are checked to have a proxy.

=== Simantics Tooling ===

Select menu '''Help/Install New Software''' and write http://www.simantics.org/update/utils into the ''Work with'' text field. Install the latest ''Ontology Development/Graph Feature''. This provides the possibility to create ''Simantics Ontology Projects'', i.e. allows IDE integrated development of the ontologies (data models) used in the Simantics application you are developing.

See [[org.simantics.graph]] for the component's documentation.

=== Eclipse plug-in for Subversion ===

{{tip|With Simantics 1.4 and future releases this step is optional.}}

Simantics uses Subversion ([http://subversion.apache.org/ SVN]) as a version control system ([http://en.wikipedia.org/wiki/Revision_control VCS]) for storing all of our source code. To access this data from neatly from Eclipse, you need to install some plug-ins into it. To install the plug-in, follow these instructions:

* Install Subversion plug-in: [http://www.eclipse.org/subversive/ Eclipse Subversive]. Update Site is a part of Helios Update Site. From the main menu, open Help > Install New Software...
*# [[Image:Install_connectors.png|right|100px|thumb|SVN connector installation dialog]] From the ''Work with'' selector, select Helios - http://download.eclipse.org/releases/helios
*#* From the ''Collaboration'' folder, select the following items:
*#** '''Subversive SVN Team Provider'''
*#** '''Subversive SVN JDT Ignore Extensions'''
*#* Select Finish and watch the installation proceed
*#* Click ''Restart Now'' after the installation completes
*# After restarting, open the '''SVN Repository Exploring''' perspective and Eclipse should open a dialog called '''Install Connectors'''. Select '''SVN Kit 1.3.x''' and press finish.

* NOTE: if this installation process fails, this means that Eclipse is offering broken/incompatible packages at the moment. In this case you probably need to install the latest ''early access'' versions using http://www.eclipse.org/subversive/downloads.php#early_access

* Be warned that there has been a bug in Subversive which causes it to use the HTTP proxy for HTTPS addresses too. In order to get your SVN connection to www.simantics.org working, you may need to use direct connection proxy settings after installing the SVN plug-ins.

== Setup IDE ==

* Import Simantics Java formatting rules into your Eclipse: [[Media:Simantics-Java-Formatting.xml | save this XML file]]
** In Eclipse: ''Window/Preferences'' and the ''Java/Code Style/Formatter'' folder, select ''Import...'' and find the XML file you just downloaded.
* From the same preferences dialog also make sure that JDK 6.0 (or JRE 1.6) compliance is enabled:
*: [[Image:java_compiler_preferences.png|400px]]
* Optionally enable Save Actions: ''Java/Editor/Save Actions'':
** enable ''Organize imports''
** enable ''Additional actions''
** enable ''Format source code'' (not always recommendable)
** ''Configure'': ''Code Organizing'': Enable ''Remove trailing whitespace'' and ''Correct indentation''

== Download Simantics ==

=== Simantics 1.4+ Instructions ===

Follow the instructions on the [[Target Platform#Simantics 1.4|Target Platform page]] to set the Simantics 1.4 target platform up for your workspace.

=== Pre-Simantics 1.4 Instructions ===

==== Install Simantics target platform ====
The target platform is a set of Simantics and Eclipse features and plug-ins that constitute the components you can build your Simantics/Eclipse-based software out of. These are needed as base to get working on your own contributions on top of the Simantics platform.

To get the platform one must perform a [http://svnbook.red-bean.com/en/1.5/svn.tour.initial.html''checkout''] from the SVN repository. You can use Eclipse's '''SVN Repository Exploring perspective''' for this task. You can also use other tools, such as [http://tortoisesvn.net TortoiseSVN] or the [http://subversion.tigris.org/getting.html#binary-packages SVN command line client].

<blockquote>
{{questionanswer|'''How do I ''check out'' from SVN in Eclipse in general?'''|
[[Image:new_repository_location.png|right|100px]]
* Switch to the '''SVN Repository Exploring''' perspective.
* In the ''SVN Repositories'' view, from the context menu, select ''New → Repository Location''.
* Enter the SVN repository location in the URL field and enter your repository credentials in the authentication fields.
* Browse the added repository tree, select the directory/project you want to access and edit, and select '''Check out''' from the context menu.
}}
</blockquote>

# '''Checkout the target platform''' for your version into a directory of your choice. See [[Target Platform]] for available versions.
#* Updating your target platform is now a matter of updating your target platform working copy.
#* Upgrading to newer versions of the target platform requires switching to/checking out another branch of the target platform.
# '''Import the target platform into your eclipse IDE''':
#* If you checked out the target platform using another tool besides Eclipse, first import the target platform into your workspace:
#** ''File/Import'': ''General/Existing Project into Workspace'': Select target platform location as ''root directory''. '''Deselect''' ''Copy projects into workspace'' if selected. Press ''Finish''.
#* Select menu item ''Window/Preferences'' from your Eclipse IDE.
#* Open the preference page Plug-in Development/Target Platform.
#* Activate your target platform definition by checking it and press OK.

==== Download Simantics Components ====

===== Add Simantics repositories =====
* Switch to ''SVN Repository Exploring'' perspective in Eclipse.
* Add the main Simantics repository location in the SVN Repository view:
** General tab:
*** URL = https://www.simantics.org/svn/simantics/
*** Authentication =
**** '''Committers:''' your username and password

===== Checkout Simantics sources =====
* Checkout the proper project sets into your workspace. Eclipse will check it out as ''ProjectSets'':
** '''Simantics development version''': ''project-set/trunk''

* Switch to ''Java perspective''.
* To speed up the download, disable automatic building from menu toggle ''Project/Build Automatically''.
* From the ''Package Explorer'' view, pick '''simantics.psf''' file from the ProjectSets folder and select ''Import Project Set'' from the popup menu.
* Re-enable automatic building
* '''IMPORTANT''': If checked out code does not compile/work, consult the [[Plugins|maintainers of the non-working module]].

===== Troubleshooting =====

* If the project set import fails or does not do anything, please update your SVN plug-ins to the latest versions available.

=== Start Development ===

To get started on development, continue to '''[[Tutorial: Ontology Development]]'''.

== Basic IDE Usage ==
=== Running Products from the IDE ===

* Create a '''Product Configuration''' (.product) for your own product.
** You can use '''[https://www.simulationsite.net/trac/simantics/browser/sysdyn/trunk/org.simantics.sysdyn.ui/sysdyn.product sysdyn.product]''' as a starting point for your own product configuration. To get '''sysdyn.product''', import the '''sysdyn.psf''' project-set.
** Be sure to only include the components that you want to have in your product, nothing more.

: [[Image:SimanticsWorkbenchProduct.png|500px]]
* Launch the product from the links under the ''Testing'' section

* When launching the Simantics Workbench application from the IDE, i.e. in development mode, the application will make sure that your application workspace will contain a Simantics database that contains the transferable graphs contained by the ontology project bundles that are included in your product's plug-in configuration.
** Be warned that the application can't handle all cases of modified database contents. This means that sometimes the easiest way to get your application running is clearing your application's workspace and starting with a fresh database.

; IMPORTANT DEVELOPER NOTICE

Remember to always launch your application using the .product configuration editor as described above when you want to make sure that your IDE's application launcher configuration is up-to-date. The launcher configurations contain the set of plug-ins that are installed into the launched application which means which is not updated when the application is launched through the menu or (Ctrl+)F11.

The launcher configurations will most likely require updating when you
# take new plug-ins into use (add them to features included by the product)
# remove plug-ins from use
# plug-ins are moved from the workspace to the target platform or vice versa
# the target platform is updated

=== Testing your own contributions with Simantics ===

; Scenario - Testing a set of new plug-ins

Prerequisites:
# Some of the added plug-ins may contain ontologies.
# You've created your own set of plug-ins based on the Simantics SDK.
# You've defined ''features'' that include your plug-ins.
# You've followed the instructions at [[#Building]]

Steps to follow:
# If you have not already created a product definition for yourself:
## Optionally create a new plug-in project with the name ''product'' in it
## Add a new ''Product Configuration'' to an existing or a new plug-in with basic settings
## Open the new .product file with ''Product Configuration Editor''
## From the ''Overview'' tab, ''Product Definition'' section, select '''org.simantics.workbench.application''' as the application and create a new product extension with the ''New'' button beside the product selector. Also mark the product definition ''feature based''.
# Configure the product to your liking, i.e. add the features you need to it
# Launch your product from the product configuration editor ''Overview'' tab

=== Product Deployment ===

Deploying a product in this context means taking a certain set of features and plug-ins and packaging into an installable and executable application.

; Things to ensure before deploying your product:
# '''Ensure correctness of your build.properties files'''
#* For each of your own bundles (plug-ins and features), check that their ''build.properties'' files contain all the necessary files within each bundle. For example '''adapters.xml''' is often forgotten from the build since there is currently no automation that would add it to the build.
# '''Ensure validity of .product definition:'''
#* Open your .product file in the Eclipse IDE (use Ctrl-Shift-R for searching)
#* On the ''Launching'' page:
#** Set '''Launcher Name''' to set the name of your product executable.
#** Under '''Program Arguments:''', add -fixerrors. This ensures that your product will initialize all new workspaces with a database instead of assuming that a database must already pre-exist.
#** Under '''VM Arguments:''' add at least '''-ea''' to enable VM assertions.

; Deploying Executable Product
* Open .product file in the Eclipse IDE (use Ctrl-Shift-R for searching)
* On the ''Overview'' page of the product editor, select ''Eclipse Product export wizard'' from under '''Exporting'''
* Fill in any missing details in the dialog and select Finish.
** To create a directly executable product, you need to deselect '''Generate metadata repository'''.
** To create a product deployable with [http://wiki.eclipse.org/Equinox/p2/Director_application P2 director] (and in the future [[SPM]]), you need to select '''Generate metadata repository'''. This will generate an [http://wiki.eclipse.org/Equinox/p2 Eclipse P2] repository.

[[Category: Miscellaneous Documents]]

Development Environment Setup Guide

2017-06-05T04:44:29Z

Hannu Niemisto:

== Install Prerequisites ==
=== Register to access source code ===

{{tip|Simantics is an open source software platform, licensed under Eclipse Public License EPL (more information in section [https://www.simantics.org/simantics/about-simantics/licensing Licensing]). The source code for both semantic database engine Simantics Core and the client Simantics Workbench is available to '''registered users'''. To gain access to the complete Simantics SDK source code, go to the [https://www.simantics.org/members/index.php Simantics Members Wiki] and [https://www.simantics.org/members/index.php/Special:RequestAccount request an account].}}

=== JDK ===
* 64-bit JDK 8.0 (= Java Standard Edition Development Kit) is required. The latest update should always work. Get it [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html here].

=== Eclipse IDE ===

* Get the latest 64-bit Eclipse (currently Neon): http://www.eclipse.org/downloads/
* In the installer, choose ''Eclipse for RCP and RAP Developers''

* Start Eclipse with a new empty workspace by launching the executable within the package. The program will query you for the workspace location.

[[Image:InstalledJREs.png|right|100px|thumb|Java VM selection preference page]]

* If you have multiple JRE/JDK versions installed, check that your Eclipse is using the the right one from ''Window/Preferences'': ''Java/Installed JREs'' as shown below. For example in windows the active JRE and JDK locations should be something like:
** '''C:\Program Files\Java\jre6'''
** '''C:\Program Files\Java\jdk1.6.0_<update number>'''

=== IMPORTANT: HTTP proxy ===
If you are on a network where the only way to access the internet via HTTP is through an HTTP proxy you need to make sure that Eclipse also uses this proxy. Corporate networks tend to be like this. If you do not do this, you cannot install anything using Eclipse's own plug-in installer.

Open the preferences dialog from main menu '''Window/Preferences'''. From the tree on the left go to '''General/Network Connections''' and modify the settings so that HTTP connections are checked to have a proxy.

=== Simantics Tooling ===

Select menu '''Help/Install New Software''' and write http://www.simantics.org/update/utils into the ''Work with'' text field. Install the latest ''Ontology Development/Graph Feature''. This provides the possibility to create ''Simantics Ontology Projects'', i.e. allows IDE integrated development of the ontologies (data models) used in the Simantics application you are developing.

See [[org.simantics.graph]] for the component's documentation.

=== Eclipse plug-in for Subversion ===

{{tip|With Simantics 1.4 and future releases this step is optional.}}

Simantics uses Subversion ([http://subversion.apache.org/ SVN]) as a version control system ([http://en.wikipedia.org/wiki/Revision_control VCS]) for storing all of our source code. To access this data from neatly from Eclipse, you need to install some plug-ins into it. To install the plug-in, follow these instructions:

* Install Subversion plug-in: [http://www.eclipse.org/subversive/ Eclipse Subversive]. Update Site is a part of Helios Update Site. From the main menu, open Help > Install New Software...
*# [[Image:Install_connectors.png|right|100px|thumb|SVN connector installation dialog]] From the ''Work with'' selector, select Helios - http://download.eclipse.org/releases/helios
*#* From the ''Collaboration'' folder, select the following items:
*#** '''Subversive SVN Team Provider'''
*#** '''Subversive SVN JDT Ignore Extensions'''
*#* Select Finish and watch the installation proceed
*#* Click ''Restart Now'' after the installation completes
*# After restarting, open the '''SVN Repository Exploring''' perspective and Eclipse should open a dialog called '''Install Connectors'''. Select '''SVN Kit 1.3.x''' and press finish.

* NOTE: if this installation process fails, this means that Eclipse is offering broken/incompatible packages at the moment. In this case you probably need to install the latest ''early access'' versions using http://www.eclipse.org/subversive/downloads.php#early_access

* Be warned that there has been a bug in Subversive which causes it to use the HTTP proxy for HTTPS addresses too. In order to get your SVN connection to www.simantics.org working, you may need to use direct connection proxy settings after installing the SVN plug-ins.

== Setup IDE ==

* Import Simantics Java formatting rules into your Eclipse: [[Media:Simantics-Java-Formatting.xml | save this XML file]]
** In Eclipse: ''Window/Preferences'' and the ''Java/Code Style/Formatter'' folder, select ''Import...'' and find the XML file you just downloaded.
* From the same preferences dialog also make sure that JDK 6.0 (or JRE 1.6) compliance is enabled:
*: [[Image:java_compiler_preferences.png|400px]]
* Optionally enable Save Actions: ''Java/Editor/Save Actions'':
** enable ''Organize imports''
** enable ''Additional actions''
** enable ''Format source code'' (not always recommendable)
** ''Configure'': ''Code Organizing'': Enable ''Remove trailing whitespace'' and ''Correct indentation''

== Download Simantics ==

=== Simantics 1.4+ Instructions ===

Follow the instructions on the [[Target Platform#Simantics 1.4|Target Platform page]] to set the Simantics 1.4 target platform up for your workspace.

=== Pre-Simantics 1.4 Instructions ===

==== Install Simantics target platform ====
The target platform is a set of Simantics and Eclipse features and plug-ins that constitute the components you can build your Simantics/Eclipse-based software out of. These are needed as base to get working on your own contributions on top of the Simantics platform.

To get the platform one must perform a [http://svnbook.red-bean.com/en/1.5/svn.tour.initial.html''checkout''] from the SVN repository. You can use Eclipse's '''SVN Repository Exploring perspective''' for this task. You can also use other tools, such as [http://tortoisesvn.net TortoiseSVN] or the [http://subversion.tigris.org/getting.html#binary-packages SVN command line client].

<blockquote>
{{questionanswer|'''How do I ''check out'' from SVN in Eclipse in general?'''|
[[Image:new_repository_location.png|right|100px]]
* Switch to the '''SVN Repository Exploring''' perspective.
* In the ''SVN Repositories'' view, from the context menu, select ''New → Repository Location''.
* Enter the SVN repository location in the URL field and enter your repository credentials in the authentication fields.
* Browse the added repository tree, select the directory/project you want to access and edit, and select '''Check out''' from the context menu.
}}
</blockquote>

# '''Checkout the target platform''' for your version into a directory of your choice. See [[Target Platform]] for available versions.
#* Updating your target platform is now a matter of updating your target platform working copy.
#* Upgrading to newer versions of the target platform requires switching to/checking out another branch of the target platform.
# '''Import the target platform into your eclipse IDE''':
#* If you checked out the target platform using another tool besides Eclipse, first import the target platform into your workspace:
#** ''File/Import'': ''General/Existing Project into Workspace'': Select target platform location as ''root directory''. '''Deselect''' ''Copy projects into workspace'' if selected. Press ''Finish''.
#* Select menu item ''Window/Preferences'' from your Eclipse IDE.
#* Open the preference page Plug-in Development/Target Platform.
#* Activate your target platform definition by checking it and press OK.

==== Download Simantics Components ====

===== Add Simantics repositories =====
* Switch to ''SVN Repository Exploring'' perspective in Eclipse.
* Add the main Simantics repository location in the SVN Repository view:
** General tab:
*** URL = https://www.simantics.org/svn/simantics/
*** Authentication =
**** '''Committers:''' your username and password

===== Checkout Simantics sources =====
* Checkout the proper project sets into your workspace. Eclipse will check it out as ''ProjectSets'':
** '''Simantics development version''': ''project-set/trunk''

* Switch to ''Java perspective''.
* To speed up the download, disable automatic building from menu toggle ''Project/Build Automatically''.
* From the ''Package Explorer'' view, pick '''simantics.psf''' file from the ProjectSets folder and select ''Import Project Set'' from the popup menu.
* Re-enable automatic building
* '''IMPORTANT''': If checked out code does not compile/work, consult the [[Plugins|maintainers of the non-working module]].

===== Troubleshooting =====

* If the project set import fails or does not do anything, please update your SVN plug-ins to the latest versions available.

=== Start Development ===

To get started on development, continue to '''[[Tutorial: Ontology Development]]'''.

== Basic IDE Usage ==
=== Running Products from the IDE ===

* Create a '''Product Configuration''' (.product) for your own product.
** You can use '''[https://www.simulationsite.net/trac/simantics/browser/sysdyn/trunk/org.simantics.sysdyn.ui/sysdyn.product sysdyn.product]''' as a starting point for your own product configuration. To get '''sysdyn.product''', import the '''sysdyn.psf''' project-set.
** Be sure to only include the components that you want to have in your product, nothing more.

: [[Image:SimanticsWorkbenchProduct.png|500px]]
* Launch the product from the links under the ''Testing'' section

* When launching the Simantics Workbench application from the IDE, i.e. in development mode, the application will make sure that your application workspace will contain a Simantics database that contains the transferable graphs contained by the ontology project bundles that are included in your product's plug-in configuration.
** Be warned that the application can't handle all cases of modified database contents. This means that sometimes the easiest way to get your application running is clearing your application's workspace and starting with a fresh database.

; IMPORTANT DEVELOPER NOTICE

Remember to always launch your application using the .product configuration editor as described above when you want to make sure that your IDE's application launcher configuration is up-to-date. The launcher configurations contain the set of plug-ins that are installed into the launched application which means which is not updated when the application is launched through the menu or (Ctrl+)F11.

The launcher configurations will most likely require updating when you
# take new plug-ins into use (add them to features included by the product)
# remove plug-ins from use
# plug-ins are moved from the workspace to the target platform or vice versa
# the target platform is updated

=== Testing your own contributions with Simantics ===

; Scenario - Testing a set of new plug-ins

Prerequisites:
# Some of the added plug-ins may contain ontologies.
# You've created your own set of plug-ins based on the Simantics SDK.
# You've defined ''features'' that include your plug-ins.
# You've followed the instructions at [[#Building]]

Steps to follow:
# If you have not already created a product definition for yourself:
## Optionally create a new plug-in project with the name ''product'' in it
## Add a new ''Product Configuration'' to an existing or a new plug-in with basic settings
## Open the new .product file with ''Product Configuration Editor''
## From the ''Overview'' tab, ''Product Definition'' section, select '''org.simantics.workbench.application''' as the application and create a new product extension with the ''New'' button beside the product selector. Also mark the product definition ''feature based''.
# Configure the product to your liking, i.e. add the features you need to it
# Launch your product from the product configuration editor ''Overview'' tab

=== Product Deployment ===

Deploying a product in this context means taking a certain set of features and plug-ins and packaging into an installable and executable application.

; Things to ensure before deploying your product:
# '''Ensure correctness of your build.properties files'''
#* For each of your own bundles (plug-ins and features), check that their ''build.properties'' files contain all the necessary files within each bundle. For example '''adapters.xml''' is often forgotten from the build since there is currently no automation that would add it to the build.
# '''Ensure validity of .product definition:'''
#* Open your .product file in the Eclipse IDE (use Ctrl-Shift-R for searching)
#* On the ''Launching'' page:
#** Set '''Launcher Name''' to set the name of your product executable.
#** Under '''Program Arguments:''', add -fixerrors. This ensures that your product will initialize all new workspaces with a database instead of assuming that a database must already pre-exist.
#** Under '''VM Arguments:''' add at least '''-ea''' to enable VM assertions.

; Deploying Executable Product
* Open .product file in the Eclipse IDE (use Ctrl-Shift-R for searching)
* On the ''Overview'' page of the product editor, select ''Eclipse Product export wizard'' from under '''Exporting'''
* Fill in any missing details in the dialog and select Finish.
** To create a directly executable product, you need to deselect '''Generate metadata repository'''.
** To create a product deployable with [http://wiki.eclipse.org/Equinox/p2/Director_application P2 director] (and in the future [[SPM]]), you need to select '''Generate metadata repository'''. This will generate an [http://wiki.eclipse.org/Equinox/p2 Eclipse P2] repository.

[[Category: Miscellaneous Documents]]

Simantics Developer Documentation

2017-02-20T11:29:57Z

Hannu Niemisto: /* Simantics Constraint Language */

__NOTOC__
[[image:Simantics_logo_pile_01.png|right|border|400px]]

'''Simantics''' is a software platform for modelling and simulation. The system has client-server architecture with a semantic ontology-based modelling database and Eclipse framework -based client software with plug-in interface. The Simantics platform and many of its components are open source under [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License (EPL)].

The philosophy of the Simantics platform is to offer an open, high level application platform on which different computational tools can be easily integrated to form a common environment for modelling and simulation. The platform includes several modelling tools, so-called editors, for e.g. 2D graph-like hierarchical model composition and semantic graph browsing.

One of the biggest innovations in the Simantics platform is the semantic modelling approach itself and high-level ontology tools. The semantic database, i.e. triplestore, on the server side enables high performance data management and arbitrary mappings of data. This enables e.g. efficient mapping of simulation and measurement data to the model configuration and its visualisation.

The Simantics development and maintenance process is built to be solid and scalable from the very beginning. The objective is to aim far to the future what comes to requirements for scalability, usability, and reliability.

This ''Simantics Developer Documentation'' is targeted to programmers and software developers developing either the platform itself or additional plug-ins to be used with or on the platform. The [[userwiki:Main_Page|Simantics End User Documentation]] complements to documentation for the Simantics platform offering overview and detailed information about the platform from the user's point of view. The [https://www.simantics.org/simantics Simantics] website is the source of information for the Simantics project and related subjects[[Tutorials|.]]
<div style="color:white;">Disclaimer Warning: This site may cause narcolepsia in some readers. Consult your doctor if sensitive to boredom.</div>

{|width="75%"
|width="25%" valign="top"|
=== Overview ===

* [[Glossary]]
* [[Introduction to Simantics Architecture]]
* [[Roadmap]]
* [[Data View]]
* [[Component View]]
* [[Licensing|Licensing]]
* [[Useful Links]]


|width="25%" valign="top"|

=== Miscellaneous Documents ===

* [[Quick Development Environment Setup|Quick Development Environment Setup Guide]]
* [[Target Platform]]
* [[Development Practices]]
* [[Internalization]]
* [[Update Site]]
* [[Coding Convention]]
* [[Tools]]
* [[Testing]]
* [[FAQ]]
* [[Migration To Git]]

|width="25%" valign="top"|

|}

{|width="100%"

|width="25%" valign="top"|

=== Ontology Development ===

* [[:Media:Layer0.pdf|Layer0.pdf]] ([[:File:Layer0.pdf|log]])
* [[Graph Compiler]]
* [[Transferable Graph]]
* [[Binary Container Format]]
* [[Graph File Format]]
* [[Version Migration]]
* [[Tutorial: Ontology Development]]
* [[XML Schema Conversion]]

|width="25%" valign="top"|

=== Database Development ===

* [[Interface summary]]
* [[Tutorial: Quickstart]]
* [[Tutorial: Database Development]]
* [[Resource Adaptation]]
* [[Resource Serialization]]
* [[Inverse Relations]]
* [[Virtual Graphs]]
* [[Functions]]
* [[Procedural Values]]
* [[Variable]]
* [[Undo Mechanism]]
* [[Team Features]]
* [[Subgraph Extents]]
* [[Database Testing]]

|width="25%" valign="top"|

=== Data management & Experiment Control ===

* [[Databoard Specification]]
* [[Databoard Developer Manual|Databoard Java Manual]]
* [[Experiment Control]]
* [[Dataflows]]

|width="25%" valign="top"|

=== UI Development ===

* [[Org.simantics.browsing.ui_Manual|Browser Manual]]
* [[org.simantics.browsing.ui.feature|Browser Component]]
* [[Org.simantics.scenegraph.loader|Scene Graph Loader]]
* [[Org.simantics.message|Messages]]
* [[Org.simantics.views|Modelled Views]]
* [[Org.simantics.document|Documents]]
* [[Selection View]]
|}
{|width="100%"
|width="25%" valign="top"|

=== Simantics Constraint Language===

* [http://www.simantics.org/~niemisto/Introduction%20to%20SCL.pptx Introduction to SCL]
* [[SCL Compiler]]
* [[SCL Tutorial]]
* [[SCL Types]]


* [[Org.simantics.objmap_Manual|Object Map Manual]]
* [[SCL Registry]]
* [http://www.simantics.org/SCLDocumentation/StandardLibrary/Prelude.html SCL Reference]
* [http://www.simantics.org/~niemisto/Transformations.pdf Transformation language specification]
* [http://www.simantics.org/~niemisto/CHRGuide.html CHR Guide]

|width="25%" valign="top"|

=== Model Development ===

* [[Structural Ontology]]
* [[Users and Roles]]
* [[Models]]
* [[Concept Versioning]]
* [[Component Identification]]
* [[Tutorial: Model Development]]

|width="25%" valign="top"|

=== Project Development ===

* [[Project Management Conceptual Model]]
* [[Project Development]]
* [[Tutorial: Project Development]]

|width="25%" valign="top"|

=== Diagram Development ===

* [[2D Ontologies]]
* [[org.simantics.diagram|Diagram]]
* [[org.simantics.scenegraph|Scene graph]]
* [[Diagram connections]]
* [[Tutorial: Diagram Development]]

|}
{|width="100%"
|width="25%" valign="top"|

=== Issue Development ===

* [[Issue subsystem general description]]

|width="25%" valign="top"|

=== Utilities ===

* [[Simantics Generic File Import]]
* [[Logging in Simantics Platform]]

|}

-----

Licensing

2017-02-01T12:34:46Z

Hannu Niemisto: /* Simantics Licenses */

== Simantics Licenses ==

Simantics Platform is licensed under [[#Eclipse Public License]]. The license does not have to apply to 3rd party applications and plug-ins that are integrated with Simantics. That means, an application built on Simantics can be e.g. a commercial, closed code. Or it can be an open source product. In any case, the application and plug-in licensing have to respect Simantics licensing. E.g. if a plug-in component uses a so-called "Strict GPL", the integration with Simantics has to be done with extra care; the GPL licensed software can't influence the licensing of Simantics platform. For a commercial products, the application or plug-in has to be clearly separated from the platform and all the integration code needed in the Simantics platform side has to be licensed under Eclipse Public License (EPL).

On [http://www.gnu.org/philosophy/license-list.html GNU Operating System] website there is an excellent description of different free and open source licenses and their differences in a nut shell. Another website worth mentioning is [http://www.opensource.org/ Open Source Initiative]. From this side you can find information about open source software development and licensing.

Simantics depends on a few third party components which have license other than EPL.

<blockquote>
{| border="0" cellpadding="5" cellspacing="2" width="100%" "style="background:transparent; text-align:left;"
|- style="background-color: #eeeeee;"
! align="left"|Component
! align="left" style="width: 20em"|License
! align="left"|Notes
|- style="background-color: #f4f4ff;"
| [https://www.simantics.org/simantics Simantics Platform]
| [[#Eclipse Public License|EPL]]
| All Simantics plugins
|- style="background-color: #eeeeff;"
| [http://www.eclipse.org/ Eclipse Platform]
| [[#Eclipse Public License|EPL]]
| All Eclipse plugins
|- style="background-color: #f4f4ff;"
| [http://www.cs.wustl.edu/~schmidt/ACE.html ACE - Adaptive Communications Environment]
| [[#ACE license|ACE License]]
|
|- style="background-color: #eeeeff;"
| [http://www.jcraft.com/jzlib/ JZlib]
| [[#JZLib License|JZLib License]]
|
|- style="background-color: #f4f4ff;"
| [http://xmlgraphics.apache.org/batik/ Batik] (org.apache.batik)
| [[#Apache Software License 2.0|Apache Software License 2.0]]
|
|- style="background-color: #eeeeff;"
| [http://logging.apache.org/log4j/index.html Log4j] (org.apache.log4j)
| [[#Apache Software License 2.0|Apache Software License 2.0]]
|
|- style="background-color: #f4f4ff;"
| [http://www.json.org/ JSON] (JSON_libraries)
| [[#Apache Software License 2.0|Apache Software License 2.0]]
|
|- style="background-color: #eeeeff;"
| [http://cglib.sourceforge.net/ cglib]
| [[#Apache Software License 2.0|Apache Software License 2.0]]
|
|- style="background-color: #f4f4ff;"
| [http://itextpdf.com/ iText] (com.lowagie.text)
| [[#LGPL|LGPL]]
| The 2.1 series allows using either LGPL [http://www.lowagie.com/iText/lgpl.txt] or MPL [http://www.lowagie.com/iText/MPL-1.1.txt]. We use the library with the LGPL. According to the [http://www.lowagie.com/iText/download.html iText license agreement] we must mention that iText has the possibility to use MPL as an alternative license.
|- style="background-color: #eeeeff;"
| [https://svgsalamander.dev.java.net/ SVG Salamander]
| [[#LGPL|LGPL]]
|
|- style="background-color: #f4f4ff;"
| [http://lobobrowser.org/cobra.jsp Cobra]
| [[#LGPL|LGPL]]
| Cobra itself is LGPL 3. Cobra uses Rhino as its Javascript interpreter. Rhino can be used as either MPL or GPL. We currently have no need for Javascript so were not using Rhino. Although the author's opinion is to go with GPL when using Rhino, we would have to go with MPL to keep EPL compatible if we used it.
|- style="background-color: #eeeeff;"
| [http://www.jfree.org/jcommon/ JCommon], [http://www.jfree.org/jfreechart/ JFreeChart]
| [[#LGPL|LGPL]]
|
|- style="background-color: #f4f4ff;"
| valign="top" | [http://trove4j.sourceforge.net/ GNU Trove] (gnu.trove2, gnu.trove3)
| valign="top" | [[#LGPL|LGPL]]
| [http://trove4j.sourceforge.net/html/license.html Original license text].

The source code for GNU Trove is licensed under the Lesser GNU Public License (LGPL).
Copyright (c) 2001, Eric D. Friedman All Rights Reserved. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Two classes (HashFunctions and PrimeFinder) included in Trove are licensed under the following terms:

Copyright (c) 1999 CERN - European Organization for Nuclear Research. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. CERN makes no representations about the suitability of this software for any purpose. It is provided "as is" without expressed or implied warranty.

|- style="background-color: #eeeeff;"
| [http://www.fastlz.org/ FastLZ]
| [[#FastLZ License|MIT License]]
| SVN revision 12
|- style="background-color: #f4f4ff;"
| [http://code.google.com/p/lz4/ LZ4 - Extremely Fast Compression algorithm]
| [[#LZ4 License|BSD 2-Clause License]]
| SVN revision 68
|- style="background-color: #eeeeff;"
| [https://github.com/jpountz/lz4-java LZ4 compression for Java]
| [[#Apache Software License 2.0|Apache Software License 2.0]]
| 1.3.0
|- style="background-color: #f4f4ff;"
| [http://www.famfamfam.com/lab/icons/silk/ FamFamFam Silk Icons by Mark James]
| [[#Creative Commons Attribution 2.5 License|Creative Commons Attribution 2.5 License]]
| 1.3
|- style="background-color: #eeeeff;"
| [http://damieng.com/creative/icons/silk-companion-1-icons Silk Companion 1 (more Silk icons) by Damien Guard]
| [[#Creative Commons Attribution 2.5 License|Creative Commons Attribution 2.5 License]]
| -
|- style="background-color: #f4f4ff;"
| [http://fastutil.di.unimi.it/ fastutil: Fast & compact type-specific collections for Java]
| [[#Apache Software License 2.0|Apache Software License 2.0]]
| 7.0.6
|- style="background-color: #f4f4ff;"
| valign="top" | [http://asm.ow2.org/ ASM]
| [http://asm.ow2.org/license.html]
|- style="background-color: #f4f4ff;"
| valign="top" | [https://eclipse.org/jetty/ Jetty]
| [[#Eclipse Public License|EPL]]
|- style="background-color: #f4f4ff;"
| valign="top" | [http://www.graphviz.org/ Graphviz]
| [[#Eclipse Public License|EPL]]
|}
</blockquote>

== Eclipse Public License ==




[http://www.eclipse.org/org/documents/epl-v10.html http://www.eclipse.org/org/documents/epl-v10.html]

Eclipse Public License - v 1.0.

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

'''1. DEFINITIONS'''

"Contribution" means:

a) in the case of the initial Contributor, the initial code and documentation distributed under this Agreement, and

b) in the case of each subsequent Contributor:

i) changes to the Program, and

ii) additions to the Program;

where such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution 'originates' from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program.

"Contributor" means any person or entity that distributes the Program.

"Licensed Patents" mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

"Program" means the Contributions distributed in accordance with this Agreement.

"Recipient" means anyone who receives the Program under this Agreement, including all Contributors.

'''2. GRANT OF RIGHTS'''

a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form.

b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.

c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.

d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.

'''3. REQUIREMENTS'''

A Contributor may choose to distribute the Program in object code form under its own license agreement, provided that:

a) it complies with the terms and conditions of this Agreement; and

b) its license agreement:

i) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;

ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;

iii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and

iv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange.

When the Program is made available in source code form:

a) it must be made available under this Agreement; and

b) a copy of this Agreement must be included with each copy of the Program.

Contributors may not remove or alter any copyright notices contained within the Program.

Each Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution.

'''4. COMMERCIAL DISTRIBUTION'''

Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.

For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.

'''5. NO WARRANTY'''

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement , including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

'''6. DISCLAIMER OF LIABILITY'''

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

'''7. GENERAL'''

If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.

All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.

Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.

This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation.

== LGPL ==

[http://www.gnu.org/copyleft/lesser.html http://www.gnu.org/copyleft/lesser.html]

GNU LESSER GENERAL PUBLIC LICENSE

Version 3, 29 June 2007

Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/>

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below.
'''0. Additional Definitions.'''

As used herein, “this License” refers to version 3 of the GNU Lesser General Public License, and the “GNU GPL” refers to version 3 of the GNU General Public License.

“The Library” refers to a covered work governed by this License, other than an Application or a Combined Work as defined below.

An “Application” is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library.

A “Combined Work” is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the “Linked Version”.

The “Minimal Corresponding Source” for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version.

The “Corresponding Application Code” for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work.

'''1. Exception to Section 3 of the GNU GPL.'''

You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL.

'''2. Conveying Modified Versions.'''

If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version:

* a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or
* b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy.

'''3. Object Code Incorporating Material from Library Header Files.'''

The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following:

* a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License.
* b) Accompany the object code with a copy of the GNU GPL and this license document.

'''4. Combined Works.'''

You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following:

* a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License.
* b) Accompany the Combined Work with a copy of the GNU GPL and this license document.
* c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document.
* d) Do one of the following:
** 0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.
** 1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version.
* e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.)

'''5. Combined Libraries.'''

You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following:

* a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License.
* b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.

'''6. Revised Versions of the GNU Lesser General Public License.'''

The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation.

If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library.

== JZLib License ==

[http://www.jcraft.com/jzlib/LICENSE.txt http://www.jcraft.com/jzlib/LICENSE.txt]
<pre>
JZlib 0.0.* were released under the GNU LGPL license. Later, we have switched
over to a BSD-style license.

------------------------------------------------------------------------------
Copyright (c) 2000,2001,2002,2003,2004 ymnk, JCraft,Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the distribution.

3. The names of the authors may not be used to endorse or promote products
derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT,
INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>

== Apache Software License 2.0 ==

[http://www.apache.org/licenses/LICENSE-2.0.txt http://www.apache.org/licenses/LICENSE-2.0.txt]
<pre>
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.

"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:

(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and

(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and

(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.

You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

APPENDIX: How to apply the Apache License to your work.

To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.

Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</pre>

== ACE License ==

[http://www.cs.wustl.edu/~schmidt/ACE-copying.html http://www.cs.wustl.edu/~schmidt/ACE-copying.html]
Copyright (c) 2000-2005 INRIA, France Telecom
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holders nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF

== FastLZ License ==
<pre>
FastLZ - lightning-fast lossless compression library

Copyright (C) 2007 Ariya Hidayat (ariya@kde.org)
Copyright (C) 2006 Ariya Hidayat (ariya@kde.org)
Copyright (C) 2005 Ariya Hidayat (ariya@kde.org)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
</pre>

== LZ4 License ==
<pre>
LZ4 - Fast LZ compression algorithm
Copyright (C) 2011-2012, Yann Collet.
BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

You can contact the author at :
- LZ4 homepage : http://fastcompression.blogspot.com/p/lz4.html
- LZ4 source repository : http://code.google.com/p/lz4/
</pre>

== Creative Commons Attribution 2.5 License ==

http://creativecommons.org/licenses/by/2.5/ 
http://creativecommons.org/licenses/by/2.5/legalcode

<center>'''Creative Commons Legal Code'''</center>

<center>'''Attribution 2.5'''</center>

CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM ITS USE.

''License''

THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.

BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.

'''1. Definitions'''
<blockquote>
a. '''"Collective Work"''' means a work, such as a periodical issue, anthology or encyclopedia, in which the Work in its entirety in unmodified form, along with a number of other contributions, constituting separate and independent works in themselves, are assembled into a collective whole. A work that constitutes a Collective Work will not be considered a Derivative Work (as defined below) for the purposes of this License.

b. '''"Derivative Work"''' means a work based upon the Work or upon the Work and other pre-existing works, such as a translation, musical arrangement, dramatization, fictionalization, motion picture version, sound recording, art reproduction, abridgment, condensation, or any other form in which the Work may be recast, transformed, or adapted, except that a work that constitutes a Collective Work will not be considered a Derivative Work for the purpose of this License. For the avoidance of doubt, where the Work is a musical composition or sound recording, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered a Derivative Work for the purpose of this License.

c. '''"Licensor"''' means the individual or entity that offers the Work under the terms of this License.

d. '''"Original Author"''' means the individual or entity who created the Work.

e. '''"Work"''' means the copyrightable work of authorship offered under the terms of this License.

f. '''"You"''' means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation.
</blockquote>

'''2. Fair Use Rights.''' Nothing in this license is intended to reduce, limit, or restrict any rights arising from fair use, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws.

'''3. License Grant.''' Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below:

<blockquote>
a. to reproduce the Work, to incorporate the Work into one or more Collective Works, and to reproduce the Work as incorporated in the Collective Works;

b. to create and reproduce Derivative Works;

c. to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission the Work including as incorporated in Collective Works;

d. to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission Derivative Works.

e. For the avoidance of doubt, where the work is a musical composition:

<blockquote>
i. Performance Royalties Under Blanket Licenses. Licensor waives the exclusive right to collect, whether individually or via a performance rights society (e.g. ASCAP, BMI, SESAC), royalties for the public performance or public digital performance (e.g. webcast) of the Work.

ii. Mechanical Rights and Statutory Royalties. Licensor waives the exclusive right to collect, whether individually or via a music rights agency or designated agent (e.g. Harry Fox Agency), royalties for any phonorecord You create from the Work ("cover version") and distribute, subject to the compulsory license created by 17 USC Section 115 of the US Copyright Act (or the equivalent in other jurisdictions).
</blockquote>

f. '''Webcasting Rights and Statutory Royalties.''' For the avoidance of doubt, where the Work is a sound recording, Licensor waives the exclusive right to collect, whether individually or via a performance-rights society (e.g. SoundExchange), royalties for the public digital performance (e.g. webcast) of the Work, subject to the compulsory license created by 17 USC Section 114 of the US Copyright Act (or the equivalent in other jurisdictions).
</blockquote>

The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats. All rights not expressly granted by Licensor are hereby reserved.

'''4. Restrictions.''' The license granted in Section 3 above is expressly made subject to and limited by the following restrictions:

<blockquote>
a. You may distribute, publicly display, publicly perform, or publicly digitally perform the Work only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy or phonorecord of the Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Work that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute, publicly display, publicly perform, or publicly digitally perform the Work with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License Agreement. The above applies to the Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Work itself to be made subject to the terms of this License. If You create a Collective Work, upon notice from any Licensor You must, to the extent practicable, remove from the Collective Work any credit as required by clause 4(b), as requested. If You create a Derivative Work, upon notice from any Licensor You must, to the extent practicable, remove from the Derivative Work any credit as required by clause 4(b), as requested.

b. If you distribute, publicly display, publicly perform, or publicly digitally perform the Work or any Derivative Works or Collective Works, You must keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or (ii) if the Original Author and/or Licensor designate another party or parties (e.g. a sponsor institute, publishing entity, journal) for attribution in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; the title of the Work if supplied; to the extent reasonably practicable, the Uniform Resource Identifier, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and in the case of a Derivative Work, a credit identifying the use of the Work in the Derivative Work (e.g., "French translation of the Work by Original Author," or "Screenplay based on original Work by Original Author"). Such credit may be implemented in any reasonable manner; provided, however, that in the case of a Derivative Work or Collective Work, at a minimum such credit will appear where any other comparable authorship credit appears and in a manner at least as prominent as such other comparable authorship credit.
</blockquote>

5. Representations, Warranties and Disclaimer

UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.

6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. Termination

<blockquote>
a. This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Derivative Works or Collective Works from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License.

b. Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above.
</blockquote>

8. Miscellaneous

<blockquote>
a. Each time You distribute or publicly digitally perform the Work or a Collective Work, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.

b. Each time You distribute or publicly digitally perform a Derivative Work, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License.

c. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

d. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent.

e. This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You.
</blockquote>

Creative Commons is not a party to this License, and makes no warranty whatsoever in connection with the Work. Creative Commons will not be liable to You or any party on any legal theory for any damages whatsoever, including without limitation any general, special, incidental or consequential damages arising in connection to this license. Notwithstanding the foregoing two (2) sentences, if Creative Commons has expressly identified itself as the Licensor hereunder, it shall have all rights and obligations of Licensor.

Except for the limited purpose of indicating to the public that the Work is licensed under the CCPL, neither party will use the trademark "Creative Commons" or any related trademark or logo of Creative Commons without the prior written consent of Creative Commons. Any permitted use will be in compliance with Creative Commons' then-current trademark usage guidelines, as may be published on its website or otherwise made available upon request from time to time.

Creative Commons may be contacted at http://creativecommons.org/.

[[Category:Introduction]]

Migration To Git

2016-12-29T14:38:43Z

Hannu Niemisto: /* Eclipse */

== Recommended Reading ==

* Official Gerrit introduction: https://gerrit-review.googlesource.com/Documentation/intro-quick.html.
* Gerrit tutorial: http://www.vogella.com/tutorials/Gerrit/article.html

== Instructions for Simantics Developers ==

=== Gerrit ===

# Request a Gerrit account. If you already have a SVN account, it should work also in Gerrit.
# Generate SSH Public/Private key. If you already have one available, skip this step
#* Windows
#** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
#** Run PuTTYgen and generate a key
#*** For Type of key to generate, select '''SSH-2 RSA'''
#*** Press '''Generate''' button
#*** Move your mouse over the window until the progress bar is finished
#*** Write a '''Key passphrase''' to protect your private key in case your local machine is compromised.
#*** Save the generated public and private keys in <code>C:\Users\{username}\.ssh</code> as follows:
#**** Start cmd.exe and create the target directory using <code>mkdir .ssh</code>
#**** Save private key using '''Conversions -> Export OpenSSH Key'''. The name <code>id_rsa</code> is preferred because it will work out of the box with all tools.
#**** At the top of the window, there is a text field labeled '''Public key for pasting into OpenSSH authorized_keys'''. Copy the public key from there and save it into a text file at <code>C:\Users\{username}\.ssh\id_rsa.pub</code>
#* Linux
#** Generate public and private keys using <code>ssh-keygen -t rsa</code>
# Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
# Select your name in the top-right corner and press ''Settings''
# Go to section '''SSH Public Keys'''
# Open the file containing the generated public key in a text editor and copy-paste its contents to the box in Gerrit and and press '''Add'''
# Add and verify your contact information (name + e-mail). This will allow administrators to add you to the necessary groups to get commit access:
#* Go to section '''Contact Information''' and enter your '''Full Name''' there
#* Add a '''Preferred Email''' address using the button '''Register New Email'''
#* Wait for the authorization mail to arrive. It will look something like the following and contain a longish link that tends to end with == characters. Note that outlook tends to leave the trailing == characters out of the link it generates automatically. That's why it is recommended to copy the full URL from the mail into your browser to verify your e-mail address.
<pre>Subject: [Gerrit Code Review] Email Verification

Welcome to Gerrit Code Review at www.simantics.org.

To add a verified email address to your user account, please
click on the following link while signed in as .....:

http://www.simantics.org:8088/r/#/../...............................................................................==

If you have received this mail in error, you do not need to take any
action to cancel the account. The address will not be activated, and
you will not receive any further emails.

If clicking the link above does not work, copy and paste the URL in a
new browser window instead.

This is a send-only email address. Replies to this message will not
be read or answered.
</pre>

<ol start="8">
<li>Finally, ask [[User:Tuukka Lehtonen]] to add you to the necessary groups and wait for this to happen.</li>
</ol>

=== Eclipse ===

The following instructions are written for Eclipse Neon. There might be some differences if you are using Mars.

# Go to preferences (General / Network Connections / SSH2) and ensure that '''SSH2 home''' points to the directory where you saved the private key.
# Go to preferences (Team / Git / Configuration) and ensure that the tab '''User Settings''' has the following two setting: <code>user.name</code> and <code>user.email</code>. The specified name and email must match the values you've put in Gerrit to be able to push changes. [[image:git-global-config.png|400px]]
#* Also, git has a setting called <code>core.autocrlf</code> which is used for controlling the way git enforces line feeds to be encoded in a certain way in commits. Read [https://git-scm.com/book/tr/v2/Customizing-Git-Git-Configuration#idp31554304 the documentation] to learn more. We recommend to set it <code>true</code> in Windows in order to avoid committing CRLFs to repostory.
#* If you have a git command line client installed you can use the command <code>git config --list --show-origin</code> to see your current global settings and find out exactly where your settings are coming from.
# Open ''Git'' perspective
# Press button '''Clone a Git Repository and add the clone to this view''' (third button in the toolbar of Git view)
# Select '''Clone URI''' (Don't select Gerrit, it doesn't work very well at the moment)
# Go back to Gerrit. Press '''Projects''' in the top-left menu and '''List''' in the submenu.
# Find a row named '''simantics/platform''' and press '''(gitweb)''' link at the last column.
# Copy the URI starting with ''ssh:'' (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to '''URI''' field in '''Clone Git Repository dialog'''.
# This should automatically fill the other fields.
# Press Next. If your private key has a passphrase, Eclipse now asks it.
# Select all branches to be cloned (default) and press Next.
# Give a local directory where the repository is cloned to and press Finish.
# After the cloning is finished, select the '''platform''' repository in the Git Repositories view and select '''Import Projects...''' from context menu.
# Press Next, select all projects but '''org.simantics.root''' and press Finish.
# Expand the tree view of '''platform''', expand '''Branches''' under it and '''Local''' under it. Open context menu on '''master''' branch and select '''Configure Branch...'''. Select '''Rebase''' checkbox and press '''Ok'''.

The repository you cloned contains the target platform definition that needs to be set in order for the imported Simantics codebase to compile. You can find the required target platform definition file from '''org.simantics.sdk.build.targetdefinition/org.simantics.sdk.build.targetdefinition.target'''. Open it in the target definition editor and set it as the active target platform by pressing the link '''Set as Target Platform''' at the top right corner of the editor.

Congratulations, you've now set up your workspace for developing the Simantics codebase in Eclipse!

=== Updating your local repository and working space ===

# Open context menu on '''platform''' in the Git perspective and select '''Pull'''.

=== Committing your changes back to shared repository ===

# Select '''platform''' in the Git perspective and open '''Git Staging''' view.
# '''Unstaged Changes''' shows all files you have modified.
# Drag&drop those changes you want to commit to the box '''Staged Changes'''.
# Write a [[#Commit message format|commit message]]
# Ensure that '''Add Change-Id''' button is toggled down and the commit message contains a row starting ''Change-Id:''.
#* This is required by Gerrit to be able to bind commits to specific reviews. Gerrit will replace the default zero-valued Id with a generated one when the change is pushed for review.
# Press '''Commit and Push...'''
# This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
#* Example of a topic: http://www.simantics.org:8088/r/#/q/topic:svn
# Go to Gerrit. In the top-left menu select '''My''' and select '''Changes'''.
# Your change can be seen now in the section '''Outgoing reviews'''.
# Click the change. This opens a review page.
# Ask someone to review your change. This can be done also in Gerrit by pressing '''Add...''' button in the right of the '''Reviewers''' field.
# If you need to make modifications to your changes based on reviews, you'll need to ''Amend'' the earlier changes to send a new patch set to Gerrit. In this case, ensure that the ''Amend (Edit Previous Commit)'' button is toggled down and you should be able to modify the earlier commit message and push the amended changes.
# When somebody has reviewed and accepted the change with +2, the review page will contain a '''Submit''' button that can be used to merge the change to the master branch.

==== Commit message format ====

In Git, the first row of the commit message is used for ''shortlog'' and generating patch file names so keep it short, concise and as descriptive as possible. The commit box in the UI shows a vertical line marking the maximum length of a commit message line and the view will inform you if you're exceeding limits. Note that the commit message box will automatically break long lines of text into separate lines to help you write a cleanly formatted commit message.

To keep commits attached to [https://www.simantics.org/redmine/ Redmine] issues, use <code>refs #nnn</code>, where <code>nnn</code> is the issue number. This must be specified before ''Change-Id:''. The Simantics platform Gerrit is configured to show <code>refs #nnn</code> lines as hyperlinks to platform Redmine issues, i.e. to URL <code>https://www.simantics.org/redmine/issues/nnn</code>.

Often platform commits are also related to some issue or issues from other projects built on top of the platform. In order to retain some information about this association in the commit messages we recommend using separate rows in commit messages in form<code>[PRIVATE-mmm]</code> where <code>mmm</code> is the issue number in the other project.

Gerrit reviews require a row starting ''Change-Id:'' as the last row of the commit message (excluding Signed-off-by rows). This allows Gerrit to bind commits to specific reviews. Gerrit will replace the default zero-valued Id with a generated one when the change is pushed for review.

All in all, a typical commit message should look like this:
<pre>
Short description of my change in under 65 characters

A longer description of my changes
that can span multiple lines.

refs #nnn
[PRIVATE-mmm] (optional, use this if the commit relates to another project)

Change-Id: I0000000000000000000000000000000000000000
</pre>

== Simantics Member Read-only Git Access ==

# Register to member wiki at https://www.simantics.org/members/index.php
# Log into [http://www.simantics.org:8088/r/# Gerrit] using the credentials found at https://www.simantics.org/members/index.php/Code_Repository_Access
# Clone http://member@www.simantics.org:8088/r/p/simantics/platform.git using the HTTP password found at http://www.simantics.org:8088/r/#/settings/http-password

The [[#Eclipse|instructions for using Eclipse]] with this git repository apply also for the generic member account. Just remember to replace the cloned SSH repository address with the HTTP address shown above.

== Testing Reviewed Changes ==

To test reviewed code changes locally, first you must have an Eclipse IDE setup according to the instructions in [[#Instructions for Simantics Developers]] or [[#Simantics Member Read-only Git Access]].

Now, let's say for example we wish to grab a patch set from a review, such as review #72 (http://www.simantics.org:8088/r/72).

# Open '''Git''' perspective
# Select root node of the cloned simantics-platform repository from the '''Git Repositories''' view
# From the context menu of the repository, select '''Fetch from Gerrit...'''
# In the '''Change''' field, type the change number 72 and press CTRL+SPACE to start content assist. Content assist will provide you with the selections '''72 - 1''', and '''72 - 2''', i.e. patch sets 1 and 2 of change 72. After selecting a patch set, the field will be filled with the value '''refs/changes/72/72/1''' or '''refs/changes/72/72/2''' depending on the patch set you selected.
# The default settings are otherwise recommended, i.e. '''Create a Local Branch''' and ''Checkout new branch'' to switch to the new branch immediately.

There you have it, a local branch that has exactly the same repository state as in the code to be reviewed. Start testing!

== Platform Git Branching Model ==

Branch naming conventions:
* features: <code>feature/<PROJECT-NAME>-<issuenumber></code>.
** Use these for developing a single feature. To keep the version history of feature branches cleaner, merge commit pushing is limited to project owners only. This means that feature branches should be used for implementing a particular thing and then merged back to master or some other branch. They should not be used as locations for eternal development and never ending try-outs.
* releases: <code>release/x.y.z</code>, where x, y and z are major, minor and service version numbers respectively.
** Only for release stabilization branches.
* private work branches: <code>private/*</code>.
** Should be used for personal work, trials and possibly even user or project specific custom branches that need to be kept. Gerrit is not configured enforce any rules on how these branches are used.
* hotfixes: <code>hotfix/x.y.z.<hotfix number></code>.

Basic access rights:

{|border=1
|'''action''' \ '''head'''||'''master''' '''release/*''' '''hotfix/*'''||'''feature/*'''||'''private/*'''
|-
|''Code Review -/+2''||Simantics developers||Simantics developers||Simantics developers
|-
|''Submit''||Owners only||Simantics developers||Simantics developers
|-
|''Push''||Owners only||Simantics developers||Simantics developers
|-
|''Push Merge Commits''||Owners only||Owners Only||Simantics developers
|}

The current plan is to loosely follow [http://nvie.com/posts/a-successful-git-branching-model/ GitFlow] rules but we've decided to go without a separate <tt>develop</tt> branch. This means that we treat master as a development version instead of a production version. The actual <tt>release/*</tt> branches and tags are used to produce production versions. The rationale behind this is that we do not have a continuously evolving production version. Instead we produce new releases and products pick them up as they see fit.

Related reading:
* [http://nvie.com/posts/a-successful-git-branching-model/ Git Flow branching model] by Vincent Driessen
* http://endoflineblog.com/gitflow-considered-harmful

== Transferred Projects ==

The following table lists the Git repositories that have been created so far and where their content is from in the SVN repositories.

{|border=1
|'''SVN Location'''||'''Gerrit project'''
|-
|All over https://www.simantics.org/svn/simantics/||https://www.simantics.org:8088/r/#/admin/projects/simantics/platform
|-
|https://www.simantics.org/svn/simantics/3d||https://www.simantics.org:8088/r/#/admin/projects/simantics/3d
|-
|https://www.simantics.org/svn/simantics/fmi||https://www.simantics.org:8088/r/#/admin/projects/simantics/fmil
|-
|https://www.simantics.org/svn/simantics/r||https://www.simantics.org:8088/r/#/admin/projects/simantics/r
|-
|Everything except OpenModelica bundles from https://www.simantics.org/svn/simantics/sysdyn||https://www.simantics.org:8088/r/#/admin/projects/simantics/sysdyn
|-
|Parts of https://www.simantics.org/svn/simantics/third-party/trunk||https://www.simantics.org:8088/r/#/admin/projects/simantics/third-party
|-
|https://www.simantics.org/svn/members/fmi||https://www.simantics.org:8088/r/#/admin/projects/members/fmi
|}

=== Still Untransferred Project Locations ===

* https://www.simantics.org/svn/simantics/interoperability
* https://www.simantics.org/svn/simantics/modelica
* https://www.simantics.org/svn/simantics/sysdyn: OpenModelica parts need to be put in a separate repository due to the huge size of OM. Preferable this repository should support LFS
* https://www.simantics.org/svn/simantics/tutorials

== Q & A ==

=== Will the complete SVN history be transferred to Git? ===

Sadly, no it will not, at least for everything that is considered part of the current SVN Simantics SDK (see revisions list on page https://www.simantics.org/jenkins/job/target-simantics-head-sdk/lastStableBuild/).

The reason for not attempting to salvage the full history into git is in the Simantics SVN repository's structure. In SVN a "project structure" is a single combination of the folders ''trunk'', ''branches'' and ''tags''. In git branches and tags do not exist like this as separate directories in the repository itself. The [https://git-scm.com/docs/git-svn git-svn] tool is perfectly capable of transforming a single project structure into git repository with all its history, branches and tags. At some point in the past we for decided to split the SVN repository contents into multiple project structures in the hope of modularizing the platform SDK. That hope never quite realized and what's worse, that structure has made platform release engineering much more laborous and complex than it would be with a single project structure. Now in this move to Git we decided to simplify things and just put the platform SDK projects back in a single monolithic structure of bundles, features, tests and release engineering projects. All in all, we just didn't have enough git expertise to be able to transfer all the history scattered in these multiple project structures into a single git repository and moving the current SVN project structures each into its own git repository was not an enticing option either.

So how are we doing it right now? We have a separate migration git repository that contains a python script that simply exports all listed projects from SVN into the simantics-platform git repository structure. Our simantics-platform git repository contains a branch called 'svn'. The SVN exporting python script was originally used to initially populate the git repository, back when we were first testing the migration. Another python script is then used to bring in changes from SVN by exporting on top of the existing simantics-platform git repository. These changes are then committed into the svn branch and merged into master from there. We are not using git svn fetch because we're just not proficient enough with git-svn to be able to use it separately for each and every project that has moved location in git already. The git master branch has already been developed onwards, but merging changes from the svn branch to it is still very easy.

Note that the SVN repository will remain in place to keep all old versions of the platform that are still needed for maintaining existing products. We will not be moving these old branches/versions into git.

Note that in general if you have a single SVN project structure to transfer to git it is recommended to use <code>git svn</code> to transfer the complete history to Git.

=== How do I convert my SVN repository into a Gerrit/git project & repository? ===

The following is an example of converting a single SVN project location (<code>trunk/,branches/,tags/</code>) into a Gerrit-hosted git repository. The instructions assume you are working on a Linux installation which has the git command line tools installed.

SVN project structure location to be converted: https://www.simantics.org/svn/simantics/3d/

Firstly, create a new project in Gerrit ([https://www.simantics.org:8088/r/#/admin/create-project/]). Create the project without an empty initial commit because the initial commits will come from the SVN repository anyway. In this example the project name <code>simantics/3d</code> is used.

Next clone the newly created git repository:
<pre>git clone ssh://<your-username>@www.simantics.org:29418/simantics/3d.git</pre>

Step into the cloned repository directory:
<pre>cd 3d</pre>

Initialize <code>git svn</code> with the correct SVN repository location:
<pre>git svn init https://www.simantics.org/svn/simantics/3d --stdlayout --prefix=svn/</pre>

Start fetching commits from the SVN repository into the empty git repository:
<pre>git svn fetch | tee fetch.log</pre>

Next, due to the way in which <code>git svn</code> converts branches and tags, we want to do a bit of cleanup to convert the branches into local branches before pushing them to the Gerrit's repository. Download [[Media:git-svn-convert-branches.sh|this shell script]] and execute it in the repository's root directory:
<pre>sh Git-svn-convert-branches.sh</pre>

Also, download [[Media:git-svn-convert-tags.sh|this shell script]] and run it to convert all the tag branches created by <code>git svn</code> into proper git tags:
<pre>sh Git-svn-convert-tags.sh</pre>

Now, check <code>git log --graph --oneline --all --decorate=full</code> to see whether the conversion turned out to your liking. Also, check how large the repository became. If it turned out larger than you would expect it is probably caused by smaller or larger binary artifacts that have been committed into the SVN repository. If it turns out you want to leave certain projects outside the git svn conversion, you can use the <code>--ignore-paths</code> argument with <code>git svn init</code>. For example you could use <code>--ignore-paths 'org.simantics.openmodelica|org.simantics.om'</code> to leave out all projects starting with <code>org.simantics.openmodelica</code> or <code>org.simantics.om</code>.

If you are satisfied, push all the commits and tags to remote <code>origin</code>:
<pre>
$ git push --all
$ git push --tags
</pre>

The branch/tag conversion scripts are heavily inspired by the script available at http://timepit.eu/~frank/blog/2008/08/converting_git-svn_tags/.

=== Why are there .keep files in Git repository folders? ===

* https://git.wiki.kernel.org/index.php/GitFaq#Can_I_add_empty_directories.3F
* http://stackoverflow.com/questions/115983/how-can-i-add-an-empty-directory-to-a-git-repository

Our recommendation is to add an empty file named ''.keep'' to the empty folder to ensure it is kept in git.

=== How can I make gerrit check X? ===

Gerrit integrates a prolog based submit rule system that seems to be the ultimate measure for configuring how reviews work. The prolog rules can be used, among other things, to achieve the following:
* Example 8: Make change submittable only if Code-Review+2 is given by a non author
* Example 13: 1+1=2 Code-Review
* Example 15: Only allow Author to submit change

See the cookbook at: https://gerrit-review.googlesource.com/Documentation/prolog-cookbook.html

== Schedule ==

We have set 16th December 2016 as the date when the Simantics SVN repository project locations trunks will be made read-only.

Only those locations that have been indicated as transferred to git in [[#Transferred Projects]] have been marked read-only.

== SVN to Git Transition TODO ==

* Test and migrate all products trunk versions on top of the simantics-platform git master branch.
* <strike>Fix the SDK org.simantics.root build to produce source bundles. It should work already but it just doesn't at the moment. Perhaps something needs to defined in org.simantics.sdk.repository/pom.xml.</strike>
* <strike>Set a date for when SVN trunks will be changed to read-only (16.12.2016)</strike>
** <strike>E-mail simantics-developers with instructions or links to instructions about the change.</strike>
* <strike>Double check all instructions:</strike>
** <strike>Basic Eclipse IDE installation with Simantics graph compiler</strike>
** <strike>Git instructions and platform development workflow</strike>
** <strike>Gerrit instructions and practices. Only project owners shall have the right for direct push to git repositories. Others must always go through gerrit review. This is enforced via Gerrit access rights.
</strike>
* <strike>Organize brief training and feedback session the current developers (26.10.2016)</strike>

The next step is to start thinking about moving your project/product over to Gerrit!

Migration To Git

2016-12-29T14:38:06Z

Hannu Niemisto: /* Eclipse */

== Recommended Reading ==

* Official Gerrit introduction: https://gerrit-review.googlesource.com/Documentation/intro-quick.html.
* Gerrit tutorial: http://www.vogella.com/tutorials/Gerrit/article.html

== Instructions for Simantics Developers ==

=== Gerrit ===

# Request a Gerrit account. If you already have a SVN account, it should work also in Gerrit.
# Generate SSH Public/Private key. If you already have one available, skip this step
#* Windows
#** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
#** Run PuTTYgen and generate a key
#*** For Type of key to generate, select '''SSH-2 RSA'''
#*** Press '''Generate''' button
#*** Move your mouse over the window until the progress bar is finished
#*** Write a '''Key passphrase''' to protect your private key in case your local machine is compromised.
#*** Save the generated public and private keys in <code>C:\Users\{username}\.ssh</code> as follows:
#**** Start cmd.exe and create the target directory using <code>mkdir .ssh</code>
#**** Save private key using '''Conversions -> Export OpenSSH Key'''. The name <code>id_rsa</code> is preferred because it will work out of the box with all tools.
#**** At the top of the window, there is a text field labeled '''Public key for pasting into OpenSSH authorized_keys'''. Copy the public key from there and save it into a text file at <code>C:\Users\{username}\.ssh\id_rsa.pub</code>
#* Linux
#** Generate public and private keys using <code>ssh-keygen -t rsa</code>
# Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
# Select your name in the top-right corner and press ''Settings''
# Go to section '''SSH Public Keys'''
# Open the file containing the generated public key in a text editor and copy-paste its contents to the box in Gerrit and and press '''Add'''
# Add and verify your contact information (name + e-mail). This will allow administrators to add you to the necessary groups to get commit access:
#* Go to section '''Contact Information''' and enter your '''Full Name''' there
#* Add a '''Preferred Email''' address using the button '''Register New Email'''
#* Wait for the authorization mail to arrive. It will look something like the following and contain a longish link that tends to end with == characters. Note that outlook tends to leave the trailing == characters out of the link it generates automatically. That's why it is recommended to copy the full URL from the mail into your browser to verify your e-mail address.
<pre>Subject: [Gerrit Code Review] Email Verification

Welcome to Gerrit Code Review at www.simantics.org.

To add a verified email address to your user account, please
click on the following link while signed in as .....:

http://www.simantics.org:8088/r/#/../...............................................................................==

If you have received this mail in error, you do not need to take any
action to cancel the account. The address will not be activated, and
you will not receive any further emails.

If clicking the link above does not work, copy and paste the URL in a
new browser window instead.

This is a send-only email address. Replies to this message will not
be read or answered.
</pre>

<ol start="8">
<li>Finally, ask [[User:Tuukka Lehtonen]] to add you to the necessary groups and wait for this to happen.</li>
</ol>

=== Eclipse ===

The following instructions are written for Eclipse Neon. There might be some differences if you are using Mars.

# Go to preferences (General / Network Connections / SSH2) and ensure that '''SSH2 home''' points to the directory where you saved the private key.
# Go to preferences (Team / Git / Configuration) and ensure that the tab '''User Settings''' has the following two setting: <code>user.name</code> and <code>user.email</code>. The specified name and email must match the values you've put in Gerrit to be able to push changes. [[image:git-global-config.png|400px]]
#* Also, git has a setting called <code>core.autocrlf</code> which is used for controlling the way git enforces line feeds to be encoded in a certain way in commits. Read [https://git-scm.com/book/tr/v2/Customizing-Git-Git-Configuration#idp31554304 the documentation] to learn more. We recommend to set it <code>true</true> in Windows in order to avoid committing CRLFs to repostory.
#* If you have a git command line client installed you can use the command <code>git config --list --show-origin</code> to see your current global settings and find out exactly where your settings are coming from.
# Open ''Git'' perspective
# Press button '''Clone a Git Repository and add the clone to this view''' (third button in the toolbar of Git view)
# Select '''Clone URI''' (Don't select Gerrit, it doesn't work very well at the moment)
# Go back to Gerrit. Press '''Projects''' in the top-left menu and '''List''' in the submenu.
# Find a row named '''simantics/platform''' and press '''(gitweb)''' link at the last column.
# Copy the URI starting with ''ssh:'' (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to '''URI''' field in '''Clone Git Repository dialog'''.
# This should automatically fill the other fields.
# Press Next. If your private key has a passphrase, Eclipse now asks it.
# Select all branches to be cloned (default) and press Next.
# Give a local directory where the repository is cloned to and press Finish.
# After the cloning is finished, select the '''platform''' repository in the Git Repositories view and select '''Import Projects...''' from context menu.
# Press Next, select all projects but '''org.simantics.root''' and press Finish.
# Expand the tree view of '''platform''', expand '''Branches''' under it and '''Local''' under it. Open context menu on '''master''' branch and select '''Configure Branch...'''. Select '''Rebase''' checkbox and press '''Ok'''.

The repository you cloned contains the target platform definition that needs to be set in order for the imported Simantics codebase to compile. You can find the required target platform definition file from '''org.simantics.sdk.build.targetdefinition/org.simantics.sdk.build.targetdefinition.target'''. Open it in the target definition editor and set it as the active target platform by pressing the link '''Set as Target Platform''' at the top right corner of the editor.

Congratulations, you've now set up your workspace for developing the Simantics codebase in Eclipse!

=== Updating your local repository and working space ===

# Open context menu on '''platform''' in the Git perspective and select '''Pull'''.

=== Committing your changes back to shared repository ===

# Select '''platform''' in the Git perspective and open '''Git Staging''' view.
# '''Unstaged Changes''' shows all files you have modified.
# Drag&drop those changes you want to commit to the box '''Staged Changes'''.
# Write a [[#Commit message format|commit message]]
# Ensure that '''Add Change-Id''' button is toggled down and the commit message contains a row starting ''Change-Id:''.
#* This is required by Gerrit to be able to bind commits to specific reviews. Gerrit will replace the default zero-valued Id with a generated one when the change is pushed for review.
# Press '''Commit and Push...'''
# This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
#* Example of a topic: http://www.simantics.org:8088/r/#/q/topic:svn
# Go to Gerrit. In the top-left menu select '''My''' and select '''Changes'''.
# Your change can be seen now in the section '''Outgoing reviews'''.
# Click the change. This opens a review page.
# Ask someone to review your change. This can be done also in Gerrit by pressing '''Add...''' button in the right of the '''Reviewers''' field.
# If you need to make modifications to your changes based on reviews, you'll need to ''Amend'' the earlier changes to send a new patch set to Gerrit. In this case, ensure that the ''Amend (Edit Previous Commit)'' button is toggled down and you should be able to modify the earlier commit message and push the amended changes.
# When somebody has reviewed and accepted the change with +2, the review page will contain a '''Submit''' button that can be used to merge the change to the master branch.

==== Commit message format ====

In Git, the first row of the commit message is used for ''shortlog'' and generating patch file names so keep it short, concise and as descriptive as possible. The commit box in the UI shows a vertical line marking the maximum length of a commit message line and the view will inform you if you're exceeding limits. Note that the commit message box will automatically break long lines of text into separate lines to help you write a cleanly formatted commit message.

To keep commits attached to [https://www.simantics.org/redmine/ Redmine] issues, use <code>refs #nnn</code>, where <code>nnn</code> is the issue number. This must be specified before ''Change-Id:''. The Simantics platform Gerrit is configured to show <code>refs #nnn</code> lines as hyperlinks to platform Redmine issues, i.e. to URL <code>https://www.simantics.org/redmine/issues/nnn</code>.

Often platform commits are also related to some issue or issues from other projects built on top of the platform. In order to retain some information about this association in the commit messages we recommend using separate rows in commit messages in form<code>[PRIVATE-mmm]</code> where <code>mmm</code> is the issue number in the other project.

Gerrit reviews require a row starting ''Change-Id:'' as the last row of the commit message (excluding Signed-off-by rows). This allows Gerrit to bind commits to specific reviews. Gerrit will replace the default zero-valued Id with a generated one when the change is pushed for review.

All in all, a typical commit message should look like this:
<pre>
Short description of my change in under 65 characters

A longer description of my changes
that can span multiple lines.

refs #nnn
[PRIVATE-mmm] (optional, use this if the commit relates to another project)

Change-Id: I0000000000000000000000000000000000000000
</pre>

== Simantics Member Read-only Git Access ==

# Register to member wiki at https://www.simantics.org/members/index.php
# Log into [http://www.simantics.org:8088/r/# Gerrit] using the credentials found at https://www.simantics.org/members/index.php/Code_Repository_Access
# Clone http://member@www.simantics.org:8088/r/p/simantics/platform.git using the HTTP password found at http://www.simantics.org:8088/r/#/settings/http-password

The [[#Eclipse|instructions for using Eclipse]] with this git repository apply also for the generic member account. Just remember to replace the cloned SSH repository address with the HTTP address shown above.

== Testing Reviewed Changes ==

To test reviewed code changes locally, first you must have an Eclipse IDE setup according to the instructions in [[#Instructions for Simantics Developers]] or [[#Simantics Member Read-only Git Access]].

Now, let's say for example we wish to grab a patch set from a review, such as review #72 (http://www.simantics.org:8088/r/72).

# Open '''Git''' perspective
# Select root node of the cloned simantics-platform repository from the '''Git Repositories''' view
# From the context menu of the repository, select '''Fetch from Gerrit...'''
# In the '''Change''' field, type the change number 72 and press CTRL+SPACE to start content assist. Content assist will provide you with the selections '''72 - 1''', and '''72 - 2''', i.e. patch sets 1 and 2 of change 72. After selecting a patch set, the field will be filled with the value '''refs/changes/72/72/1''' or '''refs/changes/72/72/2''' depending on the patch set you selected.
# The default settings are otherwise recommended, i.e. '''Create a Local Branch''' and ''Checkout new branch'' to switch to the new branch immediately.

There you have it, a local branch that has exactly the same repository state as in the code to be reviewed. Start testing!

== Platform Git Branching Model ==

Branch naming conventions:
* features: <code>feature/<PROJECT-NAME>-<issuenumber></code>.
** Use these for developing a single feature. To keep the version history of feature branches cleaner, merge commit pushing is limited to project owners only. This means that feature branches should be used for implementing a particular thing and then merged back to master or some other branch. They should not be used as locations for eternal development and never ending try-outs.
* releases: <code>release/x.y.z</code>, where x, y and z are major, minor and service version numbers respectively.
** Only for release stabilization branches.
* private work branches: <code>private/*</code>.
** Should be used for personal work, trials and possibly even user or project specific custom branches that need to be kept. Gerrit is not configured enforce any rules on how these branches are used.
* hotfixes: <code>hotfix/x.y.z.<hotfix number></code>.

Basic access rights:

{|border=1
|'''action''' \ '''head'''||'''master''' '''release/*''' '''hotfix/*'''||'''feature/*'''||'''private/*'''
|-
|''Code Review -/+2''||Simantics developers||Simantics developers||Simantics developers
|-
|''Submit''||Owners only||Simantics developers||Simantics developers
|-
|''Push''||Owners only||Simantics developers||Simantics developers
|-
|''Push Merge Commits''||Owners only||Owners Only||Simantics developers
|}

The current plan is to loosely follow [http://nvie.com/posts/a-successful-git-branching-model/ GitFlow] rules but we've decided to go without a separate <tt>develop</tt> branch. This means that we treat master as a development version instead of a production version. The actual <tt>release/*</tt> branches and tags are used to produce production versions. The rationale behind this is that we do not have a continuously evolving production version. Instead we produce new releases and products pick them up as they see fit.

Related reading:
* [http://nvie.com/posts/a-successful-git-branching-model/ Git Flow branching model] by Vincent Driessen
* http://endoflineblog.com/gitflow-considered-harmful

== Transferred Projects ==

The following table lists the Git repositories that have been created so far and where their content is from in the SVN repositories.

{|border=1
|'''SVN Location'''||'''Gerrit project'''
|-
|All over https://www.simantics.org/svn/simantics/||https://www.simantics.org:8088/r/#/admin/projects/simantics/platform
|-
|https://www.simantics.org/svn/simantics/3d||https://www.simantics.org:8088/r/#/admin/projects/simantics/3d
|-
|https://www.simantics.org/svn/simantics/fmi||https://www.simantics.org:8088/r/#/admin/projects/simantics/fmil
|-
|https://www.simantics.org/svn/simantics/r||https://www.simantics.org:8088/r/#/admin/projects/simantics/r
|-
|Everything except OpenModelica bundles from https://www.simantics.org/svn/simantics/sysdyn||https://www.simantics.org:8088/r/#/admin/projects/simantics/sysdyn
|-
|Parts of https://www.simantics.org/svn/simantics/third-party/trunk||https://www.simantics.org:8088/r/#/admin/projects/simantics/third-party
|-
|https://www.simantics.org/svn/members/fmi||https://www.simantics.org:8088/r/#/admin/projects/members/fmi
|}

=== Still Untransferred Project Locations ===

* https://www.simantics.org/svn/simantics/interoperability
* https://www.simantics.org/svn/simantics/modelica
* https://www.simantics.org/svn/simantics/sysdyn: OpenModelica parts need to be put in a separate repository due to the huge size of OM. Preferable this repository should support LFS
* https://www.simantics.org/svn/simantics/tutorials

== Q & A ==

=== Will the complete SVN history be transferred to Git? ===

Sadly, no it will not, at least for everything that is considered part of the current SVN Simantics SDK (see revisions list on page https://www.simantics.org/jenkins/job/target-simantics-head-sdk/lastStableBuild/).

The reason for not attempting to salvage the full history into git is in the Simantics SVN repository's structure. In SVN a "project structure" is a single combination of the folders ''trunk'', ''branches'' and ''tags''. In git branches and tags do not exist like this as separate directories in the repository itself. The [https://git-scm.com/docs/git-svn git-svn] tool is perfectly capable of transforming a single project structure into git repository with all its history, branches and tags. At some point in the past we for decided to split the SVN repository contents into multiple project structures in the hope of modularizing the platform SDK. That hope never quite realized and what's worse, that structure has made platform release engineering much more laborous and complex than it would be with a single project structure. Now in this move to Git we decided to simplify things and just put the platform SDK projects back in a single monolithic structure of bundles, features, tests and release engineering projects. All in all, we just didn't have enough git expertise to be able to transfer all the history scattered in these multiple project structures into a single git repository and moving the current SVN project structures each into its own git repository was not an enticing option either.

So how are we doing it right now? We have a separate migration git repository that contains a python script that simply exports all listed projects from SVN into the simantics-platform git repository structure. Our simantics-platform git repository contains a branch called 'svn'. The SVN exporting python script was originally used to initially populate the git repository, back when we were first testing the migration. Another python script is then used to bring in changes from SVN by exporting on top of the existing simantics-platform git repository. These changes are then committed into the svn branch and merged into master from there. We are not using git svn fetch because we're just not proficient enough with git-svn to be able to use it separately for each and every project that has moved location in git already. The git master branch has already been developed onwards, but merging changes from the svn branch to it is still very easy.

Note that the SVN repository will remain in place to keep all old versions of the platform that are still needed for maintaining existing products. We will not be moving these old branches/versions into git.

Note that in general if you have a single SVN project structure to transfer to git it is recommended to use <code>git svn</code> to transfer the complete history to Git.

=== How do I convert my SVN repository into a Gerrit/git project & repository? ===

The following is an example of converting a single SVN project location (<code>trunk/,branches/,tags/</code>) into a Gerrit-hosted git repository. The instructions assume you are working on a Linux installation which has the git command line tools installed.

SVN project structure location to be converted: https://www.simantics.org/svn/simantics/3d/

Firstly, create a new project in Gerrit ([https://www.simantics.org:8088/r/#/admin/create-project/]). Create the project without an empty initial commit because the initial commits will come from the SVN repository anyway. In this example the project name <code>simantics/3d</code> is used.

Next clone the newly created git repository:
<pre>git clone ssh://<your-username>@www.simantics.org:29418/simantics/3d.git</pre>

Step into the cloned repository directory:
<pre>cd 3d</pre>

Initialize <code>git svn</code> with the correct SVN repository location:
<pre>git svn init https://www.simantics.org/svn/simantics/3d --stdlayout --prefix=svn/</pre>

Start fetching commits from the SVN repository into the empty git repository:
<pre>git svn fetch | tee fetch.log</pre>

Next, due to the way in which <code>git svn</code> converts branches and tags, we want to do a bit of cleanup to convert the branches into local branches before pushing them to the Gerrit's repository. Download [[Media:git-svn-convert-branches.sh|this shell script]] and execute it in the repository's root directory:
<pre>sh Git-svn-convert-branches.sh</pre>

Also, download [[Media:git-svn-convert-tags.sh|this shell script]] and run it to convert all the tag branches created by <code>git svn</code> into proper git tags:
<pre>sh Git-svn-convert-tags.sh</pre>

Now, check <code>git log --graph --oneline --all --decorate=full</code> to see whether the conversion turned out to your liking. Also, check how large the repository became. If it turned out larger than you would expect it is probably caused by smaller or larger binary artifacts that have been committed into the SVN repository. If it turns out you want to leave certain projects outside the git svn conversion, you can use the <code>--ignore-paths</code> argument with <code>git svn init</code>. For example you could use <code>--ignore-paths 'org.simantics.openmodelica|org.simantics.om'</code> to leave out all projects starting with <code>org.simantics.openmodelica</code> or <code>org.simantics.om</code>.

If you are satisfied, push all the commits and tags to remote <code>origin</code>:
<pre>
$ git push --all
$ git push --tags
</pre>

The branch/tag conversion scripts are heavily inspired by the script available at http://timepit.eu/~frank/blog/2008/08/converting_git-svn_tags/.

=== Why are there .keep files in Git repository folders? ===

* https://git.wiki.kernel.org/index.php/GitFaq#Can_I_add_empty_directories.3F
* http://stackoverflow.com/questions/115983/how-can-i-add-an-empty-directory-to-a-git-repository

Our recommendation is to add an empty file named ''.keep'' to the empty folder to ensure it is kept in git.

=== How can I make gerrit check X? ===

Gerrit integrates a prolog based submit rule system that seems to be the ultimate measure for configuring how reviews work. The prolog rules can be used, among other things, to achieve the following:
* Example 8: Make change submittable only if Code-Review+2 is given by a non author
* Example 13: 1+1=2 Code-Review
* Example 15: Only allow Author to submit change

See the cookbook at: https://gerrit-review.googlesource.com/Documentation/prolog-cookbook.html

== Schedule ==

We have set 16th December 2016 as the date when the Simantics SVN repository project locations trunks will be made read-only.

Only those locations that have been indicated as transferred to git in [[#Transferred Projects]] have been marked read-only.

== SVN to Git Transition TODO ==

* Test and migrate all products trunk versions on top of the simantics-platform git master branch.
* <strike>Fix the SDK org.simantics.root build to produce source bundles. It should work already but it just doesn't at the moment. Perhaps something needs to defined in org.simantics.sdk.repository/pom.xml.</strike>
* <strike>Set a date for when SVN trunks will be changed to read-only (16.12.2016)</strike>
** <strike>E-mail simantics-developers with instructions or links to instructions about the change.</strike>
* <strike>Double check all instructions:</strike>
** <strike>Basic Eclipse IDE installation with Simantics graph compiler</strike>
** <strike>Git instructions and platform development workflow</strike>
** <strike>Gerrit instructions and practices. Only project owners shall have the right for direct push to git repositories. Others must always go through gerrit review. This is enforced via Gerrit access rights.
</strike>
* <strike>Organize brief training and feedback session the current developers (26.10.2016)</strike>

The next step is to start thinking about moving your project/product over to Gerrit!

SCL Tutorial

2016-11-22T15:21:52Z

Hannu Niemisto: /* Importing functionality from Java */

[[Category: Simantics Constraint Language]]
== Getting started ==

The easiest way of getting started with SCL is to use SCL console that is included in almost all Simantics-based products. You can open the console by pressing ALT-SHIFT-q and then q and choosing "SCL Console" from the list of views.

SCL console works by executing commands you write into the input box in the bottom of the view. After the command has been written, it can be executed by pressing ENTER. However, this works only if the command contains no syntactic errors. Possible errors are highlighted in the input box and a description of the error is shown when you move mouse on top of the highlighted text.

Multiline commands can be written by pressing CTRL-ENTER (or just ENTER when the current command text contains errors). The command history can be browsed with CTRL-UP and CTRL-DOWN.

If the command you write into console results as an ordinary value, it is just printed to the console. Here are couple of examples you can try:
<pre>
> 13
13
> 1+2
3
> sin 1
0.8414709848078965
> "Hello " + "world!"
Hello world!
> [1,3,5]
[1, 3, 5]
</pre>

You can also declare local variables to be used in the commands:
<pre>
> x = 35
> y = 40
> x + y
75
> x * y
1400
</pre>

Also new functions can be defined:
<pre>
> f x = x * x
> f 123
15129
</pre>

If you write a command that has side-effects, it is executed in the console:
<pre>
> print "Hello" ; print "world!"
Hello
world!
</pre>

SCL is a dialect of Haskell and tutorials written for Haskell can be used for learning the details of the language. The main differences between the languages are the strict evaluation strategy used in SCL and somewhat different standard library. Some Haskell tutorials can be found at [http://www.haskell.org/haskellwiki/Learning_Haskell http://www.haskell.org/haskellwiki/Learning_Haskell].

== Extending SCL environment ==

The SCL values, data types etc. that are available in expressions and commands are defined in SCL modules. Currently all SCL modules must be part of the product plugins (in the future, you can also write modules inside the models). Each module is identified by a URI.

SCL module is a text file ending with extension ".scl". The recommended place for modules is scl/ folder under plugin root, but also other directories can be used:

scl/Test1.scl:
<pre>
fib :: Integer -> Integer
fib x | x <= 1 = 1
| otherwise = fib (x-1) + fib (x-2)
</pre>

A directory is declared as a SCL package with the following kind of extension points defined in org.simantics.scl.runtime:
<pre>
<extension point="org.simantics.scl.runtime.package">
<package URI="http://www.simantics.org/Tests"
directory="scl"/>
</extension>
</pre>

The module is not automatically available in the console, but you must run an import declaration:
<pre>
> import "http://www.simantics.org/Tests/Test1" as Test1
> Test1.fib 13
377
</pre>

Import declaration can also be used in modules to refer other modules. Cyclic module dependencies are not allowed.

== Importing functionality from Java ==

Java interfaces and classes can be imported from Java by declaring them inside importJava block:
<pre>
importJava "java.util.regex.Pattern" where
data Pattern

importJava "java.util.List" where
data List a
</pre>

Java methods, constructors and fields can be similarly imported by giving
their type annotations in importJava block:
<pre>
importJava "java.util.regex.Pattern" where
@JavaName compile
compilePattern :: String -> Pattern

@JavaName matcher
createMatcher :: Pattern -> String -> <Proc> Matcher

importJava "java.util.regex.Matcher" where
data Matcher

@JavaName matches
matcherMatches :: Matcher -> <Proc> Boolean

matches : Pattern -> String -> <Proc> Boolean
matches pattern text = do
matcherMatches (createMatcher pattern text)
</pre>

Another example:
<pre>
importJava "java.util.ArrayList" where
@JavaName "<init>"
createArrayList :: () -> <Proc> List a

@JavaName "<init>"
createArrayListWithCapacity :: Integer -> <Proc> List a

@JavaName size
sizeList :: List a -> <Proc> Integer

@JavaName get
getList :: List a -> Integer -> <Proc> a

@JavaName set
setList :: List a -> Integer -> a -> <Proc> ()

@JavaName add
addList :: List a -> a -> <Proc> Boolean
</pre>

Java constructor is referred with "<init>". If Java method name and SCL name matches the annotation @JavaName can be left out. Java import mechanism tries to be quite flexible. It provides some arguments based on the effects the function has. It also ignores the return value of the Java method if return type is () in SCL.

A major functionality currently still missing is the ability to create new implementations of existing Java interfaces in SCL code or extend an existing class. This can be worked around currently by writing new implementations in Java.

Migration To Git

2016-09-30T13:38:12Z

Hannu Niemisto: /* Instructions for Simantics Developers */

Migration To Git

2016-08-18T11:31:16Z

Hannu Niemisto: /* Eclipse */

== Recommended Reading ==

* Gerrit introduction: https://gerrit-review.googlesource.com/Documentation/intro-quick.html.

== Gerrit ==

# Request a Gerrit account. If your already have a SVN account, it should work also in Gerrit.
# Generate SSH Public/Private key
#* Windows
#** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
#** Run PuTTYgen and generate a key
#*** Press '''Generate''' button
#*** Move your mouse over the window until the progress bar is finished
#*** Write a '''Key passphrase''' to protect your private key in case your local machine is compromised.
#*** Save the generated public and private keys to C:\Users\{username}\.ssh.
#* Linux
#** Generate public and private keys using ssh-keygen.
# Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
# Select your name in the top-right corner and press ''Settings''
# Go to section '''SSH Public Keys''', select '''Add Key ...'''.
# Open the file containing the generated public key in text editor and paste its content to the box in Gerrit and and press '''Add'''

== Eclipse ==

The following instructions are written for Eclipse Neon. There might be some differences if you are using Mars.

# Go to preferences (General / Network Connections / SSH2) and ensure that '''SSH2 home''' points to the directory where you saved the private key.
# Open ''Git'' perspective
# Press button '''Clone a Git Repository and add the clone to this view''' (third button in the toolbar of Git view)
# Select '''Clone URI''' (Don't select Gerrit, it doesn't work very well at the moment)
# Go back to Gerrit. Press '''Projects''' in the top-left menu and '''List''' in the submenu.
# Find a row named '''simantics/platform''' and press '''(gitweb)''' link at the last column.
# Copy the URI starting with ''ssh:'' (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to '''URI''' field in '''Clone Git Repository dialog'''.
# This should automatically fill the other fields.
# Press Next. If your private key has a passphrase, Eclipse now asks it.
# Select all branches to be cloned (default) and press Next.
# Give a local directory where the repository is cloned to and press Finish.
# After the cloning is finished, select the '''platform''' repository in the Git Repositories view and select '''Import Projects...''' from context menu.
# Press Next, select all projects but '''org.simantics.root''' and press Finish.
# Expand the tree view of '''platform''', expand '''Branches''' under it and '''Local''' under it. Open context menu on '''master''' branch and select '''Configure Branch...'''. Select '''Rebase''' checkbox.

== Updating your local repository and working space ==

# Open context menu on '''platform''' in the Git perspective and select '''Pull'''.

== Committing your changes back to shared repository ==

# Select '''platform''' in the Git perspective and open '''Git Staging''' view.
# '''Unstaged Changes''' shows all files you have modified.
# Drag&drop those changes you want to commit to the box '''Staged Changes'''.
# Write a commit message.
# Ensure that '''Add Change-Id''' button is toggled down and the commit message contains a row starting ''Change-Id:''
# Press '''Commit and Push...'''
# This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
#* Example of a topic: http://www.simantics.org:8088/r/#/q/topic:svnMerge
# Go to Gerrit. In the top-left menu select '''My''' and select '''Changes'''.
# Your change can be seen now in the section '''Outgoing reviews'''.
# Click the change. This opens a review page.
# Ask someone to review your change. This can be done also in Gerrit by pressing '''Add...''' button in the right of the '''Reviewers''' field.
# When somebody has reviewed the change, the review page contains a '''Submit''' button that can be used to merge the change to the master branch.

Migration To Git

2016-08-18T11:30:58Z

Hannu Niemisto: /* Eclipse */

== Recommended Reading ==

* Gerrit introduction: https://gerrit-review.googlesource.com/Documentation/intro-quick.html.

== Gerrit ==

# Request a Gerrit account. If your already have a SVN account, it should work also in Gerrit.
# Generate SSH Public/Private key
#* Windows
#** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
#** Run PuTTYgen and generate a key
#*** Press '''Generate''' button
#*** Move your mouse over the window until the progress bar is finished
#*** Write a '''Key passphrase''' to protect your private key in case your local machine is compromised.
#*** Save the generated public and private keys to C:\Users\{username}\.ssh.
#* Linux
#** Generate public and private keys using ssh-keygen.
# Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
# Select your name in the top-right corner and press ''Settings''
# Go to section '''SSH Public Keys''', select '''Add Key ...'''.
# Open the file containing the generated public key in text editor and paste its content to the box in Gerrit and and press '''Add'''

== Eclipse ==

The following instructions are written for Eclipse Neon. There might be some differences if you are using Mars.

# Go to preferences (General / Network Connections / SSH2) and ensure that '''SSH2 home''' points to the directory where you saved the private key.
# Open ''Git'' perspective
# Press button '''Clone a Git Repository and add the clone to this view''' (third button in the toolbar of Git view)
# Select '''Clone URI''' (Don't select Gerrit, it doesn't work very well at the moment)
# Go back to Gerrit. Press '''Projects''' in the top-left menu and '''List''' in the submenu.
# Find a row named '''simantics/platform''' and press '''(gitweb)''' link at the last column.
# Copy the URI starting with ''ssh:'' (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to '''URI''' field in '''Clone Git Repository dialog'''.
# This should automatically fill the other fields.
# Press Next. If your private key has a passphrase, Eclipse now asks it.
# Select all branches to be cloned (default) and press Next.
# Give a local directory where the repository is cloned to and press Finish.
# After the cloning is finished, select the '''platform''' repository in the Git Repositories view and select '''Import Projects...''' from context menu.
# Press Next, select all projects but org.simantics.root and press Finish.
# Expand the tree view of '''platform''', expand '''Branches''' under it and '''Local''' under it. Open context menu on '''master''' branch and select '''Configure Branch...'''. Select '''Rebase''' checkbox.

== Updating your local repository and working space ==

# Open context menu on '''platform''' in the Git perspective and select '''Pull'''.

== Committing your changes back to shared repository ==

# Select '''platform''' in the Git perspective and open '''Git Staging''' view.
# '''Unstaged Changes''' shows all files you have modified.
# Drag&drop those changes you want to commit to the box '''Staged Changes'''.
# Write a commit message.
# Ensure that '''Add Change-Id''' button is toggled down and the commit message contains a row starting ''Change-Id:''
# Press '''Commit and Push...'''
# This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
#* Example of a topic: http://www.simantics.org:8088/r/#/q/topic:svnMerge
# Go to Gerrit. In the top-left menu select '''My''' and select '''Changes'''.
# Your change can be seen now in the section '''Outgoing reviews'''.
# Click the change. This opens a review page.
# Ask someone to review your change. This can be done also in Gerrit by pressing '''Add...''' button in the right of the '''Reviewers''' field.
# When somebody has reviewed the change, the review page contains a '''Submit''' button that can be used to merge the change to the master branch.

Migration To Git

2016-08-17T07:11:22Z

Hannu Niemisto:

== Gerrit ==

# Request a Gerrit account. If your already have a SVN account, it should work also in Gerrit.
# Generate SSH Public/Private key
#* Windows
#** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
#** Run PuTTYgen and generate a key
#*** Press '''Generate''' button
#*** Move your mouse over the window until the progress bar is finished
#*** Write a '''Key passphrase''' to protect your private key in case your local machine is compromised.
#*** Save the generated public and private keys to C:\Users\{username}\.ssh.
#* Linux
#** Generate public and private keys using ssh-keygen.
# Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
# Select your name in the top-right corner and press ''Settings''
# Go to section '''SSH Public Keys''', select '''Add Key ...'''.
# Open the file containing the generated public key in text editor and paste its content to the box in Gerrit and and press '''Add'''

== Eclipse ==

The following instructions are written for Eclipse Neon. There might be some differences if you are using Mars.

# Go to preferences (General / Network Connections / SSH2) and ensure that '''SSH2 home''' points to the directory where you saved the private key.
# Open ''Git'' perspective
# Press button '''Clone a Git Repository and add the clone to this view''' (third button in the toolbar of Git view)
# Select '''Clone URI''' (Don't select Gerrit, it doesn't work very well at the moment)
# Go back to Gerrit. Press '''Projects''' in the top-left menu and '''List''' in the submenu.
# Find a row named '''simantics/platform''' and press '''(gitweb)''' link at the last column.
# Copy the URI starting with ''ssh:'' (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to '''URI''' field in '''Clone Git Repository dialog'''.
# This should automatically fill the other fields.
# Press Next. If your private key has a passphrase, Eclipse now asks it.
# Select all branches to be cloned (default) and press Next.
# Give a local directory where the repository is cloned to and press Finish.
# After the cloning is finished, select the '''platform''' repository in the Git Repositories view and select '''Import Projects...''' from context menu.
# Press Next, select all projects (default) and press Finish.
# Expand the tree view of '''platform''', expand '''Branches''' under it and '''Local''' under it. Open context menu on '''master''' branch and select '''Configure Branch...'''. Select '''Rebase''' checkbox.

== Updating your local repository and working space ==

# Open context menu on '''platform''' in the Git perspective and select '''Pull'''.

== Committing your changes back to shared repository ==

# Select '''platform''' in the Git perspective and open '''Git Staging''' view.
# '''Unstaged Changes''' shows all files you have modified.
# Drag&drop those changes you want to commit to the box '''Staged Changes'''.
# Write a commit message.
# Ensure that '''Add Change-Id''' button is toggled down and the commit message contains a row starting ''Change-Id:''
# Press '''Commit and Push...'''
# This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
#* Example of a topic: http://www.simantics.org:8088/r/#/q/topic:svnMerge
# Go to Gerrit. In the top-left menu select '''My''' and select '''Changes'''.
# Your change can be seen now in the section '''Outgoing reviews'''.
# Click the change. This opens a review page.
# Ask someone to review your change. This can be done also in Gerrit by pressing '''Add...''' button in the right of the '''Reviewers''' field.
# When somebody has reviewed the change, the review page contains a '''Submit''' button that can be used to merge the change to the master branch.

Migration To Git

2016-08-16T07:54:52Z

Hannu Niemisto:

== Gerrit ==

# Request a Gerrit account. If your already have a SVN account, it should work also in Gerrit.
# Generate SSH Public/Private key
#* Windows
#** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
#** Run PuTTYgen and generate a key
#*** Press '''Generate''' button
#*** Move your mouse over the window until the progress bar is finished
#*** Write a '''Key passphrase''' to protect your private key in case your local machine is compromised.
#*** Save the generated public and private keys to C:\Users\{username}\.ssh.
#* Linux
#** Generate public and private keys using ssh-keygen.
# Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
# Select your name in the top-right corner and press ''Settings''
# Go to section '''SSH Public Keys''', select '''Add Key ...'''.
# Open the file containing the generated public key in text editor and paste its content to the box in Gerrit and and press '''Add'''

== Eclipse ==

# Go to preferences (General / Network Connections / SSH2) and ensure that '''SSH2 home''' points to the directory where you saved the private key.
# Open ''Git'' perspective
# Press button '''Clone a Git Repository and add the clone to this view''' (third button in the toolbar of Git view)
# Select '''Clone URI''' (Don't select Gerrit, it doesn't work very well at the moment)
# Go back to Gerrit. Press '''Projects''' in the top-left menu and '''List''' in the submenu.Repositories
# Find a row named '''simantics/platform''' and press '''(gitweb)''' link at the last column.
# Copy the URI starting with ''ssh:'' (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to '''URI''' field in '''Clone Git Repository dialog'''.
# This should automatically fill the other fields.
# Press Next. If your private key has a passphrase, Eclipse now asks it.
# Select all branches to be cloned (default) and press Next.
# Give a local directory where the repository is cloned to and press Finish.
# After the cloning is finished, select the '''platform''' repository in the Git Repositories view and select '''Import Projects...''' from context menu.
# Press Next, select all projects (default) and press Finish.
# Expand the tree view of '''platform''', expand '''Branches''' under it and '''Local''' under it. Open context menu on '''master''' branch and select '''Configure Branch...'''. Select '''Rebase''' checkbox.

== Updating your local repository and working space ==

# Open context menu on '''platform''' in the Git perspective and select '''Pull'''.

== Committing your changes back to shared repository ==

# Select '''platform''' in the Git perspective and open '''Git Staging''' view.
# '''Unstaged Changes''' shows all files you have modified.
# Drag&drop those changes you want to commit to the box '''Staged Changes'''.
# Write a commit message.
# Ensure that '''Add Change-Id''' button is toggled down and the commit message contains a row starting ''Change-Id:''
# Press '''Commit and Push...'''
# This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
# Go to Gerrit. In the top-left menu select '''My''' and select '''Changes'''.
# Your change can be seen now in the section '''Outgoing reviews'''.
# Click the change. This opens a review page.
# Ask someone to review your change. This can be done also in Gerrit by pressing '''Add...''' button in the right of the '''Reviewers''' field.
# When somebody has reviewed the change, the review page contains a '''Submit''' button that can be used to merge the change to the master branch.

Migration To Git

2016-08-16T07:52:47Z

Hannu Niemisto:

== Gerrit ==

# Request a Gerrit account. If your already have a SVN account, it should work also in Gerrit.
# Generate SSH Public/Private key
#* Windows
#** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
#** Run PuTTYgen and generate a key
#*** Press '''Generate''' button
#*** Move your mouse over the window until the progress bar is finished
#*** Write a '''Key passphrase''' to protect your private key in case your local machine is compromised.
#*** Save the generated public and private keys to C:\Users\{username}\.ssh.
#* Linux
#** Generate public and private keys using ssh-keygen.
# Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
# Select your name in the top-right corner and press''Settings''
# Go to section '''SSH Public Keys''', select '''Add Key ...'''.
# Open the file containing the generated public key in text editor and paste its content to the box in Gerrit and and press '''Add'''

== Eclipse ==

# Go to preferences (General / Network Connections / SSH2) and ensure that '''SSH2 home''' points to the directory where you generated the private key.
# Open ''Git'' perspective
# Press button '''Clone a Git Repository and add the clone to this view''' (third button in the toolbar of Git view)
# Select '''Clone URI''' (Don't select Gerrit, it doesn't work very well at the moment)
# Go back to Gerrit. Press '''Projects''' in the top-left menu and '''List''' in the submenu.Repositories
# Find a row named '''simantics/platform''' and press '''(gitweb)''' link at the last column.
# Copy the URI starting with ''ssh:'' (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to '''URI''' field in '''Clone Git Repository dialog'''.
# This should automatically fill the other fields.
# Press Next. If your private key has a passphrase, Eclipse now asks it.
# Select all branches to be cloned (default) and press Next.
# Give a local directory where the repository is cloned to and press Finish.
# After the cloning is finished, select the '''platform''' repository in the Git Repositories view and select '''Import Projects...''' from context menu.
# Press Next, select all projects (default) and press Finish.
# Expand the tree view of '''platform''', expand '''Branches''' under it and '''Local''' under it. Open context menu on '''master''' branch and select '''Configure Branch...'''. Select '''Rebase''' checkbox.

== Updating your local repository and working space ==

# Open context menu on '''platform''' in the Git perspective and select '''Pull'''.

== Committing your changes back to shared repository ==

# Select '''platform''' in the Git perspective and open '''Git Staging''' view.
# '''Unstaged Changes''' shows all files you have modified.
# Drag&drop those changes you want to commit to the box '''Staged Changes'''.
# Write a commit message.
# Ensure that '''Add Change-Id''' button is toggled down and the commit message contains a row starting ''Change-Id:''
# Press '''Commit and Push...'''
# This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
# Go to Gerrit. In the top-left menu select '''My''' and select '''Changes'''.
# Your change can be seen now in the section '''Outgoing reviews'''.
# Click the change. This opens a review page.
# Ask someone to review your change. This can be done also in Gerrit by pressing '''Add...''' button in the right of the '''Reviewers''' field.
# When somebody has reviewed the change, the review page contains a '''Submit''' button that can be used to merge the change to the master branch.

Migration To Git

2016-08-16T07:51:21Z

Hannu Niemisto:

== Gerrit ==

# Request a Gerrit account.
# Generate SSH Public/Private key
#* Windows
#** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
#** Run PuTTYgen and generate a key
#*** Press '''Generate''' button
#*** Move your mouse over the window until the progress bar is finished
#*** Write a '''Key passphrase''' to protect your private key in case your local machine is compromised.
#*** Save the generated public and private keys to C:\Users\{username}\.ssh.
#* Linux
#** Generate public and private keys using ssh-keygen.
# Go to http://www.simantics.org:8088/r/ and log in with your Gerrit username/password
# Select your name in the top-right corner and press''Settings''
# Go to section '''SSH Public Keys''', select '''Add Key ...'''.
# Open the file containing the generated public key in text editor and paste its content to the box in Gerrit and and press '''Add'''

== Eclipse ==

# Go to preferences (General / Network Connections / SSH2) and ensure that '''SSH2 home''' points to the directory where you generated the private key.
# Open ''Git'' perspective
# Press button '''Clone a Git Repository and add the clone to this view''' (third button in the toolbar of Git view)
# Select '''Clone URI''' (Don't select Gerrit, it doesn't work very well at the moment)
# Go back to Gerrit. Press '''Projects''' in the top-left menu and '''List''' in the submenu.Repositories
# Find a row named '''simantics/platform''' and press '''(gitweb)''' link at the last column.
# Copy the URI starting with ''ssh:'' (ssh://{username}@www.simantics.org:29418/simantics/platform.git) and paste it to '''URI''' field in '''Clone Git Repository dialog'''.
# This should automatically fill the other fields.
# Press Next. If your private key has a passphrase, Eclipse now asks it.
# Select all branches to be cloned (default) and press Next.
# Give a local directory where the repository is cloned to and press Finish.
# After the cloning is finished, select the '''platform''' repository in the Git Repositories view and select '''Import Projects...''' from context menu.
# Press Next, select all projects (default) and press Finish.
# Expand the tree view of '''platform''', expand '''Branches''' under it and '''Local''' under it. Open context menu on '''master''' branch and select '''Configure Branch...'''. Select '''Rebase''' checkbox.

== Updating your local repository and working space ==

# Open context menu on '''platform''' in the Git perspective and select '''Pull'''.

== Committing your changes back to shared repository ==

# Select '''platform''' in the Git perspective and open '''Git Staging''' view.
# '''Unstaged Changes''' shows all files you have modified.
# Drag&drop those changes you want to commit to the box '''Staged Changes'''.
# Write a commit message.
# Ensure that '''Add Change-Id''' button is toggled down and the commit message contains a row starting ''Change-Id:''
# Press '''Commit and Push...'''
# This opens a dialog that asks the Gerrit Branch and a Topic. Topic can be added optionally to tie multiple changes together.
# Go to Gerrit. In the top-left menu select '''My''' and select '''Changes'''.
# Your change can be seen now in the section '''Outgoing reviews'''.
# Click the change. This opens a review page.
# Ask someone to review your change. This can be done also in Gerrit by pressing '''Add...''' button in the right of the '''Reviewers''' field.
# When somebody has reviewed the change, the review page contains a '''Submit''' button that can be used to merge the change to the master branch.

Migration To Git

2016-08-16T07:39:50Z

Hannu Niemisto:

Migration To Git

2016-08-16T07:37:51Z

Hannu Niemisto:

Migration To Git

2016-08-16T07:31:02Z

Hannu Niemisto: Created page with "== Gerrit == # Request a Gerrit account. # Generate SSH Public/Private key #* Windows #** Install PuTTY (msi) or download only PuTTYgen (exe) (http://www.chiark.greenend.org...."

Quick Development Environment Setup

2015-12-01T07:25:35Z

Hannu Niemisto:

__TOC__

== Install Java JDK and Eclipse, and Setup the IDE for Simantics Development ==

# Get and install ''Java SE Development Kit 8'' (JDK 8). You can download the package from [http://www.oracle.com/technetwork/java/javase/downloads/index.html http://www.oracle.com/technetwork/java/javase/downloads/index.html]. Follow the installation instructions for your operating system. It is recommended to always use the latest JDK update.
# Get and install the latest ''Eclipse Classic IDE'' release build. You can find the package from [http://download.eclipse.org/eclipse/downloads/ http://download.eclipse.org/eclipse/downloads/]. You can select freely the installation location for the package, e.g. under your home directory. Just unzip the package to install Eclipse.
# After the installation of Eclipse, check that your Eclipse is set to use the right Java Runtime Environment (JRE):
#* In Eclipse platform, open "Window - Preferences".
#* Open page “Java / Installed JREs”.
#* Set the JRE to point to the previously installed JDK 8.
# Install the Simantics Graph Compiler:
#* In Eclipse platform, open “Help / Install New Software...”.
#* Set the installation site to "http://www.simantics.org/update/utils" in the “Work with” field and press “Add...”. Give the installation site link a name when asked.
#* Select from the list the latest "Ontology development / Graph feature" and proceed with the installation. Restart Eclipse after the installation.
# Install the Subversive plug-in to the Eclipse platform:
#* In Eclipse platform, open ''“Help / Install New Software...”''.
#* Select installation site "Luna - http://download.eclipse.org/releases/luna" to the “Work with” field from the preset list.
#* Click open the "Collaboration" folder and select from the list:
#** ''Subversive SVN Team Provider''
#** ''Subversive SVN JDT Ignore Extensions''
#: and proceed with the installation. Restart Eclipse after the installation.
# After restarting Eclipse, open the SVN Repository Exploring perspective:
#* In Eclipse platform, open “Window / Open Perspective / Other...”.
#* Select ''SVN Repository Exploring'' and press “OK”. Eclipse should open the “Install Connectors” dialog.
#* Select latest “SVN Kit 1.x.y” and press “Finish”, and proceed with the installation. Restart Eclipse after the installation.

== Install Simantics 1.17 Target Platform ==

# In Eclipse platform, activate the ''Plug-in Development'' perspective, either from the tab on the upper right corner of the Eclipse platform or from the “Window / Open Perspective / Other...” menu, and select ''Plug-in Development''.
# Create a new general project in Eclipse by:
#* Selecting “File / New / Project...” menu item.
#* In the "Select a wizard", select “General / Project” and press “Next”.
#* Give the project a name, e.g. "Simantics_target" and press "Finish".
# Copy one of the following files into your system to some temporary location:
#* [http://www.simantics.org/download/1.17/simantics.target http://www.simantics.org/download/1.17/simantics.target] (for application development on Simantics platform)
#: The Simantics platform source code is available for [https://www.simantics.org/simantics/about-simantics/thth-simantics THTH/Simantics Division] registered members through these alternative target definitions (user name and password are asked during the installation, these are available at the [https://www.simantics.org/members/index.php/Main_Page THTH/Simantics Member Wiki]):
#* [http://www.simantics.org/download/1.17/simantics-sdk.target http://www.simantics.org/download/1.17/simantics-sdk.target] (for Simantics platform development and application development on Simantics platform)
# In Eclipse ''Package Explorer'' (the view on left side of the Eclipse platform):
#* Right-click your previously created project and select "Import..." from the context menu.
#* In ''Select wizard'', select “General / File System”, and press "Next".
#* Select in the “From directory” the folder where the previously downloaded file(s) are located, and select the downloaded file(s) in the file list below. Press "Finish".
# Set the target platform for the development with Simantics:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* The new target definitions should be available in the list. Activate one of the following:
#** “Simantics 1.17” (for application development on Simantics platform)
#** “Simantics SDK 1.17” (for Simantics platform development and application development on Simantics platform)
#: and confirm the target platform definition by pressing "Apply" and/or "OK". If you defined a ''Simantics SDK 1.17'' target, you are asked for the username and the password.
#* Wait until Eclipse finishes downloading, this may take a while. After the download is completed, there should be several plug-ins starting with "org.simantics.*" in the Eclipse ''Plug-ins'' view (the view on the left side of Eclipse).
# '''Keep your platform up-to-date!''' Updating is as easy as reloading the target platform from ''Target Platform'' preference page:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* Select the active target platform, e.g. ''Simantics SDK 1.17'', from the list and press "Reload".
#* Wait until the platform is updated.

== Test Your Installation ==

Test your installation with the [http://dev.simantics.org/index.php/Tutorial:_Ontology_Development Simantics movie tutorial]:

# Download ''Simantics movie tutorial'' plug-ins into your Eclipse workspace:
#* Get [https://www.simantics.org/jenkins/job/package-movie-tutorial-head/lastSuccessfulBuild/artifact/movie-tutorial.zip movie-tutorial.zip]
#* In Eclipse platform, select “File / Import...” menu item.
#* In the "Select" dialog, select “General / Existing Projects into Workspace” and press “Next”.
#* Select the “Select archive file:” radio button and press “Browse” to find the downloaded movie-tutorial.zip.
#* Press “Select All” and “Finish”.
# Run movie.product:
#* From the ''Package Explorer'' view, open “org.simantics.movie.ui'' / Movie.product”.
#* From the ''Overview'' page of the opened product editor, press “Launch an Eclipse application”.

If you managed to start the ''movie'' product, your development platform should be operational.

'''''Happy developing with Simantics!'''''

Quick Development Environment Setup

2015-12-01T07:23:22Z

Hannu Niemisto:

__TOC__

== Install Java JDK and Eclipse, and Setup the IDE for Simantics Development ==

# Get and install ''Java SE Development Kit 8'' (JDK 8). You can download the package from [http://www.oracle.com/technetwork/java/javase/downloads/index.html http://www.oracle.com/technetwork/java/javase/downloads/index.html]. Follow the installation instructions for your operating system. It is recommended to always use the latest JDK update.
# Get and install the latest ''Eclipse Classic IDE'' 4.4.1 (Luna SR1) release build. You can find the package from [http://download.eclipse.org/eclipse/downloads/ http://download.eclipse.org/eclipse/downloads/]. You can select freely the installation location for the package, e.g. under your home directory. Just unzip the package to install Eclipse.
# After the installation of Eclipse, check that your Eclipse is set to use the right Java Runtime Environment (JRE):
#* In Eclipse platform, open "Window - Preferences".
#* Open page “Java / Installed JREs”.
#* Set the JRE to point to the previously installed JDK 8.
# Install the Simantics Graph Compiler:
#* In Eclipse platform, open “Help / Install New Software...”.
#* Set the installation site to "http://www.simantics.org/update/utils" in the “Work with” field and press “Add...”. Give the installation site link a name when asked.
#* Select from the list the latest "Ontology development / Graph feature" and proceed with the installation. Restart Eclipse after the installation.
# Install the Subversive plug-in to the Eclipse platform:
#* In Eclipse platform, open ''“Help / Install New Software...”''.
#* Select installation site "Luna - http://download.eclipse.org/releases/luna" to the “Work with” field from the preset list.
#* Click open the "Collaboration" folder and select from the list:
#** ''Subversive SVN Team Provider''
#** ''Subversive SVN JDT Ignore Extensions''
#: and proceed with the installation. Restart Eclipse after the installation.
# After restarting Eclipse, open the SVN Repository Exploring perspective:
#* In Eclipse platform, open “Window / Open Perspective / Other...”.
#* Select ''SVN Repository Exploring'' and press “OK”. Eclipse should open the “Install Connectors” dialog.
#* Select latest “SVN Kit 1.x.y” and press “Finish”, and proceed with the installation. Restart Eclipse after the installation.

== Install Simantics 1.17 Target Platform ==

# In Eclipse platform, activate the ''Plug-in Development'' perspective, either from the tab on the upper right corner of the Eclipse platform or from the “Window / Open Perspective / Other...” menu, and select ''Plug-in Development''.
# Create a new general project in Eclipse by:
#* Selecting “File / New / Project...” menu item.
#* In the "Select a wizard", select “General / Project” and press “Next”.
#* Give the project a name, e.g. "Simantics_target" and press "Finish".
# Copy one of the following files into your system to some temporary location:
#* [http://www.simantics.org/download/1.17/simantics.target http://www.simantics.org/download/1.17/simantics.target] (for application development on Simantics platform)
#: The Simantics platform source code is available for [https://www.simantics.org/simantics/about-simantics/thth-simantics THTH/Simantics Division] registered members through these alternative target definitions (user name and password are asked during the installation, these are available at the [https://www.simantics.org/members/index.php/Main_Page THTH/Simantics Member Wiki]):
#* [http://www.simantics.org/download/1.17/simantics-sdk.target http://www.simantics.org/download/1.17/simantics-sdk.target] (for Simantics platform development and application development on Simantics platform)
# In Eclipse ''Package Explorer'' (the view on left side of the Eclipse platform):
#* Right-click your previously created project and select "Import..." from the context menu.
#* In ''Select wizard'', select “General / File System”, and press "Next".
#* Select in the “From directory” the folder where the previously downloaded file(s) are located, and select the downloaded file(s) in the file list below. Press "Finish".
# Set the target platform for the development with Simantics:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* The new target definitions should be available in the list. Activate one of the following:
#** “Simantics 1.17” (for application development on Simantics platform)
#** “Simantics SDK 1.17” (for Simantics platform development and application development on Simantics platform)
#: and confirm the target platform definition by pressing "Apply" and/or "OK". If you defined a ''Simantics SDK 1.17'' target, you are asked for the username and the password.
#* Wait until Eclipse finishes downloading, this may take a while. After the download is completed, there should be several plug-ins starting with "org.simantics.*" in the Eclipse ''Plug-ins'' view (the view on the left side of Eclipse).
# '''Keep your platform up-to-date!''' Updating is as easy as reloading the target platform from ''Target Platform'' preference page:
#* In Eclipse platform, open “Window / Preferences”, and from there the “Plug-in Development / Target Platform” folder.
#* Select the active target platform, e.g. ''Simantics SDK 1.17'', from the list and press "Reload".
#* Wait until the platform is updated.

== Test Your Installation ==

Test your installation with the [http://dev.simantics.org/index.php/Tutorial:_Ontology_Development Simantics movie tutorial]:

# Download ''Simantics movie tutorial'' plug-ins into your Eclipse workspace:
#* Get [https://www.simantics.org/jenkins/job/package-movie-tutorial-head/lastSuccessfulBuild/artifact/movie-tutorial.zip movie-tutorial.zip]
#* In Eclipse platform, select “File / Import...” menu item.
#* In the "Select" dialog, select “General / Existing Projects into Workspace” and press “Next”.
#* Select the “Select archive file:” radio button and press “Browse” to find the downloaded movie-tutorial.zip.
#* Press “Select All” and “Finish”.
# Run movie.product:
#* From the ''Package Explorer'' view, open “org.simantics.movie.ui'' / Movie.product”.
#* From the ''Overview'' page of the opened product editor, press “Launch an Eclipse application”.

If you managed to start the ''movie'' product, your development platform should be operational.

'''''Happy developing with Simantics!'''''

Simantics Developer Documentation

2015-11-26T07:47:24Z

Hannu Niemisto: /* Simantics Constraint Language */

__NOTOC__
[[image:Simantics_logo_pile_01.png|right|border|400px]]

'''Simantics''' is a software platform for modelling and simulation. The system has client-server architecture with a semantic ontology-based modelling database and Eclipse framework -based client software with plug-in interface. The Simantics platform and many of its components are open source under [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License (EPL)].

The philosophy of the Simantics platform is to offer an open, high level application platform on which different computational tools can be easily integrated to form a common environment for modelling and simulation. The platform includes several modelling tools, so-called editors, for e.g. 2D graph-like hierarchical model composition and semantic graph browsing.

One of the biggest innovations in the Simantics platform is the semantic modelling approach itself and high-level ontology tools. The semantic database, i.e. triplestore, on the server side enables high performance data management and arbitrary mappings of data. This enables e.g. efficient mapping of simulation and measurement data to the model configuration and its visualisation.

The Simantics development and maintenance process is built to be solid and scalable from the very beginning. The objective is to aim far to the future what comes to requirements for scalability, usability, and reliability.

This ''Simantics Developer Documentation'' is targeted to programmers and software developers developing either the platform itself or additional plug-ins to be used with or on the platform. The [[userwiki:Main_Page|Simantics End User Documentation]] complements to documentation for the Simantics platform offering overview and detailed information about the platform from the user's point of view. The [https://www.simantics.org/simantics Simantics] website is the source of information for the Simantics project and related subjects[[Tutorials|.]]
<div style="color:white;">Disclaimer Warning: This site may cause narcolepsia in some readers. Consult your doctor if sensitive to boredom.</div>

{|width="75%"
|width="25%" valign="top"|
=== Overview ===

* [[Glossary]]
* [[Introduction to Simantics Architecture]]
* [[Roadmap]]
* [[Data View]]
* [[Component View]]
* [[Licensing|Licensing]]
* [[Useful Links]]


|width="25%" valign="top"|

=== Miscellaneous Documents ===

* [[Quick Development Environment Setup|Quick Development Environment Setup Guide]]
* [[Target Platform]]
* [[Development Practices]]
* [[Internalization]]
* [[Update Site]]
* [[Coding Convention]]
* [[Tools]]
* [[Testing]]
* [[FAQ]]

|width="25%" valign="top"|

|}

{|width="100%"

|width="25%" valign="top"|

=== Ontology Development ===

* [[:Media:Layer0.pdf|Layer0.pdf]] ([[:File:Layer0.pdf|log]])
* [[Graph Compiler]]
* [[Transferable Graph]]
* [[Binary Container Format]]
* [[Graph File Format]]
* [[Version Migration]]
* [[Tutorial: Ontology Development]]

|width="25%" valign="top"|

=== Database Development ===

* [[Interface summary]]
* [[Tutorial: Quickstart]]
* [[Tutorial: Database Development]]
* [[Resource Adaptation]]
* [[Resource Serialization]]
* [[Inverse Relations]]
* [[Virtual Graphs]]
* [[Functions]]
* [[Procedural Values]]
* [[Variable]]
* [[Undo Mechanism]]
* [[Team Features]]
* [[Subgraph Extents]]
* [[Database Testing]]

|width="25%" valign="top"|

=== Data management & Experiment Control ===

* [[Databoard Specification]]
* [[Databoard Developer Manual|Databoard Java Manual]]
* [[Experiment Control]]
* [[Dataflows]]

|width="25%" valign="top"|

=== UI Development ===

* [[Org.simantics.browsing.ui_Manual|Browser Manual]]
* [[org.simantics.browsing.ui.feature|Browser Component]]
* [[Org.simantics.scenegraph.loader|Scene Graph Loader]]
* [[Org.simantics.message|Messages]]
* [[Org.simantics.views|Modelled Views]]
* [[Org.simantics.document|Documents]]
* [[Selection View]]
|}
{|width="100%"
|width="25%" valign="top"|

=== Simantics Constraint Language===

* [http://www.simantics.org/~niemisto/Introduction%20to%20SCL.pptx Introduction to SCL]
* [[SCL Compiler]]
* [[SCL Tutorial]]
* [[SCL Types]]


* [[Org.simantics.objmap_Manual|Object Map Manual]]
* [[SCL Registry]]
* [http://www.simantics.org/SCLDocumentation/StandardLibrary/Prelude.html SCL Reference]

|width="25%" valign="top"|

=== Model Development ===

* [[Structural Ontology]]
* [[Users and Roles]]
* [[Models]]
* [[Concept Versioning]]
* [[Component Identification]]
* [[Tutorial: Model Development]]

|width="25%" valign="top"|

=== Project Development ===

* [[Project Management Conceptual Model]]
* [[Project Development]]
* [[Tutorial: Project Development]]

|width="25%" valign="top"|

=== Diagram Development ===

* [[2D Ontologies]]
* [[org.simantics.diagram|Diagram]]
* [[org.simantics.scenegraph|Scene graph]]
* [[Diagram connections]]
* [[Tutorial: Diagram Development]]

|width="25%" valign="top"|

=== Issue Development ===

* [[Issue subsystem general description]]

|}

-----

File:Mapping5.png

2015-10-14T11:19:02Z

Hannu Niemisto:

Mapping

2015-10-14T11:18:47Z

Hannu Niemisto: /* Calculation level reference */

== Simplest possible connection ==

[[File:Mapping.png]]

== Connection flags ==

[[File:Mapping2.png]]

== Signal connection ==

[[File:Mapping3.png]]

== Calculation level reference ==

[[File:Mapping4.png]]

[[File:Mapping5.png]]

File:Mapping4.png

2015-02-04T14:43:44Z

Hannu Niemisto:

Mapping

2015-02-04T14:43:30Z

Hannu Niemisto:

File:Mapping3.png

2014-12-22T12:12:11Z

Hannu Niemisto: Hannu Niemisto uploaded a new version of "File:Mapping3.png"

Mapping

2014-12-22T11:53:16Z

Hannu Niemisto:

== Simplest possible connection ==

[[File:Mapping.png]]

== Connection flags ==

[[File:Mapping2.png]]

== Signal connection ==

[[File:Mapping3.png]]

File:Mapping3.png

2014-12-22T11:52:21Z

Hannu Niemisto:

File:Mapping2.png

2014-12-22T11:51:52Z

Hannu Niemisto:

File:Mapping.png

2014-12-22T11:51:26Z

Hannu Niemisto:

Mapping

2014-12-22T11:50:33Z

Hannu Niemisto: Created page with "File:Mapping.png File:Mapping2.png File:Mapping3.png"

[[File:Mapping.png]]

[[File:Mapping2.png]]

[[File:Mapping3.png]]

Subgraph operations

2013-11-12T21:22:40Z

Hannu Niemisto: /* Baseline behavior */

This page discusses three common operations that handle some subgraph of the whole Simantics database.
They all have very similar issues:
* Export/import
** What is exported?
** How are references from the exported part to the unexported part handled?
* Copy/paste
** What is copied?
** How are references from the copied part to the uncopied part handled?
* Removal
** What is removed?
** How are references between the removed and the unremoved resources handled?
Moreover in many cases copy/paste should behave similarly to export/import
and immediate removal of an imported object should usually restore the database to the
state before import.

== Baseline behavior ==

First, it should be made clear, that in some cases there are more than one reasonable behaviour
for the operations. For example, consider an applications where graphical and semantic objects are
separated and the same semantic object can be represented by multiple graphical objects.
When the user removes a graphical object, it is possible to remove also the corresponding semantic object,
but it is also sensible to remove only the graphical object. Sometimes the desired behaviour can
be asked from the user.

This means that the "correct" behaviour of each operation cannot be based purely on the shape of the
data but it should be customizable in each case separately. However, the customization cannot be
based solely on the type of the resource selected when the operation is requested. For example, a removal
of a library has a very simple behavior: its children should also be removed. However the children
of the library may each require different removal customization.

In order to collect all requirements for the customizable export/import, copy/paste and removal operations,
we first define the ''baseline behaviour'' for the operations. The idea is that we can then collect all current cases where
the operations should behave differently from the baseline and this helps for choosing the right customization
hooks.

Every operation targets some resource C. In some cases there can be more than one target,
but definitions should be easily generalizable for that case.

A resource is ''external to C'' if
there is a PartOf-path leading from the resource to the root library such
that the path does not include C. In other words, the set of resources external
to C are the resources that are reachable by ConsistsOf from root library without
going through C.

A resource is ''in the context of C'' if it reachable from C by statements
without going through any external resources.

[[Image:Extent.png]]

Now, we can define baseline behaviors:
* Export writes all resources in the context of C as internal resources to the transferable graph, together with all their statements excluding PartOf-statements from C. Resources external to C are referred by URI. C is marked the root of TG.
* Import creates all internal resources in TG file as new resources and adds all the statements in TG. The references to external resources are resolved by URI and if the resource does not exist a dummy resource is created. The root of the TG is attached by ConsistsOf to the target of the import operation.
* Copy/paste behaves just like export/import.
* Removal unlinks all the resource in the context of C from the external resources.

== Exceptions to baseline behavior ==

=== Export/import ===

=== Copy/paste ===

=== Removal ===

* Component types (and other types)
** If the type has instances the operation must be cancelled or all the instances must be removed
* Connection points, properties (and other relations)
** If the relation is used somewhere the operation must be cancelled or the corresponding statement must be removed.
* Components
** If component is created by mapping from a diagram the corresponding diagram elements should also be removed

Subgraph operations

2013-11-12T13:48:01Z

Hannu Niemisto: /* Baseline behavior */

This page discusses about three common operations that handle some subgraph of the whole Simantics database.
They all have very similar issues:
* Export/import
** What is exported?
** How the references from the exported part to the unexported part are handled?
* Copy/paste
** What is copied?
** How the references from the copied part to the uncopied part are handled?
* Removal
** What is removed?
** How the references between the removed and the unremoved resources are handled?
Moreover in many cases copy/paste should behave similarly to export/import
and immediate removal of an imported object should usually restore the database to the
state before import.

== Baseline behavior ==

First, it should be made clear, that in some cases there are more than one reasonable behaviour
for the operations. For example, consider an applications where graphical and semantic objects are
separated and the same semantic object can be represented by multiple graphical objects.
When the user removes a graphical object, it is possible to remove also the corresponding semantic object,
but it is also sensible to remove only the graphical object. Sometimes the desired behaviour can
be asked from the user.

This means that the "correct" behaviour of each operation cannot be based purely on the shape of the
data but it should be customizable in each case separately. However, the customization cannot be
based solely on the type of the resource selected when the operation is requested. For example, a removal
of a library has a very simple behavior: its children should also be removed. However the children
of the library may each require different removal customization.

In order to collect all requirements for the customizable export/import, copy/paste and removal operations,
we first define the ''baseline behaviour'' for the operations. The idea is that we can then collect all current cases where
the operations should behave differently from the baseline and this helps for choosing the right customization
hooks.

Every operation targets some resource C. In some cases there can be more than one target,
but definitions should be easily generalizable for that case.

A resource is ''external to C'' if
there is a PartOf-path leading from the resource to the root library such
that the path does not include C. In other words, the set of resources external
to C are the resources that are reachable by ConsistsOf from root library without
going through C.

A resource is ''in the context of C'' if it reachable from C by statements
without going through any external resources.

[[Image:Extent.png]]

Now, we can define baseline behaviors:
* Export writes all resources in the context of C as internal resources to the transferable graph, together with all their statements excluding a PartOf-statements from C. Resources external to C are referred by URI. C is marked the root of TG.
* Import creates all internal resources in TG file as new resources and adds all the statements in TG. The references to external resources are resolved by URI and if the resource does not exist a dummy resource is created. The root of the TG is attached by ConsistsOf to the target of the import operation.
* Copy/paste behaves just like export/import.
* Removal removes all the resource in the context of C.

== Exceptions to baseline behavior ==

=== Export/import ===

=== Copy/paste ===

=== Removal ===

* Component types (and other types)
** If the type has instances the operation must be cancelled or all the instances must be removed
* Connection points, properties (and other relations)
** If the relation is used somewhere the operation must be cancelled or the corresponding statement must be removed.
* Components
** If component is created by mapping from a diagram the corresponding diagram elements should also be removed

Subgraph operations

2013-11-12T13:46:58Z

Hannu Niemisto: /* Baseline behavior */

This page discusses about three common operations that handle some subgraph of the whole Simantics database.
They all have very similar issues:
* Export/import
** What is exported?
** How the references from the exported part to the unexported part are handled?
* Copy/paste
** What is copied?
** How the references from the copied part to the uncopied part are handled?
* Removal
** What is removed?
** How the references between the removed and the unremoved resources are handled?
Moreover in many cases copy/paste should behave similarly to export/import
and immediate removal of an imported object should usually restore the database to the
state before import.

== Baseline behavior ==

First, it should be made clear, that in some cases there are more than one reasonable behaviour
for the operations. For example, consider an applications where graphical and semantic objects are
separated and the same semantic object can be represented by multiple graphical objects.
When the user removes a graphical object, it is possible to remove also the corresponding semantic object,
but it is also sensible to remove only the graphical object. Sometimes the desired behaviour can
be asked from the user.

This means that the "correct" behaviour of each operation cannot be based purely on the shape of the
data but it should be customizable in each case separately. However, the customization cannot be
based solely on the type of the resource selected when the operation is requested. For example, a removal
of a library has a very simple behavior: its children should also be removed. However the children
of the library may each require different removal customization.

In order to collect all requirements for the customizable export/import, copy/paste and removal operations,
we first define the ''baseline behaviour'' for the operations. The idea is that we can then collect all current cases where
the operations should behave differently from the baseline and this helps for choosing the right customization
hooks.

Every operation targets some resource C. In some cases there can be more than one target,
but definitions should be easily generalizable for that case.

A resource is ''external to C'' if
there is a PartOf-path leading from the resource to the root library such
that the path does not include C. In other words, the set of resources external
to C are the resources that are reachable by ConsistsOf from root library without
going through C.

A resource is ''in the context of C'' if it reachable from C by statements
without going through any external resources.

[[Image:Extent.png]]

Now, we can define baseline behaviors:
* Export writes all resources in the context of C as internal resources to the transferable graph, together with all their statements excluding a PartOf-statements from C. Resources external to C are referred by URI. C is marked the root of TG.
* Import creates all internal resources in TG file as new resources and add all the statements in TG. The references to external resources are resolved by URI and if the resource does not exist a dummy resource is created. The root of the TG is attached by ConsistsOf to the target of the import operation.
* Copy/paste behaves just like export/import.
* Removal removes all the resource in the context of C.

== Exceptions to baseline behavior ==

=== Export/import ===

=== Copy/paste ===

=== Removal ===

* Component types (and other types)
** If the type has instances the operation must be cancelled or all the instances must be removed
* Connection points, properties (and other relations)
** If the relation is used somewhere the operation must be cancelled or the corresponding statement must be removed.
* Components
** If component is created by mapping from a diagram the corresponding diagram elements should also be removed

Subgraph operations

2013-11-12T13:45:25Z

Hannu Niemisto: /* Baseline behavior */

This page discusses about three common operations that handle some subgraph of the whole Simantics database.
They all have very similar issues:
* Export/import
** What is exported?
** How the references from the exported part to the unexported part are handled?
* Copy/paste
** What is copied?
** How the references from the copied part to the uncopied part are handled?
* Removal
** What is removed?
** How the references between the removed and the unremoved resources are handled?
Moreover in many cases copy/paste should behave similarly to export/import
and immediate removal of an imported object should usually restore the database to the
state before import.

== Baseline behavior ==

First, it should be made clear, that in some cases there are more than one reasonable behaviour
for the operations. For example, consider an applications where graphical and semantic objects are
separated and the same semantic object can be represented by multiple graphical objects.
When the user removes a graphical object, it is possible to remove also the corresponding semantic object,
but it is also sensible to remove only the graphical object. Sometimes the desired behaviour can
be asked from the user.

This means that the "correct" behaviour of each operation cannot be based purely on the shape of the
data but it should be customizable in each case separately. However, the customization cannot be
based solely on the type of the resource selected when the operation is requested. For example, a removal
of a library has a very simple behavior: its children should also be removed. However the children
of the library may each require different removal customization.

In order to collect all requirements for the customizable export/import, copy/paste and removal operations,
we first define the ''baseline behaviour'' for operations. Idea is that we then collect all current cases where
the operations should behave differently from the baseline and this helps for choosing the right customization
hooks.

Each of the operations targets some resource C. In some cases there can be more than one target,
but definitions should be easily generalizable for that case.

A resource is ''external to C'' if
there is a PartOf-path leading from the resource to the root library such
that the path does not include C. In other words, the set of resources external
to C are the resources that are reachable by ConsistsOf from root library without
going through C.

A resource is ''in the context of C'' if it reachable from C by statements
without going through any external resources.

[[Image:Extent.png]]

Now, we can define baseline behaviors:
* Export writes all resources in the context of C as internal resources to the transferable graph, together with all their statements excluding a PartOf-statements from C. Resources external to C are referred by URI. C is marked the root of TG.
* Import creates all internal resources in TG file as new resources and add all the statements in TG. The references to external resources are resolved by URI and if the resource does not exist a dummy resource is created. The root of the TG is attached by ConsistsOf to the target of the import operation.
* Copy/paste behaves just like export/import.
* Removal removes all the resource in the context of C.

== Exceptions to baseline behavior ==

=== Export/import ===

=== Copy/paste ===

=== Removal ===

* Component types (and other types)
** If the type has instances the operation must be cancelled or all the instances must be removed
* Connection points, properties (and other relations)
** If the relation is used somewhere the operation must be cancelled or the corresponding statement must be removed.
* Components
** If component is created by mapping from a diagram the corresponding diagram elements should also be removed

Subgraph operations

2013-11-12T13:43:45Z

Hannu Niemisto:

This page discusses about three common operations that handle some subgraph of the whole Simantics database.
They all have very similar issues:
* Export/import
** What is exported?
** How the references from the exported part to the unexported part are handled?
* Copy/paste
** What is copied?
** How the references from the copied part to the uncopied part are handled?
* Removal
** What is removed?
** How the references between the removed and the unremoved resources are handled?
Moreover in many cases copy/paste should behave similarly to export/import
and immediate removal of an imported object should usually restore the database to the
state before import.

== Baseline behavior ==

First, it should be made clear, that in some cases there are more than one reasonable behaviour
for the operations. For example, consider an applications where graphical and semantic objects are
separated and the same semantic object can be represented by multiple graphical objects.
When the user removes a graphical object, it is possible to remove also the corresponding semantic object,
but it is also sensible to remove only the graphical object. Sometimes the desired behaviour can
be asked from the user.

This means that the "correct" behaviour of each operation cannot be based purely on the shape of the
data but it should be customizable in each case separately. However, the customization cannot be
based solely on the type of the resource selected when the operation is requested. For example, a removal
of a library has a very simple behavior: its children should also be removed. However the children
of the library may each require different removal customization.

In order to collect all requirements for the customizable export/import, copy/paste and removal operations,
we first define ''baseline behaviour'' for operations. Idea is that we then collect all current cases where
the operations should behave differently from the baseline and this helps for choosing the right customization
hooks.

Each of the operations targets some resource C. In some cases there can be more than one target,
but definitions should be easily generalizable for that case.

A resource is ''external to C'' if
there is a PartOf-path leading from the resource to the root library such
that the path does not include C. In other words, the set of resources external
to C are the resources that are reachable by ConsistsOf from root library without
going through C.

A resource is ''in the context of C'' if it reachable from C by statements
without going through any external resources.

[[Image:Extent.png]]

Now, we can define baseline behaviors:
* Export writes all resources in the context of C as internal resources to the transferable graph, together with all their statements excluding a PartOf-statements from C. Resources external to C are referred by URI. C is marked the root of TG.
* Import creates all internal resources in TG file as new resources and add all the statements in TG. The references to external resources are resolved by URI and if the resource does not exist a dummy resource is created. The root of the TG is attached by ConsistsOf to the target of the import operation.
* Copy/paste behaves just like export/import.
* Removal removes all the resource in the context of C.

== Exceptions to baseline behavior ==

=== Export/import ===

=== Copy/paste ===

=== Removal ===

* Component types (and other types)
** If the type has instances the operation must be cancelled or all the instances must be removed
* Connection points, properties (and other relations)
** If the relation is used somewhere the operation must be cancelled or the corresponding statement must be removed.
* Components
** If component is created by mapping from a diagram the corresponding diagram elements should also be removed

File:Extent.png

2013-11-12T13:43:09Z

Hannu Niemisto:

Subgraph operations

2013-11-12T13:42:40Z

Hannu Niemisto: Created page with "Topic: Subgraph_operations This page discusses about three common operations that handle some subgraph of the whole Simantics database. They all have very similar issues: * Expo..."

Topic: Subgraph_operations

This page discusses about three common operations that handle some subgraph of the whole Simantics database.
They all have very similar issues:
* Export/import
** What is exported?
** How the references from the exported part to the unexported part are handled?
* Copy/paste
** What is copied?
** How the references from the copied part to the uncopied part are handled?
* Removal
** What is removed?
** How the references between the removed and the unremoved resources are handled?
Moreover in many cases copy/paste should behave similarly to export/import
and immediate removal of an imported object should usually restore the database to the
state before import.

== Baseline behavior ==

First, it should be made clear, that in some cases there are more than one reasonable behaviour
for the operations. For example, consider an applications where graphical and semantic objects are
separated and the same semantic object can be represented by multiple graphical objects.
When the user removes a graphical object, it is possible to remove also the corresponding semantic object,
but it is also sensible to remove only the graphical object. Sometimes the desired behaviour can
be asked from the user.

This means that the "correct" behaviour of each operation cannot be based purely on the shape of the
data but it should be customizable in each case separately. However, the customization cannot be
based solely on the type of the resource selected when the operation is requested. For example, a removal
of a library has a very simple behavior: its children should also be removed. However the children
of the library may each require different removal customization.

In order to collect all requirements for the customizable export/import, copy/paste and removal operations,
we first define ''baseline behaviour'' for operations. Idea is that we then collect all current cases where
the operations should behave differently from the baseline and this helps for choosing the right customization
hooks.

Each of the operations targets some resource C. In some cases there can be more than one target,
but definitions should be easily generalizable for that case.

A resource is ''external to C'' if
there is a PartOf-path leading from the resource to the root library such
that the path does not include C. In other words, the set of resources external
to C are the resources that are reachable by ConsistsOf from root library without
going through C.

A resource is ''in the context of C'' if it reachable from C by statements
without going through any external resources.

[[Image:Extent.png]]

Now, we can define baseline behaviors:
* Export writes all resources in the context of C as internal resources to the transferable graph, together with all their statements excluding a PartOf-statements from C. Resources external to C are referred by URI. C is marked the root of TG.
* Import creates all internal resources in TG file as new resources and add all the statements in TG. The references to external resources are resolved by URI and if the resource does not exist a dummy resource is created. The root of the TG is attached by ConsistsOf to the target of the import operation.
* Copy/paste behaves just like export/import.
* Removal removes all the resource in the context of C.

== Exceptions to baseline behavior ==

=== Export/import ===

=== Copy/paste ===

=== Removal ===

* Component types (and other types)
** If the type has instances the operation must be cancelled or all the instances must be removed
* Connection points, properties (and other relations)
** If the relation is used somewhere the operation must be cancelled or the corresponding statement must be removed.
* Components
** If component is created by mapping from a diagram the corresponding diagram elements should also be removed

Commands

2013-10-22T12:28:36Z

Hannu Niemisto: /* Recording */

= Requirements =

The core idea of Simantics command system is to have all user interface
operations go through SCL function calls. This ensures they are all
available in SCL for writing scripts and regression tests.
The direct user need driving the development is recording of the
commands for later replaying.

Because recording and scripting are the main applications,
the commands are defined to be operations that make modifications
to the persistent state of the application without any user
interaction. Thus for example a function that opens a wizard
is not a command, but the modification to a model that is
executed when the wizard is finished is a command. There are
probably cases where the difference is not so clear
(is changing of profiles a command?).

For command recording, each command must have a context where
it is executed. Particularly when making modifications to
two models in the same workspace, the commands should be recorded
to two separate command logs. This may cause problems, when
the command affects the existence of the model (creating new model,
importing model, removing model), the command affects multiple
models (moving stuff between models) or the command causes a persistent
effect outside of models (changing preferences, importing ontologies).

The command system should specify how commands are executed from
Java code, how they are referred in modelled user inteface actions
(such as modelled context view or selection view) and how new commands
are contributed.

The main challenge of the system is the difference between two modes
of execution. When writing a script, the state of the application at
execution time is unknown and all commands should be available. Each
command is executed atomically and they either succeed or fail with
an error message that is either written to the console, if the execution
is initiated there, or otherwise shown in a dialog.
On the other hand, when executing commands from UI, the user expects that UI hides
or disables the actions that are not allowed in the current operating
context or will surely fail.

The second challenge is the serialization of the commands for recording
so that commands would be valid with maximal probability when replaying
in an application context with possible minor differences.

= Design =

== Introduction ==

The most important thing of the command is the modification it
makes to the model. However, for use in UI, some additional information
is needed such as which roles are allowed to execute the command and
a function to check is the command execution possible.

The following approaches were consided for bundling this information together:
# Commands are SCL functions returning a value of type <code>Command a</code> that can be checked and executed
# Commands are concepts in ontologies that define different properties containing SCL functions for checking and execution
# Commands are specified as separate SCL functions that are tied together by naming conventions

The first approach has some drawbacks. First, it is not possible to know the allowed roles
without first giving all parameters to the function. Second, without adding some new syntactic
sugar, the <code>Command</code> -type complicates writing of scripts. Either every command
has to be wrapped like
<pre>
exec (newDiagram ...)
</pre>
or written in monadic style. A benefit of <code>Command</code> -type might be the ability to create
new commands by combinators.

The second approach makes possible to define arbitrary properties for the commands, so it
is extensible. Its drawback is the need for a read transaction for obtaining information about
commands. It makes it also heavier to define new commands. A command contribution might
involve additions in three places: Java code implementing the operation, SCL code importing
the Java code and ontology referring to SCL.

The third approach has the flexibility of the ontology approach, but is lighterweight.
Role and checking may have some defaults (allowed for any role, no checking), which
makes it possible to consider any SCL function as a command. For these benefits we
choose this approach.

== Defining commands ==

Commands are defined as ordinary SCL-functions. The name of the command (and thus the defining function)
should be in imperative mood (createDiagram, not newDiagram). The command is executed in a write transaction,
thus WriteGraph and Proc effects are allowed in the signature.

Additional SCL-functions <code>command_check</code> and <code>command_role</code> specify the related
checking function and role. Although we follow camel case naming convention in SCL, in this case
the suffixes are separated by <code>_</code>. Role function should return the role name (string).
The parameters of the role function are some prefix of the parameters of the command, typically
role function does not have parameters at all.

The signature of the checking function is related to the signature of the command in a more complicated
way in order to make checking of partial parameters possible. Basically some suffix of the signature
is replaced by <code>Boolean</code> and any right subtype may be enclosed in <code>Maybe</code>.
The checking function may have ReadGraph effect and if it has the command system ensures that it is
executed in the read transaction.
So, if the signature of the command is
<pre>
A -> B -> <WriteGraph> C
</pre>
then, the signature of the checking function can be for example:
<pre>
Boolean
A -> <ReadGraph> Boolean
A -> B -> <ReadGraph> Boolean
A -> <ReadGraph> Maybe (B -> Boolean)
A -> <ReadGraph> Maybe (B -> <ReadGraph> Boolean)
</pre>
If the final Boolean value is false or any of the intermediate Maybe value is
Nothing, then the command may not be executed.

Here is an example:
<pre>
setPropertyAsString :: Variable -> String -> <WriteGraph> ()
setPropertyAsString_check :: Variable -> <ReadGraph> Maybe (String -> <ReadGraph> Boolean)
setPropertyAsString_role :: String
</pre>
The command takes a variable and a value in a string form as a parameter.
The checking function first checks if the variable is writable. The second
part of the checking tests that the string value is valid.

== Java API ==

Java API for executing commands is meant to be used during execution of
UI operations. A command is obtained with the following method:
<pre>
public class Commands {
public static Command get(ReadGraph graph, String name);
}
</pre>
The parameter 'name' is the full name of the SCL-function (such as <code>Simantics/Diagram/setTransformation</code>).
The method never fails but returns a dummy Command-object if the command is not found.

Command interface contains a method for checking if the command is applicable with the given parameters. It may be given less than all parameters of the command. The command can be executed synchronously or asynchronously.
All methods need a context resource (usually a model) that must be first obtained.
<pre>
public interface Command {
boolean check(RequestProcessor processor, Resource model, Object ... parameters) throws DatabaseException;
Object execute(RequestProcessor processor, Resource model, Object ... parameters) throws DatabaseException;
void asyncExecute(RequestProcessor processor, Resource model, Object[] parameters,
Procedure<Object> procedure);
}
</pre>

The interface handles roles automatically. When the current user has no
privileges to execute the command, check method always fails.

== Recording ==

When a command is executed, the textual form of the command is written
to the metadata of the change set. The command metadata is associated with a
certain context (usually a model). Although the metadata is enough to reconstruct
the whole command history, a snapshot of the history is periodically written to
a separate file to save information in the case the whole database corrupts.

The writing of command metadata happens in the commit-method of the Command interface
after the change is successfully made the the database and no exception is
thrown. Each command is written in a form readily suitable for execution in a script
with two exceptions: Command begins with the full name of the command function so that
no imports are not expected to be available. It is assumed that a resource
named <code>context</code> is defined.

Command parameters are serialized with a function:
<pre>
gshow :: GShow a => Resource -> a -> <Proc,ReadGraph> String
</pre>
The first parameter is the current context resource. All references are made relative
to that resource so that commands can later executed in some other context. The method
<code>gshow</code> works much like <code>show</code> in Prelude, but
is also able to write expressions for finding resources in ontologies and under
the context resource. It is defined in the module <code>Simantics/GShow</code>.

Commands

2013-10-22T12:28:09Z

Hannu Niemisto: /* Recording */

= Requirements =

The core idea of Simantics command system is to have all user interface
operations go through SCL function calls. This ensures they are all
available in SCL for writing scripts and regression tests.
The direct user need driving the development is recording of the
commands for later replaying.

Because recording and scripting are the main applications,
the commands are defined to be operations that make modifications
to the persistent state of the application without any user
interaction. Thus for example a function that opens a wizard
is not a command, but the modification to a model that is
executed when the wizard is finished is a command. There are
probably cases where the difference is not so clear
(is changing of profiles a command?).

For command recording, each command must have a context where
it is executed. Particularly when making modifications to
two models in the same workspace, the commands should be recorded
to two separate command logs. This may cause problems, when
the command affects the existence of the model (creating new model,
importing model, removing model), the command affects multiple
models (moving stuff between models) or the command causes a persistent
effect outside of models (changing preferences, importing ontologies).

The command system should specify how commands are executed from
Java code, how they are referred in modelled user inteface actions
(such as modelled context view or selection view) and how new commands
are contributed.

The main challenge of the system is the difference between two modes
of execution. When writing a script, the state of the application at
execution time is unknown and all commands should be available. Each
command is executed atomically and they either succeed or fail with
an error message that is either written to the console, if the execution
is initiated there, or otherwise shown in a dialog.
On the other hand, when executing commands from UI, the user expects that UI hides
or disables the actions that are not allowed in the current operating
context or will surely fail.

The second challenge is the serialization of the commands for recording
so that commands would be valid with maximal probability when replaying
in an application context with possible minor differences.

= Design =

== Introduction ==

The most important thing of the command is the modification it
makes to the model. However, for use in UI, some additional information
is needed such as which roles are allowed to execute the command and
a function to check is the command execution possible.

The following approaches were consided for bundling this information together:
# Commands are SCL functions returning a value of type <code>Command a</code> that can be checked and executed
# Commands are concepts in ontologies that define different properties containing SCL functions for checking and execution
# Commands are specified as separate SCL functions that are tied together by naming conventions

The first approach has some drawbacks. First, it is not possible to know the allowed roles
without first giving all parameters to the function. Second, without adding some new syntactic
sugar, the <code>Command</code> -type complicates writing of scripts. Either every command
has to be wrapped like
<pre>
exec (newDiagram ...)
</pre>
or written in monadic style. A benefit of <code>Command</code> -type might be the ability to create
new commands by combinators.

The second approach makes possible to define arbitrary properties for the commands, so it
is extensible. Its drawback is the need for a read transaction for obtaining information about
commands. It makes it also heavier to define new commands. A command contribution might
involve additions in three places: Java code implementing the operation, SCL code importing
the Java code and ontology referring to SCL.

The third approach has the flexibility of the ontology approach, but is lighterweight.
Role and checking may have some defaults (allowed for any role, no checking), which
makes it possible to consider any SCL function as a command. For these benefits we
choose this approach.

== Defining commands ==

Commands are defined as ordinary SCL-functions. The name of the command (and thus the defining function)
should be in imperative mood (createDiagram, not newDiagram). The command is executed in a write transaction,
thus WriteGraph and Proc effects are allowed in the signature.

Additional SCL-functions <code>command_check</code> and <code>command_role</code> specify the related
checking function and role. Although we follow camel case naming convention in SCL, in this case
the suffixes are separated by <code>_</code>. Role function should return the role name (string).
The parameters of the role function are some prefix of the parameters of the command, typically
role function does not have parameters at all.

The signature of the checking function is related to the signature of the command in a more complicated
way in order to make checking of partial parameters possible. Basically some suffix of the signature
is replaced by <code>Boolean</code> and any right subtype may be enclosed in <code>Maybe</code>.
The checking function may have ReadGraph effect and if it has the command system ensures that it is
executed in the read transaction.
So, if the signature of the command is
<pre>
A -> B -> <WriteGraph> C
</pre>
then, the signature of the checking function can be for example:
<pre>
Boolean
A -> <ReadGraph> Boolean
A -> B -> <ReadGraph> Boolean
A -> <ReadGraph> Maybe (B -> Boolean)
A -> <ReadGraph> Maybe (B -> <ReadGraph> Boolean)
</pre>
If the final Boolean value is false or any of the intermediate Maybe value is
Nothing, then the command may not be executed.

Here is an example:
<pre>
setPropertyAsString :: Variable -> String -> <WriteGraph> ()
setPropertyAsString_check :: Variable -> <ReadGraph> Maybe (String -> <ReadGraph> Boolean)
setPropertyAsString_role :: String
</pre>
The command takes a variable and a value in a string form as a parameter.
The checking function first checks if the variable is writable. The second
part of the checking tests that the string value is valid.

== Java API ==

Java API for executing commands is meant to be used during execution of
UI operations. A command is obtained with the following method:
<pre>
public class Commands {
public static Command get(ReadGraph graph, String name);
}
</pre>
The parameter 'name' is the full name of the SCL-function (such as <code>Simantics/Diagram/setTransformation</code>).
The method never fails but returns a dummy Command-object if the command is not found.

Command interface contains a method for checking if the command is applicable with the given parameters. It may be given less than all parameters of the command. The command can be executed synchronously or asynchronously.
All methods need a context resource (usually a model) that must be first obtained.
<pre>
public interface Command {
boolean check(RequestProcessor processor, Resource model, Object ... parameters) throws DatabaseException;
Object execute(RequestProcessor processor, Resource model, Object ... parameters) throws DatabaseException;
void asyncExecute(RequestProcessor processor, Resource model, Object[] parameters,
Procedure<Object> procedure);
}
</pre>

The interface handles roles automatically. When the current user has no
privileges to execute the command, check method always fails.

== Recording ==

When a command is executed, the textual form of the command is written
to the metadata of the change set. The command metadata is associated with a
certain context (usually a model). Although the metadata is enough to reconstruct
the whole command history, a snapshot of the history is periodically written to
a separate file to save information in the case the whole database corrupts.

The writing of command metadata happens in the commit-method of the Command interface
after the change is successfully made the the database and no exception is
thrown. Each command is written in a form readily suitable for execution in a script
with two exceptions: Command begins with the full name of the command function so that
no imports are not expected to be available. It is assumed that a resource
named <code>context</code> is defined.

Command parameters are serialized with a function:
<pre>
gshow :: GShow a => Resource -> a -> <Proc,ReadGraph> String
</pre>
The first parameter is the current context resource. All references are made relative
to that resource that commands can later executed in some other context. The method
<code>gshow</code> works much like <code>show</code> in Prelude, but
is also able to write expressions for finding resources in ontologies and under
the context resource. It is defined in the module <code>Simantics/GShow</code>.

Commands

2013-10-22T12:26:31Z

Hannu Niemisto: /* Java API */

= Requirements =

The core idea of Simantics command system is to have all user interface
operations go through SCL function calls. This ensures they are all
available in SCL for writing scripts and regression tests.
The direct user need driving the development is recording of the
commands for later replaying.

Because recording and scripting are the main applications,
the commands are defined to be operations that make modifications
to the persistent state of the application without any user
interaction. Thus for example a function that opens a wizard
is not a command, but the modification to a model that is
executed when the wizard is finished is a command. There are
probably cases where the difference is not so clear
(is changing of profiles a command?).

For command recording, each command must have a context where
it is executed. Particularly when making modifications to
two models in the same workspace, the commands should be recorded
to two separate command logs. This may cause problems, when
the command affects the existence of the model (creating new model,
importing model, removing model), the command affects multiple
models (moving stuff between models) or the command causes a persistent
effect outside of models (changing preferences, importing ontologies).

The command system should specify how commands are executed from
Java code, how they are referred in modelled user inteface actions
(such as modelled context view or selection view) and how new commands
are contributed.

The main challenge of the system is the difference between two modes
of execution. When writing a script, the state of the application at
execution time is unknown and all commands should be available. Each
command is executed atomically and they either succeed or fail with
an error message that is either written to the console, if the execution
is initiated there, or otherwise shown in a dialog.
On the other hand, when executing commands from UI, the user expects that UI hides
or disables the actions that are not allowed in the current operating
context or will surely fail.

The second challenge is the serialization of the commands for recording
so that commands would be valid with maximal probability when replaying
in an application context with possible minor differences.

= Design =

== Introduction ==

The most important thing of the command is the modification it
makes to the model. However, for use in UI, some additional information
is needed such as which roles are allowed to execute the command and
a function to check is the command execution possible.

The following approaches were consided for bundling this information together:
# Commands are SCL functions returning a value of type <code>Command a</code> that can be checked and executed
# Commands are concepts in ontologies that define different properties containing SCL functions for checking and execution
# Commands are specified as separate SCL functions that are tied together by naming conventions

The first approach has some drawbacks. First, it is not possible to know the allowed roles
without first giving all parameters to the function. Second, without adding some new syntactic
sugar, the <code>Command</code> -type complicates writing of scripts. Either every command
has to be wrapped like
<pre>
exec (newDiagram ...)
</pre>
or written in monadic style. A benefit of <code>Command</code> -type might be the ability to create
new commands by combinators.

The second approach makes possible to define arbitrary properties for the commands, so it
is extensible. Its drawback is the need for a read transaction for obtaining information about
commands. It makes it also heavier to define new commands. A command contribution might
involve additions in three places: Java code implementing the operation, SCL code importing
the Java code and ontology referring to SCL.

The third approach has the flexibility of the ontology approach, but is lighterweight.
Role and checking may have some defaults (allowed for any role, no checking), which
makes it possible to consider any SCL function as a command. For these benefits we
choose this approach.

== Defining commands ==

Commands are defined as ordinary SCL-functions. The name of the command (and thus the defining function)
should be in imperative mood (createDiagram, not newDiagram). The command is executed in a write transaction,
thus WriteGraph and Proc effects are allowed in the signature.

Additional SCL-functions <code>command_check</code> and <code>command_role</code> specify the related
checking function and role. Although we follow camel case naming convention in SCL, in this case
the suffixes are separated by <code>_</code>. Role function should return the role name (string).
The parameters of the role function are some prefix of the parameters of the command, typically
role function does not have parameters at all.

The signature of the checking function is related to the signature of the command in a more complicated
way in order to make checking of partial parameters possible. Basically some suffix of the signature
is replaced by <code>Boolean</code> and any right subtype may be enclosed in <code>Maybe</code>.
The checking function may have ReadGraph effect and if it has the command system ensures that it is
executed in the read transaction.
So, if the signature of the command is
<pre>
A -> B -> <WriteGraph> C
</pre>
then, the signature of the checking function can be for example:
<pre>
Boolean
A -> <ReadGraph> Boolean
A -> B -> <ReadGraph> Boolean
A -> <ReadGraph> Maybe (B -> Boolean)
A -> <ReadGraph> Maybe (B -> <ReadGraph> Boolean)
</pre>
If the final Boolean value is false or any of the intermediate Maybe value is
Nothing, then the command may not be executed.

Here is an example:
<pre>
setPropertyAsString :: Variable -> String -> <WriteGraph> ()
setPropertyAsString_check :: Variable -> <ReadGraph> Maybe (String -> <ReadGraph> Boolean)
setPropertyAsString_role :: String
</pre>
The command takes a variable and a value in a string form as a parameter.
The checking function first checks if the variable is writable. The second
part of the checking tests that the string value is valid.

== Java API ==

Java API for executing commands is meant to be used during execution of
UI operations. A command is obtained with the following method:
<pre>
public class Commands {
public static Command get(ReadGraph graph, String name);
}
</pre>
The parameter 'name' is the full name of the SCL-function (such as <code>Simantics/Diagram/setTransformation</code>).
The method never fails but returns a dummy Command-object if the command is not found.

Command interface contains a method for checking if the command is applicable with the given parameters. It may be given less than all parameters of the command. The command can be executed synchronously or asynchronously.
All methods need a context resource (usually a model) that must be first obtained.
<pre>
public interface Command {
boolean check(RequestProcessor processor, Resource model, Object ... parameters) throws DatabaseException;
Object execute(RequestProcessor processor, Resource model, Object ... parameters) throws DatabaseException;
void asyncExecute(RequestProcessor processor, Resource model, Object[] parameters,
Procedure<Object> procedure);
}
</pre>

The interface handles roles automatically. When the current user has no
privileges to execute the command, check method always fails.

== Recording ==

When a command is executed, the textual form of the command is written
to the metadata of the change set. The command metadata is associated with a
certain context (usually a model). Although the metadata is enough to reconstruct
the whole command history, a snapshot of the history is periodically written to
a separate file to save information in the case the whole database corrupts.

The writing of command metadata happens in the commit-method of the Command interface
after the change is successfully made the the database and no exception is
thrown. Each command is written in a form readily suitable for execution in a script
with two exceptions: Command begins with the full name of the command function so that
no imports are not expected to be available. It is assumed that a resource
named <code>context</code> is defined.

Command parameters are serialized with a type class:
<pre>
class RepresentableParameter a where
representParameter :: Resource -> a -> <ReadGraph> String
</pre>
The first parameter is the current context resource. All references are made relative
to that resource that commands can later executed in some other context. The method
<code>representParameter</code> works much like <code>show</code> in Prelude, but
is also able to write expressions for finding resources in ontologies and under
the context resource.

Commands

2013-09-26T10:49:10Z

Hannu Niemisto: /* Recording */

= Requirements =

The core idea of Simantics command system is to have all user interface
operations go through SCL function calls. This ensures they are all
available in SCL for writing scripts and regression tests.
The direct user need driving the development is recording of the
commands for later replaying.

Because recording and scripting are the main applications,
the commands are defined to be operations that make modifications
to the persistent state of the application without any user
interaction. Thus for example a function that opens a wizard
is not a command, but the modification to a model that is
executed when the wizard is finished is a command. There are
probably cases where the difference is not so clear
(is changing of profiles a command?).

For command recording, each command must have a context where
it is executed. Particularly when making modifications to
two models in the same workspace, the commands should be recorded
to two separate command logs. This may cause problems, when
the command affects the existence of the model (creating new model,
importing model, removing model), the command affects multiple
models (moving stuff between models) or the command causes a persistent
effect outside of models (changing preferences, importing ontologies).

The command system should specify how commands are executed from
Java code, how they are referred in modelled user inteface actions
(such as modelled context view or selection view) and how new commands
are contributed.

The main challenge of the system is the difference between two modes
of execution. When writing a script, the state of the application at
execution time is unknown and all commands should be available. Each
command is executed atomically and they either succeed or fail with
an error message that is either written to the console, if the execution
is initiated there, or otherwise shown in a dialog.
On the other hand, when executing commands from UI, the user expects that UI hides
or disables the actions that are not allowed in the current operating
context or will surely fail.

The second challenge is the serialization of the commands for recording
so that commands would be valid with maximal probability when replaying
in possible little different application context.

= Design =

== Introduction ==

The most important thing of the command is the modification it
makes to the model. However, for use in UI, some additional information
is needed such as which roles are allowed to execute the command and
a function to check is the command execution possible.

The following approaches were consided for bundling this information together:
# Commands are SCL functions returning a value of type <code>Command a</code> that can be checked and executed
# Commands are concepts in ontologies that define different properties containing SCL functions for checking and execution
# Commands are specified as separate SCL functions that are tied together by naming conventions

The first approach has some drawbacks. First, it is not possible to know the allowed roles
without first giving all parameters to the function. Second, without adding some new syntactic
sugar, the <code>Command</code> -type complicated writing of scripts. Either every command
has to be wrapped like
<pre>
exec (newDiagram ...)
</pre>
or written in monadic style. A benefit of <code>Command</code> -type might be the ability to create
new commands by combinators.

The second approach makes possible to define arbitrary properties for the commands, so it
is extensible. Its drawback is need for a read transaction for obtaining information about
commands. It makes it also heavier to define new commands. A command contribution might
involve additions in three places: Java code implementing the operation, SCL code importing
the Java code and ontology referring to SCL.

The third approach has the flexibility of the ontology approach, but is lighterweight.
Role and checking may have some defaults (allowed for any role, no checking), which
makes it possible to consider any SCL function as a command. For these benefits we
choose this approach.

== Defining commands ==

Commands are defined as ordinary SCL-functions. The name of the command (and thus the defining function)
should be in imperative mood (createDiagram, not newDiagram). The command is executed in a write transaction,
thus WriteGraph and Proc effects are allowed in the signature.

Additional SCL-functions <code>command_check</code> and <code>command_role</code> specify the related
checking function and role. Although we follow camel case naming convention in SCL, in this case
the suffixes are separated by <code>_</code>. Role function should return the role name (string).
The parameters of the role function are some prefix of the parameters of the command, typically
role function does not have parameters at all.

The signature of the checking function is related to the signature of the command in more complicated
way in order to make checking of partial parameters possible. Basically some suffix of the signature
is replaced by <code>Boolean</code> and any right subtype may be enclosed in <code>Maybe</code>.
The checking function may have ReadGraph event and if it has the command system ensures that it is
executed in the read transaction.
So, if the signature of the command is
<pre>
A -> B -> <WriteGraph> C
</pre>
then, the signature of the checking function can be for example:
<pre>
Boolean
A -> <ReadGraph> Boolean
A -> B -> <ReadGraph> Boolean
A -> <ReadGraph> Maybe (B -> Boolean)
A -> <ReadGraph> Maybe (B -> <ReadGraph> Boolean)
</pre>
If the final Boolean value is false or any of the intermediate Maybe value is
Nothing, then the command may not be executed.

Here is an example:
<pre>
setPropertyAsString :: Variable -> String -> <WriteGraph> ()
setPropertyAsString_check :: Variable -> <ReadGraph> Maybe (String -> <ReadGraph> Boolean)
setPropertyAsString_role :: String
</pre>
The command takes a variable and a value in a string form as a parameter.
The checking function first check, if the variable is writable. The second
part of the checking tests that the string value is valid.

== Java API ==

Java API for executing commands is meant to be used from during execution of
UI operations. Commands are executed in contexts (usually models) that
must be first obtained. New command can be created with <code>newCommand</code>
method in the context. Parameter <code>name</code> is a full path of the
SCL-function implementing the command.
<pre>
public class CommandContext {
public static CommandContext getContext(Resource resource);
public static CommandContext getContext(RequestProcessor graph, Resource resource);
public Command newCommand(String name);
}
</pre>

Command interface has methods for adding and removing parameters, checking
that command is eligible for exectution and committing the command.
Even if checking accepts the parameter, the command may fail in commit.
On failure, an exception is thrown (currently no special exception is specified).
<pre>
public interface Command {
Command addParameters(Object ... parameters);
Command removeParameters(int count);
boolean check();
boolean check(RequestProcessor graph);
void commit();
void commit(RequestProcessor graph);
}
</pre>
(TODO async methods?)

The interface handles roles automatically. When the current user has no
privileges to execute the command, check method always fails.

Example (fictional):
<pre>
public Runnable renameContribution(Resource target) {
final Command command = CommandContext.getContext(target)
.newCommand("Simantics/FictionalModule/rename", target);
if(!command.check())
return null; // Cannot rename the target
else
return new Runnable() {
public void run() {
new RenameWidget(command).start();
}
};
}

public class RenameWidget {
Command command;
public RenameWidget(Command command) { this.command = command; }

public boolean validate(String name) {
boolean result = command.addParameters(name).check();
command.removeParameters(1);
return result;
}

public void finish() {
try {
command.addParameters(getName()).commit();
} catch(Exception e) {
show error to user
}
}
}
</pre>

== Recording ==

When a command is executed, the textual form of the command is written
to the metadata of the change set. The command metadata is associated with a
certain context (usually a model). Although the metadata is enough to reconstruct
the whole command history, a snapshot of the history is periodically written to
a separate file to save information in the case the whole database corrupts.

The writing of command metadata happens in the commit-method of the Command interface
after the change is successfully made the the database and no exception is
thrown. Each command is written in a form readily suitable for execution in a script
with two exceptions: Command begins with the full name of the command function so that
no imports are not expected to be available. It is assumed that a resource
named <code>context</code> is defined.

Command parameters are serialized with a type class:
<pre>
class RepresentableParameter a where
representParameter :: Resource -> a -> <ReadGraph> String
</pre>
The first parameter is the current context resource. All references are made relative
to that resource that commands can later executed in some other context. The method
<code>representParameter</code> works much like <code>show</code> in Prelude, but
is also able to write expressions for finding resources in ontologies and under
the context resource.

Commands

2013-09-26T10:48:12Z

Hannu Niemisto: /* Java API */

= Requirements =

The core idea of Simantics command system is to have all user interface
operations go through SCL function calls. This ensures they are all
available in SCL for writing scripts and regression tests.
The direct user need driving the development is recording of the
commands for later replaying.

Because recording and scripting are the main applications,
the commands are defined to be operations that make modifications
to the persistent state of the application without any user
interaction. Thus for example a function that opens a wizard
is not a command, but the modification to a model that is
executed when the wizard is finished is a command. There are
probably cases where the difference is not so clear
(is changing of profiles a command?).

For command recording, each command must have a context where
it is executed. Particularly when making modifications to
two models in the same workspace, the commands should be recorded
to two separate command logs. This may cause problems, when
the command affects the existence of the model (creating new model,
importing model, removing model), the command affects multiple
models (moving stuff between models) or the command causes a persistent
effect outside of models (changing preferences, importing ontologies).

The command system should specify how commands are executed from
Java code, how they are referred in modelled user inteface actions
(such as modelled context view or selection view) and how new commands
are contributed.

The main challenge of the system is the difference between two modes
of execution. When writing a script, the state of the application at
execution time is unknown and all commands should be available. Each
command is executed atomically and they either succeed or fail with
an error message that is either written to the console, if the execution
is initiated there, or otherwise shown in a dialog.
On the other hand, when executing commands from UI, the user expects that UI hides
or disables the actions that are not allowed in the current operating
context or will surely fail.

The second challenge is the serialization of the commands for recording
so that commands would be valid with maximal probability when replaying
in possible little different application context.

= Design =

== Introduction ==

The most important thing of the command is the modification it
makes to the model. However, for use in UI, some additional information
is needed such as which roles are allowed to execute the command and
a function to check is the command execution possible.

The following approaches were consided for bundling this information together:
# Commands are SCL functions returning a value of type <code>Command a</code> that can be checked and executed
# Commands are concepts in ontologies that define different properties containing SCL functions for checking and execution
# Commands are specified as separate SCL functions that are tied together by naming conventions

The first approach has some drawbacks. First, it is not possible to know the allowed roles
without first giving all parameters to the function. Second, without adding some new syntactic
sugar, the <code>Command</code> -type complicated writing of scripts. Either every command
has to be wrapped like
<pre>
exec (newDiagram ...)
</pre>
or written in monadic style. A benefit of <code>Command</code> -type might be the ability to create
new commands by combinators.

The second approach makes possible to define arbitrary properties for the commands, so it
is extensible. Its drawback is need for a read transaction for obtaining information about
commands. It makes it also heavier to define new commands. A command contribution might
involve additions in three places: Java code implementing the operation, SCL code importing
the Java code and ontology referring to SCL.

The third approach has the flexibility of the ontology approach, but is lighterweight.
Role and checking may have some defaults (allowed for any role, no checking), which
makes it possible to consider any SCL function as a command. For these benefits we
choose this approach.

== Defining commands ==

Commands are defined as ordinary SCL-functions. The name of the command (and thus the defining function)
should be in imperative mood (createDiagram, not newDiagram). The command is executed in a write transaction,
thus WriteGraph and Proc effects are allowed in the signature.

Additional SCL-functions <code>command_check</code> and <code>command_role</code> specify the related
checking function and role. Although we follow camel case naming convention in SCL, in this case
the suffixes are separated by <code>_</code>. Role function should return the role name (string).
The parameters of the role function are some prefix of the parameters of the command, typically
role function does not have parameters at all.

The signature of the checking function is related to the signature of the command in more complicated
way in order to make checking of partial parameters possible. Basically some suffix of the signature
is replaced by <code>Boolean</code> and any right subtype may be enclosed in <code>Maybe</code>.
The checking function may have ReadGraph event and if it has the command system ensures that it is
executed in the read transaction.
So, if the signature of the command is
<pre>
A -> B -> <WriteGraph> C
</pre>
then, the signature of the checking function can be for example:
<pre>
Boolean
A -> <ReadGraph> Boolean
A -> B -> <ReadGraph> Boolean
A -> <ReadGraph> Maybe (B -> Boolean)
A -> <ReadGraph> Maybe (B -> <ReadGraph> Boolean)
</pre>
If the final Boolean value is false or any of the intermediate Maybe value is
Nothing, then the command may not be executed.

Here is an example:
<pre>
setPropertyAsString :: Variable -> String -> <WriteGraph> ()
setPropertyAsString_check :: Variable -> <ReadGraph> Maybe (String -> <ReadGraph> Boolean)
setPropertyAsString_role :: String
</pre>
The command takes a variable and a value in a string form as a parameter.
The checking function first check, if the variable is writable. The second
part of the checking tests that the string value is valid.

== Java API ==

Java API for executing commands is meant to be used from during execution of
UI operations. Commands are executed in contexts (usually models) that
must be first obtained. New command can be created with <code>newCommand</code>
method in the context. Parameter <code>name</code> is a full path of the
SCL-function implementing the command.
<pre>
public class CommandContext {
public static CommandContext getContext(Resource resource);
public static CommandContext getContext(RequestProcessor graph, Resource resource);
public Command newCommand(String name);
}
</pre>

Command interface has methods for adding and removing parameters, checking
that command is eligible for exectution and committing the command.
Even if checking accepts the parameter, the command may fail in commit.
On failure, an exception is thrown (currently no special exception is specified).
<pre>
public interface Command {
Command addParameters(Object ... parameters);
Command removeParameters(int count);
boolean check();
boolean check(RequestProcessor graph);
void commit();
void commit(RequestProcessor graph);
}
</pre>
(TODO async methods?)

The interface handles roles automatically. When the current user has no
privileges to execute the command, check method always fails.

Example (fictional):
<pre>
public Runnable renameContribution(Resource target) {
final Command command = CommandContext.getContext(target)
.newCommand("Simantics/FictionalModule/rename", target);
if(!command.check())
return null; // Cannot rename the target
else
return new Runnable() {
public void run() {
new RenameWidget(command).start();
}
};
}

public class RenameWidget {
Command command;
public RenameWidget(Command command) { this.command = command; }

public boolean validate(String name) {
boolean result = command.addParameters(name).check();
command.removeParameters(1);
return result;
}

public void finish() {
try {
command.addParameters(getName()).commit();
} catch(Exception e) {
show error to user
}
}
}
</pre>

== Recording ==

When a command is executed, the textual form of the command is written
to the metadata of the change set. The command metadata is associated with a
certain context (usually a model). Although the metadata is enough to reconstruct
the whole command history, a snapshot of the history is periodically written to
a separate file to save information in the case the whole database corrupts.

The writing of command metadata happens in the commit-method of the Command interface
after the change is successfully made the the database and no exception is
thrown. Each command is written in a form readily suitable for execution in a script
with two exceptions: Command begins with the full name of the command function so that
no imports are not expected to be available. It is assumed that a resource
named <code>context</code> is defined.

Command parameters are serialized with a type class:
<pre>
class RepresentableParameter a where
representParameter :: Resource -> a -> <ReadGraph> String
</pre>
The first parameter is the current context resource. All references are made relative
to that resource that commands can later executed in some other context. The method
<code>representParameter</code> works much like <code>show</code> in Prelude, but
is also able to write expressions for finding resources in ontologies and under
the context resource.

Commands

2013-09-26T10:47:50Z

Hannu Niemisto: /* Java API */

= Requirements =

The core idea of Simantics command system is to have all user interface
operations go through SCL function calls. This ensures they are all
available in SCL for writing scripts and regression tests.
The direct user need driving the development is recording of the
commands for later replaying.

Because recording and scripting are the main applications,
the commands are defined to be operations that make modifications
to the persistent state of the application without any user
interaction. Thus for example a function that opens a wizard
is not a command, but the modification to a model that is
executed when the wizard is finished is a command. There are
probably cases where the difference is not so clear
(is changing of profiles a command?).

For command recording, each command must have a context where
it is executed. Particularly when making modifications to
two models in the same workspace, the commands should be recorded
to two separate command logs. This may cause problems, when
the command affects the existence of the model (creating new model,
importing model, removing model), the command affects multiple
models (moving stuff between models) or the command causes a persistent
effect outside of models (changing preferences, importing ontologies).

The command system should specify how commands are executed from
Java code, how they are referred in modelled user inteface actions
(such as modelled context view or selection view) and how new commands
are contributed.

The main challenge of the system is the difference between two modes
of execution. When writing a script, the state of the application at
execution time is unknown and all commands should be available. Each
command is executed atomically and they either succeed or fail with
an error message that is either written to the console, if the execution
is initiated there, or otherwise shown in a dialog.
On the other hand, when executing commands from UI, the user expects that UI hides
or disables the actions that are not allowed in the current operating
context or will surely fail.

The second challenge is the serialization of the commands for recording
so that commands would be valid with maximal probability when replaying
in possible little different application context.

= Design =

== Introduction ==

The most important thing of the command is the modification it
makes to the model. However, for use in UI, some additional information
is needed such as which roles are allowed to execute the command and
a function to check is the command execution possible.

The following approaches were consided for bundling this information together:
# Commands are SCL functions returning a value of type <code>Command a</code> that can be checked and executed
# Commands are concepts in ontologies that define different properties containing SCL functions for checking and execution
# Commands are specified as separate SCL functions that are tied together by naming conventions

The first approach has some drawbacks. First, it is not possible to know the allowed roles
without first giving all parameters to the function. Second, without adding some new syntactic
sugar, the <code>Command</code> -type complicated writing of scripts. Either every command
has to be wrapped like
<pre>
exec (newDiagram ...)
</pre>
or written in monadic style. A benefit of <code>Command</code> -type might be the ability to create
new commands by combinators.

The second approach makes possible to define arbitrary properties for the commands, so it
is extensible. Its drawback is need for a read transaction for obtaining information about
commands. It makes it also heavier to define new commands. A command contribution might
involve additions in three places: Java code implementing the operation, SCL code importing
the Java code and ontology referring to SCL.

The third approach has the flexibility of the ontology approach, but is lighterweight.
Role and checking may have some defaults (allowed for any role, no checking), which
makes it possible to consider any SCL function as a command. For these benefits we
choose this approach.

== Defining commands ==

Commands are defined as ordinary SCL-functions. The name of the command (and thus the defining function)
should be in imperative mood (createDiagram, not newDiagram). The command is executed in a write transaction,
thus WriteGraph and Proc effects are allowed in the signature.

Additional SCL-functions <code>command_check</code> and <code>command_role</code> specify the related
checking function and role. Although we follow camel case naming convention in SCL, in this case
the suffixes are separated by <code>_</code>. Role function should return the role name (string).
The parameters of the role function are some prefix of the parameters of the command, typically
role function does not have parameters at all.

The signature of the checking function is related to the signature of the command in more complicated
way in order to make checking of partial parameters possible. Basically some suffix of the signature
is replaced by <code>Boolean</code> and any right subtype may be enclosed in <code>Maybe</code>.
The checking function may have ReadGraph event and if it has the command system ensures that it is
executed in the read transaction.
So, if the signature of the command is
<pre>
A -> B -> <WriteGraph> C
</pre>
then, the signature of the checking function can be for example:
<pre>
Boolean
A -> <ReadGraph> Boolean
A -> B -> <ReadGraph> Boolean
A -> <ReadGraph> Maybe (B -> Boolean)
A -> <ReadGraph> Maybe (B -> <ReadGraph> Boolean)
</pre>
If the final Boolean value is false or any of the intermediate Maybe value is
Nothing, then the command may not be executed.

Here is an example:
<pre>
setPropertyAsString :: Variable -> String -> <WriteGraph> ()
setPropertyAsString_check :: Variable -> <ReadGraph> Maybe (String -> <ReadGraph> Boolean)
setPropertyAsString_role :: String
</pre>
The command takes a variable and a value in a string form as a parameter.
The checking function first check, if the variable is writable. The second
part of the checking tests that the string value is valid.

== Java API ==

Java API for executing commands is meant to be used from during execution of
UI operations. Commands are executed in contexts (usually models) that
must be first obtained. New command can be created with <code>newCommand</code>
method in the context. Parameter <code>name</code> is a full path of the
SCL-function implementing the command.
<pre>
public class CommandContext {
public static CommandContext getContext(Resource resource);
public static CommandContext getContext(RequestProcessor graph, Resource resource);
public Command newCommand(String name);
}
</pre>

Command interface has methods for adding and removing parameters, checking
that command is eligible for exectution and committing the command.
Even if checking accepts the parameter, the command may fail in commit.
On failure, an exception is thrown (currently no special exception is specified).
<pre>
public interface Command {
Command addParameters(Object ... parameters);
Command removeParameters(int count);
boolean check();
boolean check(RequestProcessor graph);
void commit();
void commit(RequestProcessor graph);
}
</pre>
(TODO async methods?)

The interface handles roles automatically. When the current user has no
privileges to execute the command, check method always fails.

Example (fictional):
<pre>
public Runnable renameContribution(Resource target) {
final Command command = CommandContext.getContext(target)
.newCommand("Simantics/FictionalModule/rename", target);
if(!command.check())
return null; // Cannot rename the target
else
return new Runnable() {
public void run() {
new RenameWidget(command).start();
}
};
}

public class RenameWidget {
Command command;
public RenameWidget(Command command) { this.command = command; }

public boolean validate(String name) {
boolean result = command.addParameters(name).check();
command.removeParameters(1);
return result;
}

public void finish() {
try {
command.addParameters(getName()).commit();
} catch(Exception e) {
show error to user
}
}
}
</pre>

== Recording ==

When a command is executed, the textual form of the command is written
to the metadata of the change set. The command metadata is associated with a
certain context (usually a model). Although the metadata is enough to reconstruct
the whole command history, a snapshot of the history is periodically written to
a separate file to save information in the case the whole database corrupts.

The writing of command metadata happens in the commit-method of the Command interface
after the change is successfully made the the database and no exception is
thrown. Each command is written in a form readily suitable for execution in a script
with two exceptions: Command begins with the full name of the command function so that
no imports are not expected to be available. It is assumed that a resource
named <code>context</code> is defined.

Command parameters are serialized with a type class:
<pre>
class RepresentableParameter a where
representParameter :: Resource -> a -> <ReadGraph> String
</pre>
The first parameter is the current context resource. All references are made relative
to that resource that commands can later executed in some other context. The method
<code>representParameter</code> works much like <code>show</code> in Prelude, but
is also able to write expressions for finding resources in ontologies and under
the context resource.