Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

STEM Eclipse Setup

STEM TOP BAR.gif

STEM Home

Welcome

This is a tutorial on how to get the STEM source code downloaded, compiled, and running in your Eclipse Development Environment. This tutorial is mainly for committers and advanced users that want to work with the STEM source directly.

Getting Started

STEM is a Java application built on top of the Eclipse Rich Client Platform (RCP). To build and run STEM, a developer must install a supported Java Development Kit (JDK) and the Eclipse SDK. While it may be possible to compile STEM in another IDE, we strongly recommend you use the Eclipse SDK.

Prerequisites

To download and compile the STEM source, developers should first install the following components:

  1. A workstation running an Eclipse-supported operating system:
    • Windows (XP, Vista, 7)
    • Linux (GTK)
    • Mac OS X (10.5 or later)
  2. A supported Java Standard Edition (J2SE) For STEM V4.0.3 or above the minimum requirement is (J2SE) 11.0.8 JVM
    Oracle Java SE-11.0.8
  3. Eclipse 4.5.4 (Mars) or above
    • Note: If you're using a 64-bit JVM, be sure to download the 64-bit version of Eclipse
  4. Please observe, STEM is currently running Java-11. You need to make sure your development environment is self consistently set to the same Java version (three places)
    • Eclipse>Preferences>Java>Compiler
    • Eclipse>Preferences>Java>Installed JRE's
    • In run configuration for the STEM product, on the Execution Environment set on the Main tab. See below .

Creating a STEM Development Environment

The process for building STEM consists of several steps. The steps should be followed in this order:

Set up your Eclipse SDK

Before you attempt to checkout and compile the STEM source code, some additional features must be installed into your Eclipse SDK.

Install Required Eclipse Features

This installation guide requires that Eclipse EGit be installed. In addition to EGit, much of STEM is built using modeled code generated by the Eclipse Modeling Framework (EMF). To extend these models, or edit existing models, EMF must be installed into your environment.

  1. Launch your Eclipse SDK
  2. Open the Eclipse Software Installer by opening the Help menu and choosing Install New Software
  3. When the Install dialog opens, select the Juno repository from the drop-down menu. Wait while the list of additional features loads.
    • Install EGit
      1. Expand the Collaboration category by clicking the arrow next to it
      2. Select Eclipse EGit
    • Install the Eclipse Modeling Framework (EMF)
      1. Expand the Modeling category by clicking the arrow next to it
      2. Select EMF - Eclipse Modeling Framework SDK
  4. Click Next
  5. Verify that EGit and EMF are in the list of features to install. Click Next
  6. Read the license agreement and, if you accept, choose I accept the terms of the license agreement . Click Finish
  7. Wait while the features install into your Eclipse SDK
    This step may take up to 10 minutes to complete
  8. When the installer finishes, it'll prompt you to restart. Click Restart Now


Checkout and Build the STEM Source Code

Once your Eclipse environment is set up, you're ready to checkout the STEM source code. The STEM Project provides an Eclipse Team Project Set (PSF) that'll help you quickly get the STEM Source code checked out.

Source Tree Location (HTML)

You may browse the git source tree here at https://git.eclipse.org/c/stem/org.eclipse.stem.git/tree/

Most of the project code is found under org.eclipse.stem: https://git.eclipse.org/c/stem/org.eclipse.stem.git/tree/org.eclipse.stem

Checkout the STEM Source Code from a Project Set File

Important Note: Before beginning these steps, committers should read these important details about checking out from Git.

  1. Launch your Eclipse SDK
  2. When prompted to Select a workspace, choose a new path that does not contain an existing workspace. This creates a new workspace.
    Important Note: Eclipse and STEM work best when the workspace path contains no whitespace characters (spaces, tabs, etc). Example: C:\workspace\
    Switch to the GIT Repository Exploring perspective (this seems to be necessary to workaround EGit bugs)
  3. Open the File menu and choose Import
  4. When the Import dialog opens, expand the Team category by clicking the arrow next to it
  5. Choose Team Project Set and click Next
  6. On the Import a Team Project Set page, choose URL and enter the URL for the correct Project Set file
    • For new users (non-committers):
      http://www.eclipse.org/stem/psf.php
    • For Eclipse committers (SSH):
      http://www.eclipse.org/stem/psf.php?r=ssh&u=YOUR_COMMITTER_USERNAME
      Note: Replace YOUR_COMMITTER_USERNAME with your committer username, not e-mail address, in the above link
    • For Eclipse committers (HTTPS):
      http://www.eclipse.org/stem/psf.php?r=https
      NOTE: for HTTPS the password is different than for the rest of eclipse. You can generate a password here: https://git.eclipse.org/r/#/settings/http-password
  7. Click Finish
    STEM Setup Import PSF.png
  8. Wait while Eclipse checks out and imports the STEM source code into your environment
    Depending on your connection speed, this step may take over an hour to complete. Have some coffee and come back.
  9. Trouble shooting for SSH. If you're getting authentication exceptions checking out the STEM source code, make sure you've configured SSH in the Eclipse preference settings correctly. Instructions for doing this can be found here [SSH Configuration]. Do not upload your public key to GitHub, instead you need to upload it to Gerrit here: [Gerrit SSH Upload].

Apply the Target Platform

Once the checkout completes, there will likely be hundreds (or thousands) of build errors. STEM uses what's called an Eclipse Target Platform to manage the rest of the dependencies that must be installed to completely build and run STEM. The following steps will help you in applying the target platform.

Important Note About Target Platforms: The target platform represents which version of the Eclipse Platform to compile and run STEM in.
  1. In the Eclipse SDK, open the Preferences dialog. Select the Window menu and choose Preferences
    On Mac OS X, it's under the Eclipse menu
  2. In the Preferences dialog, expand the Plug-in Development category
  3. Select the Target Platform option under Plug-in Development category
  4. Select the STEM4 Target Platform by clicking checkbox
    STEMtarget4.png
  5. Wait while Eclipse loads the Target Platform.
    Depending on your connection speed, this step may take up to 30 minutes to complete.
  6. Make sure STEM is built completely. Under the Problems tab, there should be no Errors (Warnings are OK)
    STEM Setup Problems.png
  7. If you are still seeing errors, try cleaning the workspace
    1. Select the Project menu and choose Clean...
    2. In the Clean dialog, choose Clean All Projects
    3. Click OK
    4. Wait for Eclipse to clean and re-build STEM
  8. If you see errors it could be due to a missing plugin in your environment. Right click on the error and select "Quick Fix" and install any missing plugins

Configure the Package Presentation

After everything is built, in the package explored you are very likely to see two different views of the same package(s). To fix this, at the top of the Package Explorer click the down Arrow and select: >Package Presentation> Hierarchical

STEM PackagePresentation.png

That will fix the view.

Build the STEM Denominator Data

Once STEM is built, it's time to build the STEM data sets. This process transforms the data from a raw, human-readable format to STEM modeled data files that are readable by scenarios, models, decorators, etc.

  1. In the Eclipse SDK, in the Package Explorer , scrolls down to the org.eclipse.stem.internal.data project
  2. Expand the org.eclipse.stem.internal.data project by clicking the arrow next to it
  3. RIGHT click on the update.xml file
  4. In the context menu, highlight Run As and click on Ant Build
  5. Wait while the data builder runs.
    This will take up to 10 minutes
  6. When the builder finishes, the console should say BUILD SUCCESSFUL
    STEM Setup UpdateConsoleFinished.png

Advanced ANT configuration

Please Observe: There is an issue with the latest version of Eclipse 4 versions on some platforms that causes the Ant build to fail. 
The default path for eclipse.pdebuild.home in Ant properties has a final dot (.) at the end of the path value. 
For example, you may see the value C:\Users\account_name\Desktop\Stem\eclipse-rcp-oxygen-1a-win32-x86_64\eclipse\plugins \org.eclipse.pde.build_3.9.300.v20170515-0912\. This issue has been reported particularly on mac. Removing this final dot(.), or adding (/)  after resolves the issue. The bug has been reported to Eclipse. 

If you have trouble running ANT follow the detailed instructions below (please observe the "...")
This is a one time configuration which, when completed successfully, should allow you to run Ant in the future 
based on the simple instructions described above.
  1. In the Eclipse SDK, in the Package Explorer , scrolls down to the org.eclipse.stem.internal.data project
  2. Expand the org.eclipse.stem.internal.data project by clicking the arrow next to it
  3. RIGHT click on the update.xml file
  4. In the context menu, highlight Run As and click on Ant Build ...
    STEM Setup Run Update.png
  5. This will launch an ANT dialog to Edit configuration and launch
    STEMConfigRunAnt.png
  6. click on the Properties Tab
  7. uncheck the box labeled 'Use global properties as specified in the Ant runtime preferences'
  8. close the dialog
  9. reopen the dialog as before. The eclipse.pdebuild.home variable will now be editable
    1. RIGHT click on the update.xml file
    2. In the context menu, highlight Run As and click on Ant Build ...
  10. again, click on the Properties Tab
  11. click on the eclipse.pdebuild.home variable. Expand the dialog window to make it bigger
    STEMEditPDEhome.png
  12. click 'Edit Property'
  13. move the cursor to the far right of the Value field and remove the trailing dot (.) at the end of the path value.
  14. click OK
  15. click Apply
  16. click Run
  17. Ant should run successfully. When the builder finishes, the console should say BUILD SUCCESSFUL
    STEM Setup UpdateConsoleFinished.png

Launch STEM

Configure stem.product

Once the STEM source is compiled and data sets built, it's time to launch the STEM application.

  1. In the Eclipse SDK, in the Package Explorer , scroll down to the org.eclipse.stem.ui project
  2. Expand the org.eclipse.stem.ui project by clicking the arrow next to it
  3. RIGHT click on the stem2.product file
  4. In the context menu, highlight Run As and click on Eclipse Application
    STEM Setup RunProduct.png
  5. The STEM Application will load with errors (expected) but this creates the STEM run configuration which you can now customize
  6. exit the STEM application
  7. Got to the top Eclipse menu bar and select >> Run >> Run Configurations...
    STEM4RunConfig.png
  8. In the Run Configurations Dialog
    1. Select stem4.product in the Eclipse Application list (on the left)
    2. Select the Plug-ins tab
    3. Please make sure that the Launch with combo box select all workspace and enabled target plug-in
    4. click Run
  9. STEM should now run without errors. Once the run configuration is configured correctly you can just click run (the configuration is a one time operation until/unless you add a new plugin).

Set the Runtime Arguments

From the launch Run Configuration dialog, click on the Arguments tab. Set the runtime arguments as shown below.

STEM4 Run Config.png]]

Known Issues and workarounds

There is a bug with MacOS Mojave running on a laptop with touchbar.

Please see: https://bugs.eclipse.org/bugs/show_bug.cgi?id=538377

The workaround is to add -nosplash to the "Program arguments" in the launch configuration's "Arguments" tab.


For Eclipse Version: 2020-09 (4.17.0), you should add the VM arguement -Dorg.eclipse.update.reconcile=false as shown below.

-Xms400M -Xmx1024M -XstartOnFirstThread -Dorg.eclipse.swt.internal.carbon.smallFonts -Dorg.eclipse.update.reconcile=false

Advanced Topics

The following are advanced topics that existing developers may be interested in. If you're new to STEM development, you can skip this section.

Generating the stand alone STEM Application

Weekly builds are running on the Eclipse CI infrastructure and distributed through the website. The build process uses Maven. To learn how to create a build please visit the page Building the STEM RCP Application

Getting the Earth Science Data

The STEM project contains several gigabytes of "earth science" data derived from NASA and NOAA satellite imagery. These data include global elevations, air temperatures, rainfall, vegetation coverage, etc. By default, this data is not included when you checkout STEM. These steps will help you checkout and build the earth science data for use in your STEM development environment.

WARNING The STEM Earth Science Data is several gigabytes in size. The checkout may take several hours to finish and will use a lot of disk space

  1. Complete all the steps above and make sure STEM is built in your Eclipse SDK and can be launched
  2. In your Eclipse SDK, go to the File menu and select Import
  3. In the Import wizard, expand Team , select Team Project Set , and click Next
  4. On the Import a Team Project Set page, choose URL and enter the URL for the correct Project Set
    For new users (non-committers): http://www.eclipse.org/stem/psf.php?ws=STEM-Data-EarthScience
    For Eclipse committers (using https): http://www.eclipse.org/stem/psf.php?ws=STEM-Data-EarthScience&r=https
    or For Eclipse committers (using ssh): http://www.eclipse.org/stem/psf.php?ws=STEM-Data-EarthScience&r=ssh
  5. Click Finish
  6. Wait while Eclipse checks out the Earth Science Data
    This check out may take several hours.
  7. In the Eclipse SDK, in Package Explorer , scrolls down to the org.eclipse.stem.internal.data.geography.earthscience project
  8. Expand the org.eclipse.stem.internal.data.geography.earthscience project
  9. RIGHT click on the update.xml file
  10. Highlight Run As then click Ant build. Please observe, if you had to follow Advanced Ant Configuration instructions above you will have to do the same here.
  11. Wait while Eclipse builds the Earth Science data sets
    This step may take up to 30 minutes
  12. In Run Configurations select the Plug-ins tab and make sure all required years of org.eclipse.stem.internal.data.geography.earthscience are selected


Old Version

Back to the top