Ch. 2 Installation and Setup

Tooling for System Descriptor language is provided in the form of a custom Eclipse installation. Once installed, Eclipse can be used to create and edit SD models. Two items must be downloaded to continue:

1. the base Eclipse installation for either Linux or Windows
2. the System Descriptor language update site

Note that the latest versions can be located on the GitHub releases page.

Setting up Eclipse

1. Unzip the Eclipse zip to any location you wish.
2. Start Eclipse:
   • Windows: double click eclipse.exe.
   • Linux: cd to the directory in which you unzipped eclipse and enter ./eclipse.
   • If Eclipse fails to start, see Eclipse Troubleshooting below.
3. Choose any directory when Eclipse prompts for the location of its workspace.
   • optional: On the bottom right of the Welcome tab unselect Always show Welcome at start up and close the Tab.
4. Install the SD update site once eclipse has started.
   1. Select Help → Install New Software.
   2. Click Add… to create a new software site.
   3. Name the site System Descriptor Language Support (note this name can be anything).
   4. Select Archive…
   5. Navigate to the directory where the update site zip is located.
   6. Select the com.ngc.seaside.systemdescriptor.updatesite-.zip (note that denotes the version you downloaded).
   7. Select Open.
   8. Select OK.
   9. Unselect Group items by category at the bottom
   10. Unselect Contact all update sites during install to find required software.
   11. Check JellyFish SystemDescriptor DSL.
   12. Select Next and follow the prompts.
5. Restart Eclipse when prompted.

Eclipse Troubleshooting

If Eclipse fails to the start, it is usually because Eclipse is using an older version of Java. It may be neccessary to configure the Java executable Eclipse uses when starting. In most cases, you can configure your system so a Java 8 JDK is installed and that JDK is listed first on the $PATH envionrment variable. If you cannot configure the $PATH for you system, you can edit the eclipse.ini file. Add the lines below:

eclipse.ini

-vm
<PATH_TO_YOUR_JAVA_EXE>

These lines must occur direclty after the openFile line. Include a full path to the java.exe executable. Below is a complete example.

eclipse.ini

-startup
plugins/org.eclipse.equinox.launcher_1.5.0.v20180512-1130.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.700.v20180518-1200
-product
org.eclipse.epp.package.dsl.product
-showsplash
org.eclipse.epp.package.common
--launcher.defaultAction
openFile
--launcher.defaultAction
openFile
-vm
C:/java/jdk1.8.xxx/bin/javaw.exe
--launcher.appendVmargs
-vmargs
-Dosgi.requiredJavaVersion=1.8
-Dosgi.instance.area.default=@user.home/eclipse-workspace
-XX:+UseG1GC
-XX:+UseStringDeduplication
--add-modules=ALL-SYSTEM
-Dosgi.requiredJavaVersion=1.8
-Dosgi.dataAreaRequiresExplicitInit=true
-Xms256m
-Xmx2024m
--add-modules=ALL-SYSTEM

Cleaning the Project

Sometimes, Eclipse will show errors in files even if the files are syntacticallyd valid. This is expecially true when importing other types of data types. When this happens,

1. Select Project -> Clean.
2. Select Clean all projects.
3. Clock Clean.
4. After cleaning, right click a project in the Package Explorer and select Refresh.

This should remove the errors. If all else fails, restart Eclipse.

Creating an Initial Project

Once Eclipse has a restarted, an initial project can be created to make sure the installation was successful. Make sure the Package Explorer window is visible and follow the steps below. If for some reason Package Explorer isn’t shown (or you accidentally close it) just select Window -> Show View -> Package Explorer in the menu.

1. Select File -> New -> Other in the menu. You may also right click in the Package Explorer and select New -> Other.
2. Expand JellyFish
3. Select System Descriptor Project
4. Select Next.
5. Enter a project name of HelloWorld.
   1. Leave Use default location checked
6. Select Finish.

A new project should appear in the project explorer.

1. Expand the HelloWorld project and expand src/main/sd
2. Expand the item labeled com/ngc/mysdproject
3. Double click MyModel.sd to open the example model

Its contents should look something similar to this:

MyModel.sd

/*
 * ...
 * [license header]
 * ...
 */
package com.ngc.mysdproject
 
model MyModel {
  metadata {
    "name" : "MyModel",
    "description" : "MyModel description",
    "stereotypes" : ["model", "example"]
  }
}

This indicates that the tooling has been successfully installed.

Customization

Some defaults values that are generated when creating a new System Descriptor project can be modified by creating a jellyfish.properties file. This can be done as follows:

1. Navigate to your home directory. This is typically C:\users\<user> for Windows and /home/<user> for Linux.
2. If it doesn’t already exist, create a folder called .jellyfish. If you get an error in Windows, type .jellyfish. instead.
3. Create the file jellyfish.properties in the folder .jellyfish.
4. Open the file jellyfish.properties using your favorite text editor.
5. You can add properties to this file using the following syntax: <property>=<value>. Each property should be on its own line.

The following defaults can be changed using the jellyfish.properties file.

Special Characters

If a value has a colon `:` or backslash `\` character in it, it must be preceded by a backslash `\` character. For
example, the header file `C:\users\me\license.txt` should be
`jellyfish.generated.header.file=C\:\\users\\me\\license.txt` in the properties file. Conveniently, you can use forward
slashes `/` for Windows file paths instead: `jellyfish.generated.header.file=C\:/users/me/license.txt`