Development Environment Setup Guide

Install Prerequisites

JDK

• JDK 6.0 (= Java Standard Edition 1.6) is required. The latest update should always work. Get it here.
  • IMPORTANT: See this notice if using JDK 6 update 21. We suggest using update 20 at the moment if possible.

Eclipse IDE

• Get latest eclipse SDK Helios (3.6 series): http://www.eclipse.org/downloads/, choose Eclipse for RCP and RAP Developers
  • DO NOT USE the 64-bit builds on Windows, 32-bit works better for the time being

• Extract the installation package to your preferred location, e.g. d:\. The package already contains a directory called eclipse.
• Start Eclipse with a new empty workspace by launching the executable within the package. The program will query you for the workspace location.

• 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.

Eclipse plug-in for Subversion

Simantics uses Subversion (SVN) as a version control system (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: Eclipse Subversive. Update Site is a part of Helios Update Site. Look at Help > Install New Software... > select Helios - http://download.eclipse.org/releases/helios > Collaboration Tools
  • From the Subversive SVN Connectors installation category, select:
    • Subversive SVN Connectors
    • SVNKit 1.3.x. Implementation
  • 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.simulationsite.net working, you may need to use direct connection proxy settings after installing the SVN plug-ins.

Simantics Tooling

Select menu Help/Install New Software and write http://www.simantics.org/update 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.

Setup IDE

• Import Simantics Java formatting rules into your Eclipse
  • In Eclipse: Window/Preferences and Java/Code Style/Formatter
• From the same preferences dialog also make sure that JDK 6.0 (or JRE 1.6) compliance is enabled:

  

• 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

The only thing you absolutely need to have for developing at this point is the target platform. Download and install it as instructed in the following and you're ready to go.

See Target Platform for more information.

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.

TODO: explain use of Eclipse to checkout

1. Checkout the target platform for your version into a directory of your choice. See Target Platform for available versions. You can use Eclipse's SVN Repository Exploring perspective for this task. You can also use other tools, such as TortoiseSVN or the SVN command line client.
   • 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.
2. 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.

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

OPTIONAL STEPS

Developing 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.simulationsite.net/svn/simantics/
    • Authentication =
      • Committers: your username and password

For more information on our repositories, see Repositories.

Checkout Simantics sources

• Checkout the proper project sets into your workspace. Eclipse will check it out as ProjectSets:
  • Simantics 1.2 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 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.

Basic IDE Usage

Running Products from the IDE

• Create a Product Configuration (.product) for your own product.
  • You can use sysdyn.product as a starting point for your own product configuration.
  • Be sure to only include the components that you want to have in your product, nothing more.

• 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 nearly all cases of 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

1. take new plug-ins into use (add them to features included by the product)
2. remove plug-ins from use
3. plug-ins are moved from the workspace to the target platform or vice versa
4. the target platform is updated

Testing your own contributions with Simantics

Scenario: Testing a set of plug-ins

Prerequisites:

1. Some of the added plug-ins may contain ontologies.
2. You've created your own set of plug-ins based on the Simantics SDK.
3. You've defined features that include your plug-ins.
4. You've followed the instructions at #Building

Steps to follow:

1. If you have not already created a product definition for yourself:
   1. Optionally create a new plug-in project with the name product in it
   2. Add a new Product Configuration to an existing or a new plug-in with basic settings
   3. Open the new .product file in the product editor
   4. 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.
2. Configure the product to your liking, add the features you need to it and launch it.
3. Launch your product

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.

Deploying Executable Product

• Open a .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 SPM, you need to select Generate metadata repository.